Kurz: Vytvoření minimálního rozhraní API s ASP.NET Core

Autor: Wade Pickett a Tom Dykstra

Minimální rozhraní API jsou navržená tak, aby vytvářela rozhraní API HTTP s minimálními závislostmi. Jsou ideální pro mikroslužby a aplikace, které chtějí do ASP.NET Core zahrnout jenom minimální soubory, funkce a závislosti.

V tomto kurzu se naučíte základy vytváření minimálního rozhraní API s ASP.NET Core. Dalším přístupem k vytváření rozhraní API v ASP.NET Core je použití kontrolerů. Nápovědu k výběru mezi minimálními rozhraními API a rozhraními API založenými na kontroleru najdete v přehledu rozhraní API. Kurz vytvoření projektu rozhraní API na základě kontrolerů , které obsahují další funkce, najdete v tématu Vytvoření webového rozhraní API.

Overview

Tento kurz vytvoří následující rozhraní API:

API	Description	Obsah požadavku	Tělo odpovědi
GET /todoitems	Získání všech položek úkolů	None	Pole položek úkolů
GET /todoitems/complete	Získejte dokončené úkoly	None	Pole položek úkolů
GET /todoitems/{id}	Získejte položku podle ID	None	Položka úkolu
POST /todoitems	Přidání nové položky	Položka úkolu	Položka úkolu
PUT /todoitems/{id}	Aktualizace existující položky	Položka úkolu	None
PATCH /todoitems/{id}	Částečné aktualizace položky	Částečný úkol k dokončení	None
DELETE /todoitems/{id}	Odstranění položky	None	None

Prerequisites

Visual Studio

• Nejnovější verze sady Visual Studio s úlohou vývoje pro ASP.NET a web .

  

Visual Studio Code

• Visual Studio Code
• C# Dev Kit pro Visual Studio Code
• .NET 10.0 SDK

Podle pokynů editoru Visual Studio Code můžete postupovat v systémech macOS, Linux nebo Windows. Pokud používáte integrované vývojové prostředí (IDE) jiné než Visual Studio Code, může se vyžadovat změny.

Vytvoření projektu rozhraní API

Visual Studio

• Spusťte Visual Studio 2026 a vyberte Vytvořit nový projekt.

• V dialogovém okně Vytvořit nový projekt :

  • Vyberte typ projektu základního webového rozhraní API ASP.NET a vyberte Další.
  • Pojmenujte projekt TodoApi a vyberte Další.

• V dialogovém okně Další informace :

  • Ověřte, že Framework je .NET 10.0 (dlouhodobá podpora).
  • Ověřte, že je zaškrtnuté políčko Povolit podporu OpenAPI.
  • Ověřte, že políčko Použít kontrolerynení zaškrtnuté. Zrušte zaškrtnutí tohoto nastavení, pokud chcete vytvořit minimální projekt rozhraní API podle potřeby pro tento kurz místo projektu založeného na kontroleru.
  • Vyberte Vytvořit.

  

Visual Studio Code

• Spusťte Visual Studio Code, vyberte Zobrazit a pak výběrem terminálu otevřete integrovaný terminál.
• Změňte adresář(cd) na složku, která obsahuje složku projektu.
• Spusťte následující příkazy:

  dotnet new webapi -o TodoApi
  cd TodoApi
  code -r ../TodoApi

• Když se zobrazí dialogové okno s dotazem, jestli chcete autorům důvěřovat, vyberte Ano.

• Když se zobrazí dialogové okno s dotazem, jestli chcete do projektu přidat požadované prostředky, vyberte Ano.

  Předchozí příkazy vytvoří nový projekt webového minimálního rozhraní API a otevře ho v editoru Visual Studio Code.

Kontrola kódu

Soubor Program.cs vygenerovaný šablonou obsahuje následující kód:

Visual Studio

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Visual Studio Code

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Předchozí kód:

• Vytvoří WebApplicationBuilder a WebApplication s předkonfigurovanými výchozími nastaveními.
• Zaregistruje integrovaný generátor dokumentu OpenAPI pomocí builder.Services.AddOpenApi().
• Namapuje vygenerovaný dokument OpenAPI na adrese /openapi/v1.json pomocí app.MapOpenApi() pouze v prostředí Development.
• Definuje ukázkový GET /weatherforecast koncový bod, který vrací pět náhodně generovaných WeatherForecast záznamů.

V tomto kurzu nahradíte WeatherForecast novou ukázkou Todo s koncovými body pro vytváření, čtení, aktualizaci a odstraňování položek, která využívá model a databázi.

Přidání balíčků NuGet

Přidejte balíčky NuGet pro podporu databáze použité v tomto kurzu.

Visual Studio

• V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat balíčky NuGet pro řešení.
• Vyberte kartu Procházet.
• Do vyhledávacího pole zadejte Microsoft.EntityFrameworkCore.InMemory a pak vyberte Microsoft.EntityFrameworkCore.InMemory.
• V pravém podokně zaškrtněte políčko Projekt a pak vyberte Nainstalovat.

Visual Studio Code

• Spusťte následující příkaz:

  dotnet add package Microsoft.EntityFrameworkCore.InMemory

Třídy kontextu modelu a databáze

• Ve složce projektu vytvořte soubor s názvem Todo.cs s následujícím kódem:

public class Todo
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
    public string? Secret { get; set; }
}

Předchozí kód vytvoří model pro tuto aplikaci. Model je třída, která představuje data, která aplikace spravuje.

Součástí Secret této vlastnosti je ukázka běžné potřeby reálného světa: data, která aplikace ukládá a používá interně, například ID uživatele, který položku vlastní, nechcete, aby klienti viděli nebo nastavili. V kroku Zabránění nadměrnému odesílání dat, který následuje později v tomto kurzu, použijete objekt pro přenos dat (DTO), aby se pole jako Secret neobjevovala ve vstupech a odpovědích rozhraní API.

• Vytvořte soubor s názvem TodoDb.cs s následujícím kódem:

using Microsoft.EntityFrameworkCore;

class TodoDb : DbContext
{
    public TodoDb(DbContextOptions<TodoDb> options)
        : base(options) { }

    public DbSet<Todo> Todos => Set<Todo>();
}

Předchozí kód definuje kontext databáze, což je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je odvozena od Microsoft.EntityFrameworkCore.DbContext třídy.

Aplikace používá databázi v paměti s názvem TodoList. Databáze se později zaregistruje v Program.cs pomocí builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));, kde řetězec "TodoList" představuje název databáze. Vzhledem k tomu, že data jsou uložená v paměti, obnoví se při každém restartování aplikace.

Nahraďte ukázku WeatherForecast rozhraním Todo API

Šablona webapi přidá do Program.cs ukázkový koncový bod GET /weatherforecast a na konci souboru záznam WeatherForecast. Ukázka je pouze zástupný text, který ukazuje, že šablona funguje – oba nahraďte koncovými body Todo popsanými v následující části.

• Nahraďte veškerý kód Program.cs následujícím kódem. Ukázkový WeatherForecast endpoint a záznam jsou odstraněny a nahrazují je endpointy Todo:

Visual Studio

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

app.Run();

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

app.Run();

Vložený kód také obsahuje using Scalar.AspNetCore; a app.MapScalarApiReference();, který přidá uživatelské rozhraní prohlížeče pro testování rozhraní API. Balíček Scalar pro tyto řádky nakonfigurujete později v tomto kurzu v části Přidání uživatelského rozhraní prohlížeče pro zobrazení dokumentu OpenAPI. Projekt se do té doby nevytvoře.

Řádky OpenAPI, které šablona přidá (builder.Services.AddOpenApi() a app.MapOpenApi()) zůstanou na místě. Nyní popisují endpointy Todo místo ukázkového endpointu pro počasí.

Následující zvýrazněný kód zaregistruje služby aplikace v kontejneru injektáže závislostí (DI): kontext databáze (AddDbContext) a generátor dokumentů OpenAPI (AddOpenApi):

Visual Studio

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

Visual Studio Code

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

Kontejner DI poskytuje přístup k kontextu databáze a dalším službám.

Visual Studio

V tomto kurzu se k otestování rozhraní API používá Průzkumník koncových bodů a soubory .http.

Visual Studio Code

Přidání uživatelského rozhraní prohlížeče pro zobrazení dokumentu OpenAPI

Šablona již vygeneruje dokument OpenAPI na adrese /openapi/v1.json. Pokud chcete rozhraní API prozkoumat a otestovat v prohlížeči, přidejte uživatelské rozhraní, které tento dokument využívá. V tomto kurzu se používá Scalar.

Přidejte balíček Scalar.AspNetCore , který poskytuje middleware, který obsluhuje uživatelské rozhraní:

• Spusťte následující příkaz:

  dotnet add package Scalar.AspNetCore

V tomto kurzu se scalar používá pouze pro referenční middleware rozhraní API, který čte dokument OpenAPI vygenerovaný voláními AddOpenApi a MapOpenApi.

Potvrďte, že Program.cs obsahuje zvýrazněný řádek MapScalarApiReference uvnitř bloku if (app.Environment.IsDevelopment()), hned za řádkem app.MapOpenApi();, a že using Scalar.AspNetCore; je na začátku souboru. Tyto řádky jste přidali při vložení kódu todo dříve.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

Předchozí kód umožňuje pouze skalární uživatelské rozhraní ve vývoji. Čte /openapi/v1.json, dokument vytvořený nástrojem MapOpenApi(), a zpřístupňuje referenční dokumentaci API na adrese /scalar/v1. Nezapomeňte přidat using Scalar.AspNetCore; na začátek souboru.

Note

Skalární je jednou z několika možností uživatelského rozhraní OpenAPI. Alternativy, jako jsou NSwag.AspNetCore nebo Swashbuckle.AspNetCore.SwaggerUi, využívají stejný dokument OpenAPI a lze je použít místo nástroje Scalar beze změny zbytku tohoto kurzu.

Testování zveřejňování dat

Následující kód v Program.cs vytvoří HTTP POST koncový bod /todoitems, který přidá data do paměťové databáze:

Visual Studio

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

Visual Studio Code

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

Visual Studio

• Stisknutím kláves Ctrl+F5 spusťte aplikaci bez ladění. Visual Studio spustí Kestrel webový server a v případě potřeby důvěřuje vývojovému certifikátu.

Visual Studio zobrazí následující dialogové okno:

Pokud důvěřujete certifikátu SSL služby IIS Express, vyberte Ano .

Zobrazí se následující dialogové okno:

Pokud souhlasíte s tím, že se má důvěřovat vývojovému certifikátu, vyberte Ano.

Informace o tom, jak důvěřovat prohlížeči Firefox, naleznete v části k chybě certifikátu Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Pomocí koncového bodu POST přidejte data do aplikace.

• Vyberte Zobrazit>Další okna>Průzkumník koncových bodů.

• Klikněte pravým tlačítkem na koncový bod POST a vyberte Vygenerovat požadavek.

  

  Ve složce projektu s názvem TodoApi.httpse vytvoří nový soubor s podobným obsahem jako v následujícím příkladu:

  @TodoApi_HostAddress = https://localhost:7031

  POST {{TodoApi_HostAddress}}/todoitems

  ###

• První řádek vytvoří proměnnou, která se použije pro všechny koncové body.

• Další řádek definuje požadavek POST.

• Řádek s trojitým hashtagem (###) je značka oddělující požadavek: co následuje za ní, je určené pro jiný požadavek.

• Požadavek POST potřebuje hlavičky a text. Pokud chcete definovat tyto části požadavku, přidejte následující řádky bezprostředně za řádek požadavku POST:

  Content-Type: application/json

  {
    "name":"walk dog",
    "isComplete":true
  }

Předchozí kód přidá hlavičku Content-Type a text požadavku JSON. Soubor TodoApi.http by teď měl vypadat jako v následujícím příkladu, ale s číslem portu:

  @TodoApi_HostAddress = https://localhost:7057

  POST {{TodoApi_HostAddress}}/todoitems
  Content-Type: application/json

  {
    "name":"walk dog",
    "isComplete":true
  }

  ###

• Vyberte odkaz Odeslat žádost, který je nad řádkem POST žádosti.

  

  Požadavek POST se odešle do aplikace a odpověď se zobrazí v podokně Odpovědi .

  

Visual Studio Code

• Důvěřovat vývojovému certifikátu HTTPS spuštěním následujícího příkazu:

  dotnet dev-certs https --trust
  

  Předchozí příkaz zobrazí následující dialogové okno za předpokladu, že certifikát nebyl dříve důvěryhodný:

  

• Pokud souhlasíte s tím, že se má důvěřovat vývojovému certifikátu, vyberte Ano.

  Další informace najdete v části Důvěřujte vývojovému certifikátu HTTPS pro ASP.NET Core článku Vynucení SSL.

Informace o tom, jak důvěřovat prohlížeči Firefox, naleznete v části k chybě certifikátu Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

• V editoru Visual Studio Code spusťte aplikaci bez ladění stisknutím kláves Ctrl+F5 (Windows) nebo Control+F5 (macOS).

• Zobrazí se výzva k výběru ladicího programu. Vyberte C#.

• Zobrazí se výzva k výběru konfigurace spuštění. Vyberte C#:TodoApi [Výchozí konfigurace] TodoApi

  

Aplikace TodoApi se spustí a naslouchá na náhodně přiřazeném místním portu. Na panelu Terminálu vyhledejte Now listening on: řádek pro získání adresy URL a portu, například:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5090

V tomto příkladu TodoApi aplikace naslouchá na http://localhost:5090, takže port je 5090. Číslo vašeho portu se pravděpodobně liší.

• Pokud chcete aplikaci otevřít ve výchozím prohlížeči, podržte Ctrl (Windows) nebo Cmd (macOS) a vyberte adresu URL na Now listening on: řádku na panelu Terminálu. Prohlížeč se otevře v kořenovém adresáři http://localhost:{port}aplikace.

• V adresním řádku prohlížeče připojte /scalar/v1 k adrese URL, aby se zobrazila referenční stránka rozhraní API vygenerovaná skalárem, například http://localhost:5090/scalar/v1.

• Na skalární stránce vyberte operaci POST /todoitems a pak vyberte Testovací požadavek.

• Do těla požadavku zadejte JSON pro položku úkolu, aniž byste zadali volitelný id:

  {
    "name":"walk dog",
    "isComplete":true
  }

• Vyberte Odeslat.

Skalární uživatelské rozhraní zobrazí odpověď, včetně stavového kódu a textu odpovědi. Text odpovědi ukazuje:

• id je nastavena na 1.
• Vrátí se stavový kód 201 HTTP , který značí, že požadavek byl úspěšně zpracován a výsledkem vytvoření nového prostředku.

Prozkoumání koncových bodů GET

Vaše Program.cs zahrnuje několik koncových bodů GET definovaných pomocí MapGet:

API	Description	Obsah požadavku	Tělo odpovědi
GET /todoitems	Získání všech položek úkolů	None	Pole položek úkolů
GET /todoitems/complete	Získání všech dokončených položek úkolů	None	Pole položek úkolů
GET /todoitems/{id}	Získejte položku podle ID	None	Položka úkolu

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

Testování koncových bodů GET

Visual Studio

Otestujte aplikaci voláním GET koncových bodů z prohlížeče nebo pomocí Průzkumníka koncových bodů. Následující kroky jsou určené pro Průzkumníka koncových bodů.

• V Průzkumníku koncových bodů klikněte pravým tlačítkem na první koncový bod GET a vyberte Vygenerovat požadavek.

  Do souboru TodoApi.http byl přidán následující obsah:

  GET {{TodoApi_HostAddress}}/todoitems

  ###

• Vyberte odkaz Odeslat žádost, který je nad novým GET řádkem žádosti.

  Požadavek GET se odešle do aplikace a odpověď se zobrazí v podokně Odpovědi .

• Text odpovědi je podobný následujícímu formátu JSON:

  [
    {
      "id": 1,
      "name": "walk dog",
      "isComplete": true,
      "secret": null
    }
  ]

• V Průzkumníku koncových bodů klikněte pravým tlačítkem na /todoitems/{id}koncový bod GET a vyberte Vygenerovat požadavek. Do souboru TodoApi.http byl přidán následující obsah:

  GET {{TodoApi_HostAddress}}/todoitems/{id}

  ###

• Nahraďte {id} s 1.

• Vyberte odkaz Odeslat požadavek, který je nad novým řádkem požadavku GET.

  Požadavek GET se odešle do aplikace a odpověď se zobrazí v podokně Odpovědi .

• Text odpovědi je podobný následujícímu formátu JSON:

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true,
    "secret": null
  }

Visual Studio Code

Otestujte aplikaci voláním koncových bodů z prohlížeče nebo skalárního uživatelského rozhraní.

• V skalárním uživatelském rozhraní vyberte GET /todoitems a pak vyberte Odeslat testovací požadavek>.

• Alternativně volejte GET /todoitems v prohlížeči zadáním adresy URI http://localhost:{port}/todoitems. Například: http://localhost:7032/todoitems.

Volání na GET /todoitems vytvoří odpověď podobnou následující:

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true,
    "secret": null
  }
]

• Zavolejte v nástroji Scalar GET /todoitems/{id}, aby se vrátila data pro konkrétní ID:

  • Vyberte GET /todoitems/{id} a pak vyberte Testovací požadavek.
  • Nastavte pole id na 1 a vyberte Odeslat.

• Případně můžete z prohlížeče zavolat GET /todoitems/{id} zadáním adresy URI http://localhost:{port}/todoitems/1. Například: http://localhost:7032/todoitems/1.

• Odpověď je podobná následující:

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true,
    "secret": null
  }

Tato aplikace používá databázi v paměti. Pokud aplikaci restartujete, data se ztratí: GET /todoitems vrátí prázdné pole ([]) a GET /todoitems/{id} vrátí hodnotu 404 Not Found. Pokud chcete aplikaci znovu naplnit, post data do aplikace a zkuste požadavek GET znovu.

Návratové hodnoty

ASP.NET Core automaticky serializuje objekt do formátu JSON a zapíše json do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OK, za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

Návratové typy mohou představovat širokou škálu stavových kódů HTTP. Může například GET /todoitems/{id} vrátit dvě různé hodnoty stavu:

• Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby stavuNotFound 404.
• V opačném případě metoda vrátí hodnotu 200 s textem odpovědi JSON. Vrácení item vede k odpovědi HTTP 200.

Prozkoumání koncového bodu PUT

Ukázková aplikace implementuje jeden koncový bod PUT pomocí MapPut:

Visual Studio

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

Visual Studio Code

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

Tato metoda je podobná MapPost metodě, s výjimkou použití HTTP PUT. Úspěšná odpověď vrátí hodnotu 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte HTTP PATCH.

Testování koncového bodu PUT

Tato ukázka používá databázi v paměti, kterou musíte inicializovat při každém spuštění aplikace. Před voláním PUT potřebujete položku v databázi. Před voláním metody PUT zavolejte post a ujistěte se, že je v databázi položka.

Aktualizujte položku Todo, která má Id = 1, a nastavte její název na "feed fish".

Visual Studio

• V Průzkumníku koncových bodů klikněte pravým tlačítkem myši na koncový bod PUT a vyberte Vygenerovat požadavek.

  Do souboru TodoApi.http byl přidán následující obsah:

  PUT {{TodoApi_HostAddress}}/todoitems/{id}

  ###

• Na řádku požadavku PUT nahraďte {id} s 1.

• Přidejte následující řádky bezprostředně za řádek požadavku PUT:

  Content-Type: application/json

  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }

Předchozí kód přidá hlavičku Content-Type a text požadavku JSON.

• Vyberte odkaz Odeslat žádost, který je nad novým řádkem požadavku PUT.

Visual Studio Code

K odeslání požadavku PUT použijte skalární uživatelské rozhraní:

• Vyberte PUT /todoitems/{id} a pak vyberte Testovací požadavek.

• Nastavte pole ID na hodnotu 1.

• Nastavte text požadavku na následující JSON:

  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }

• Vyberte Odeslat.

Požadavek PUT se odešle do aplikace a odpověď se zobrazí v podokně Odpovědi . Tělo odpovědi je prázdné a stavový kód je 204.

Vytvoření a prozkoumání koncového bodu PATCH

Koncový bod PATCH umožňuje klientům odesílat pouze pole, která chtějí aktualizovat, například přejmenování položky seznamu úkolů bez opětovného odeslání stavu dokončení. Tento přístup se liší od požadavku PUT, který nahrazuje celou položku, takže klient musí odesílat všechna pole, i když se změní jenom jedno.

V dalších krocích přidáte nový soubor a upravíte soubor Program.cs. Před provedením těchto změn zastavte aplikaci TodoApi. Nechte skalární stránku v prohlížeči spuštěnou.

Visual Studio

• Pokud chcete aplikaci zastavit, vyberte na panelu nástrojů Visual Studio tlačítko Zastavit (červený čtverec).

Visual Studio Code

• Pokud chcete aplikaci zastavit, stiskněte Shift+F5.

Tato ukázka používá databázi v paměti, kterou musíte inicializovat při každém spuštění aplikace. Databáze musí obsahovat položku před voláním PATCH. Před voláním funkce PATCH zavolejte post a ujistěte se, že databáze obsahuje položku.

Koncový bod PATCH používá třídu s vlastnostmi s možnou TodoPatchDto hodnotou null ke správnému zpracování částečných aktualizací. Použitím nulovatelných vlastností může endpoint rozlišovat mezi polem, které nebylo zadáno (null), a polem explicitně nastaveným na hodnotu (včetně hodnoty false u booleovských polí). Bez vlastností s možnou hodnotou null má nenulovatelná hodnota typu bool ve výchozím stavu hodnotu false, což by mohlo nechtěně přepsat existující hodnotu true, když toto pole není zahrnuto v požadavku.

• Vytvořte soubor s názvem TodoPatchDto.cs s následujícím kódem:

public class TodoPatchDto
{
    public string? Name { get; set; }
    public bool? IsComplete { get; set; }
}

Třída TodoPatchDto používá vlastnosti s možnou hodnotou null (string? a bool?) k rozlišení mezi polem, které nebylo zadané v požadavku, a pole explicitně nastavené na hodnotu.

• Do Program.cs přidejte následující koncový bod PATCH bezprostředně za koncový bod MapPut:

Visual Studio

app.MapPatch("/todoitems/{id}", async (int id, TodoPatchDto inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

Visual Studio Code

app.MapPatch("/todoitems/{id}", async (int id, TodoPatchDto inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

Tato metoda je podobná MapPut metodě, ale používá http PATCH a aktualizuje pouze pole uvedená v požadavku. Úspěšná odpověď vrátí hodnotu 204 (bez obsahu).

Note

Operace PATCH umožňují částečné aktualizace prostředků. Pokročilejší částečné aktualizace pomocí dokumentů OPRAV JSON najdete v tématu JsonPatch ve webovém rozhraní API ASP.NET Core.

Otestujte koncový bod PATCH

Visual Studio

• Stisknutím kombinace kláves Ctrl+F5 znovu sestavte a spusťte aplikaci s novým koncovým bodem PATCH.

Visual Studio Code

• Spusťte aplikaci znovu, aby se znovu sestavovala s novým koncovým bodem PATCH. V editoru Visual Studio Code spusťte aplikaci bez ladění stisknutím kláves Ctrl+F5 (Windows) nebo Control+F5 (macOS).

Tato ukázka používá databázi v paměti, kterou musíte inicializovat při každém spuštění aplikace. Databáze musí obsahovat položku před voláním PATCH. Voláním metody POST se ujistěte, že databáze má položku před voláním PATCH.

Aktualizujte pouze vlastnost name položky Todo, která má Id = 1, a nastavte její název na "run errands".

Visual Studio

• V Průzkumníku koncových bodů vyberte tlačítko Aktualizovat. Potom klikněte pravým tlačítkem na koncový bod PATCH a vyberte Vygenerovat požadavek.

  Do souboru TodoApi.http byl přidán následující obsah:

  PATCH {{TodoApi_HostAddress}}/todoitems/{id}

  ###

• Na řádku požadavku PATCH nahraďte {id} za 1.

• Přidejte následující řádky bezprostředně za řádek žádosti PATCH:

  Content-Type: application/json

  {
    "name": "run errands"
  }

Předchozí kód přidá hlavičku Content-Type a text požadavku JSON pouze s polem, které se má aktualizovat.

• Vyberte odkaz Odeslat požadavek , který je nad novým řádkem žádosti PATCH.

Visual Studio Code

K odeslání požadavku PATCH použijte skalární uživatelské rozhraní:

• Aktualizujte skalární stránku v prohlížeči tak, aby se zobrazil nový PATCH koncový bod.

• Vyberte PATCH /todoitems/{id} a pak vyberte Testovací požadavek.

• Nastavte pole ID na hodnotu 1.

• Nastavte text požadavku na následující JSON:

  {
    "name": "run errands"
  }

• Vyberte Odeslat.

Požadavek PATCH se odešle do aplikace a odpověď se zobrazí v podokně Odpovědi . Tělo odpovědi je prázdné a stavový kód je 204.

Prozkoumání koncového bodu DELETE

Váš Program.cs soubor obsahuje jeden koncový bod DELETE definovaný pomocí MapDelete:

Visual Studio

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

Visual Studio Code

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

Testování koncového bodu DELETE

Visual Studio

• V Průzkumníku koncových bodů klikněte pravým tlačítkem na koncový bod DELETE a vyberte Vygenerovat požadavek.

  Přidá se DELETE požadavek k TodoApi.http.

• Nahraďte {id} v řádku žádosti DELETE textem 1. Požadavek DELETE by měl vypadat jako v následujícím příkladu:

  DELETE {{TodoApi_HostAddress}}/todoitems/1

  ###

• Vyberte odkaz Odeslat žádost pro požadavek DELETE.

Visual Studio Code

K odeslání požadavku DELETE použijte skalární uživatelské rozhraní:

• Vyberte DELETE /todoitems/{id} a pak testovací požadavek.
• Nastavte pole id na 1 a vyberte možnost Odeslat.

Požadavek DELETE se odešle do aplikace a odpověď se zobrazí v podokně Odpovědi . Tělo odpovědi je prázdné a stavový kód je 204.

Použití rozhraní MapGroup API

• Další kroky upraví Program.cs soubor, proto aplikaci před provedením těchto změn zastavte. Nechte stránku Scalar otevřenou v prohlížeči.

Visual Studio

• Pokud chcete aplikaci zastavit, vyberte na panelu nástrojů Visual Studio tlačítko Zastavit (červený čtverec).

Visual Studio Code

• Pokud chcete aplikaci zastavit, stiskněte Shift+F5.

Soubor Program.cs, který jste napsali, opakuje při každém nastavení endpointu předponu adresy URL todoitems. Rozhraní API často obsahují skupiny koncových bodů s běžnou předponou adresy URL a MapGroup metoda pomáhá tyto skupiny uspořádat. Redukuje opakující se kód a umožňuje přizpůsobit celé skupiny koncových bodů jediným voláním metod, jako a RequireAuthorizationWithMetadata.

• Program.cs Obsah nahraďte následujícím kódem:

Visual Studio

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", async (TodoDb db) =>
    await db.Todos.ToListAsync());

todoItems.MapGet("/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

todoItems.MapGet("/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

todoItems.MapPost("/", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

todoItems.MapPut("/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

todoItems.MapPatch("/{id}", async (int id, TodoPatchDto inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

todoItems.MapDelete("/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

app.Run();

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", async (TodoDb db) =>
    await db.Todos.ToListAsync());

todoItems.MapGet("/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

todoItems.MapGet("/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

todoItems.MapPost("/", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

todoItems.MapPut("/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

todoItems.MapPatch("/{id}", async (int id, TodoPatchDto inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

todoItems.MapDelete("/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

app.Run();

Předchozí kód má následující změny:

• Přidá var todoItems = app.MapGroup("/todoitems"); k nastavení skupiny pomocí předpony adresy URL /todoitems.

• Změní všechny app.Map<HttpVerb> metody na todoItems.Map<HttpVerb>.

• Odebere předponu /todoitems adresy URL z Map<HttpVerb> volání metod.

• Spustí aplikaci a otestuje koncové body a ověří, že fungují stejně.

Použití rozhraní TypedResults API

Další kroky upraví Program.cs soubor, proto aplikaci před provedením těchto změn zastavte. Nechte stránku Scalar otevřenou v prohlížeči.

Vracení TypedResults místo Results má několik výhod, včetně testovatelnosti a automatického vracení metadat typu odpovědi pro OpenAPI k popisu koncového bodu. Další informace naleznete v tématu TypedResults vs Results.

• Metody Map<HttpVerb> mohou místo lambda volat metody obslužné rutiny trasy. Pokud chcete zobrazit příklad, aktualizujte Program.cs následujícím kódem:

Visual Studio

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

app.Run();

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(todo)
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(Todo todo, TodoDb db)
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return TypedResults.Created($"/todoitems/{todo.Id}", todo);
}

static async Task<IResult> UpdateTodo(int id, Todo inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

app.Run();

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(todo)
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(Todo todo, TodoDb db)
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return TypedResults.Created($"/todoitems/{todo.Id}", todo);
}

static async Task<IResult> UpdateTodo(int id, Todo inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

Kód Map<HttpVerb> teď volá metody místo lambda:

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

Následující metody vracejí objekty, které implementují IResult a jsou definovány TypedResults:

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(todo)
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(Todo todo, TodoDb db)
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return TypedResults.Created($"/todoitems/{todo.Id}", todo);
}

static async Task<IResult> UpdateTodo(int id, Todo inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

Testy jednotek mohou volat tyto metody a testovat, že vracejí správný datový typ. Například pokud je metoda GetAllTodos:

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.ToArrayAsync());
}

Kód unit testu může ověřit, že objekt typu Ok<Todo[]> je vrácen z metody obslužné rutiny. Například:

public async Task GetAllTodos_ReturnsOkOfTodosResult()
{
    // Arrange
    var db = CreateDbContext();

    // Act
    var result = await TodosApi.GetAllTodos(db);

    // Assert: Check for the correct returned type
    Assert.IsType<Ok<Todo[]>>(result);
}

Prevence nadměrného zadávání

V současné době vaše rozhraní API zpřístupňuje celý Todo objekt, včetně Secret vlastnosti, kterou jste přidali do tříd kontextu modelu a databáze. V produkčních aplikacích použijte podmnožinu modelu k omezení dat, která můžou klienti zadávat a přijímat. Hlavním důvodem tohoto omezení je zabezpečení. Tato podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. Tento článek používá DTO.

Použijte DTO k těmto účelům:

• Zabránit nadměrnému odesílání dat.
• Skryjte vlastnosti, které klienti nemají zobrazit.
• Vynechejte některé vlastnosti pro zmenšení velikosti datové části.
• Zplošťujte grafy objektů, které obsahují vnořené objekty. Grafy plochých objektů můžou být pro klienty pohodlnější.

Tato aplikace potřebuje skrýt Secret pole, ale aplikace pro správu by se mohla rozhodnout, že ho zveřejní.

• Další kroky přidají soubor, proto aplikaci před provedením těchto změn zastavte. Nechte stránku scalar otevřenou v prohlížeči.

• Vytvořte soubor s názvem TodoItemDTO.cs s následujícím kódem:

public class TodoItemDTO
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }

    public TodoItemDTO() { }
    public TodoItemDTO(Todo todoItem) =>
    (Id, Name, IsComplete) = (todoItem.Id, todoItem.Name, todoItem.IsComplete);
}

• Program.cs Obsah souboru nahraďte následujícím kódem, který použije tento model DTO:

Visual Studio

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

app.Run();

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Select(x => new TodoItemDTO(x)).ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).Select(x => new TodoItemDTO(x)).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(new TodoItemDTO(todo))
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(TodoItemDTO todoItemDTO, TodoDb db)
{
    var todoItem = new Todo
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

    db.Todos.Add(todoItem);
    await db.SaveChangesAsync();

    todoItemDTO = new TodoItemDTO(todoItem);

    return TypedResults.Created($"/todoitems/{todoItem.Id}", todoItemDTO);
}

static async Task<IResult> UpdateTodo(int id, TodoItemDTO todoItemDTO, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = todoItemDTO.Name;
    todo.IsComplete = todoItemDTO.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

app.Run();

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Select(x => new TodoItemDTO(x)).ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).Select(x => new TodoItemDTO(x)).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(new TodoItemDTO(todo))
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(TodoItemDTO todoItemDTO, TodoDb db)
{
    var todoItem = new Todo
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

    db.Todos.Add(todoItem);
    await db.SaveChangesAsync();

    todoItemDTO = new TodoItemDTO(todoItem);

    return TypedResults.Created($"/todoitems/{todoItem.Id}", todoItemDTO);
}

static async Task<IResult> UpdateTodo(int id, TodoItemDTO todoItemDTO, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = todoItemDTO.Name;
    todo.IsComplete = todoItemDTO.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

• Spusťte aplikaci a ověřte, že můžete odesílat a získat všechna pole s výjimkou pole Secret.

Řešení potíží s dokončeným příkladem

Pokud narazíte na problém, který nemůžete vyřešit, porovnejte kód s dokončeným projektem. Zobrazit nebo stáhnout dokončený projekt (jak stáhnout)

Další kroky

• Nakonfigurujte možnosti serializace JSON.
• Zpracování chyb a výjimek: Ve výchozím nastavení je stránka výjimky vývojáře povolená v Development prostředí pro minimální aplikace API. Informace o zpracování chyb a výjimek najdete v tématu Zpracování chyb v rozhraních ASP.NET Core API.
• Příklad testování minimální aplikace API najdete v této ukázce GitHubu.
• Podpora OpenAPI v minimálních rozhraních API
• Rychlý start: Publikování do Azure
• Uspořádání minimalních rozhraní API ASP.NET Core

Learn more

Stručné referenční informace k minimálním rozhraním API