Esercitazione: Creare un'API minima con ASP.NET Core

Di Rick Anderson e Tom Dykstra

Le API minime sono progettata per creare API HTTP con dipendenze minime. Sono ideali per microservizi e app che vogliono includere solo i file, le funzionalità e le dipendenze minimi in ASP.NET Core.

Questa esercitazione illustra le nozioni di base per la creazione di un'API minima con ASP.NET Core. Un altro approccio alla creazione di API in ASP.NET Core consiste nell'usare i controller. Per informazioni sulla scelta tra API minime e API basate su controller, vedere Panoramica delle API. Per un'esercitazione sulla creazione di un progetto API basato su controller che contengono altre funzionalità, vedere Creare un'API Web.

Panoramica

Questa esercitazione consente di creare l'API seguente:

API	Descrizione	Corpo della richiesta	Corpo della risposta
GET /todoitems	Ottiene tutti gli elementi attività	None	Matrice di elementi attività
GET /todoitems/complete	Ottenere gli elementi attività completati	None	Matrice di elementi attività
GET /todoitems/{id}	Ottiene un elemento in base all'ID	None	Elemento attività
POST /todoitems	Aggiunge un nuovo elemento	Elemento attività	Elemento attività
PUT /todoitems/{id}	Aggiorna un elemento esistente	Elemento attività	None
DELETE /todoitems/{id}	Elimina un elemento	None	None

Prerequisiti

Visual Studio

• Visual Studio 2022 con il carico di lavoro Sviluppo ASP.NET e Web.

  

Visual Studio Code

• Visual Studio Code
• C# per Visual Studio Code (versione più recente)
• .NET 8.0 SDK

Le istruzioni di Visual Studio Code usano l'interfaccia della riga di comando di .NET per le funzioni di sviluppo di ASP.NET Core, ad esempio la creazione di progetti. È possibile seguire queste istruzioni in macOS, Linux o Windows e con qualsiasi editor di codice. Se si usa un editor diverso da Visual Studio Code potrebbero essere necessarie alcune modifiche minime.

Creare un progetto API

Visual Studio

• Avviare Visual Studio 2022 e selezionare Crea un nuovo progetto.

• Nella finestra di dialogo Crea un nuovo progetto:

  • Immettere Empty nella casella di ricerca Cerca modelli .
  • Selezionare il modello core vuoto ASP.NET e selezionare Avanti.

  

• Assegnare al progetto il nome TodoApi e selezionare Avanti.

• Nella finestra di dialogo Informazioni aggiuntive:

  • Selezionare .NET 8.0 (supporto a lungo termine)
  • Deselezionare Non usare istruzioni di primo livello
  • Selezionare Crea.

  

Visual Studio Code

• Aprire il terminale integrato.

• Cambiare directory (cd) e passare alla cartella che conterrà la cartella del progetto.

• Eseguire i comandi seguenti:

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

• Quando una finestra di dialogo chiede se si vuole considerare attendibili gli autori, selezionare Sì.

• Quando una finestra di dialogo chiede se si vuole aggiungere gli asset necessari al progetto, selezionare Sì.

  I comandi precedenti creano un nuovo progetto API Web minimo e lo aprono in Visual Studio Code.

Esaminare il codice

Il Program.cs file contiene il codice seguente:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Il codice precedente:

• Crea un WebApplicationBuilder oggetto e con WebApplication impostazioni predefinite preconfigurate.
• Crea un endpoint / HTTP GET che restituisce Hello World!:

Eseguire l'app

Visual Studio

Premere CTRL+F5 per l'esecuzione senza il debugger.

Visual Studio visualizza la finestra di dialogo seguente:

Selezionare Sì se si considera attendibile il certificato SSL di IIS Express.

Verrà visualizzata la finestra di dialogo seguente:

Selezionare Sì se si accetta di considerare attendibile il certificato di sviluppo.

Per informazioni sull'attendibilità del browser Firefox, vedere Firefox SEC_ERROR_INADEQUATE_KEY_USAGE errore del certificato.

Visual Studio avvia il Kestrel server Web e apre una finestra del browser.

Hello World! viene visualizzato nel browser. Il Program.cs file contiene un'app minima ma completa.

Chiudere la finestra del browser.

Visual Studio Code

• Considerare attendibile il certificato di sviluppo HTTPS eseguendo il comando riportato di seguito:

  dotnet dev-certs https --trust
  

  Il comando precedente richiede .NET 9 SDK o versione successiva in Linux. Per Linux in .NET 8.0.401 SDK e versioni precedenti, vedere la documentazione della distribuzione linux per considerare attendibile un certificato.

  Il comando precedente visualizza la finestra di dialogo seguente, purché il certificato non sia stato considerato attendibile in precedenza:

  

• Selezionare Sì se si accetta di considerare attendibile il certificato di sviluppo.

  Per altre informazioni, vedere la sezione Considerare attendibile il certificato di sviluppo HTTPS di base ASP.NET dell'articolo Applicazione di SSL .

Per informazioni sull'attendibilità del browser Firefox, vedere Firefox SEC_ERROR_INADEQUATE_KEY_USAGE errore del certificato.

In Visual Studio Code premere CTRL+F5 (Windows) o controllare+F5 (macOS) per eseguire l'app senza eseguire il debug.

Il browser predefinito viene avviato con l'URL seguente: https://localhost:<port> dove <port> è il numero di porta generato in modo casuale.

Chiudere la finestra del browser.

In Visual Studio Code scegliere Arresta debug dal menu Esegui o premere MAIUSC+F5 per arrestare l'app.

Aggiungere i pacchetti NuGet di

I pacchetti NuGet devono essere aggiunti per supportare il database e la diagnostica usati in questa esercitazione.

Visual Studio

• Scegliere NuGet Gestione pacchetti > Gestisci pacchetti NuGet per la soluzione dal menu Strumenti.
• Selezionare la scheda Sfoglia.
• Immettere Microsoft.EntityFrameworkCore.InMemory nella casella di ricerca e quindi selezionare Microsoft.EntityFrameworkCore.InMemory.
• Selezionare la casella di controllo Progetto nel riquadro destro e quindi selezionare Installa.
• Seguire le istruzioni precedenti per aggiungere il Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore pacchetto.

Visual Studio Code

• Eseguire i comandi seguenti:

  dotnet add package Microsoft.EntityFrameworkCore.InMemory
  dotnet add package Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore
  

Classi di contesto del modello e del database

• Nella cartella del progetto creare un file denominato Todo.cs con il codice seguente:

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

Il codice precedente crea il modello per questa app. Un modello è una classe che rappresenta i dati gestiti dall'app.

• Creare un file denominato TodoDb.cs con il codice seguente:

using Microsoft.EntityFrameworkCore;

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

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

Il codice precedente definisce il contesto del database, ovvero la classe principale che coordina la funzionalità di Entity Framework per un modello di dati. Tale classe deriva dalla classe Microsoft.EntityFrameworkCore.DbContext.

Aggiungere il codice API

• Sostituire il contenuto del file Program.cs con il codice seguente:

using Microsoft.EntityFrameworkCore;

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

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();

Il codice evidenziato seguente aggiunge il contesto del database al contenitore di inserimento delle dipendenze e consente di visualizzare le eccezioni correlate al database:

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

Il contenitore DI fornisce l'accesso al contesto del database e ad altri servizi.

Visual Studio

Questa esercitazione usa Endpoints Explorer e i file con estensione http per testare l'API.

Visual Studio Code

Creare un'interfaccia utente di test dell'API con Swagger

Sono disponibili molti strumenti di test dell'API Web tra cui scegliere ed è possibile seguire questa procedura di test introduttiva dell'API con il proprio strumento preferito.

Questa esercitazione usa il pacchetto .NET NSwag.AspNetCore, che integra gli strumenti Swagger per generare un'interfaccia utente di test aderendo alla specifica OpenAPI:

• NSwag: libreria .NET che integra Swagger direttamente nelle applicazioni ASP.NET Core, fornendo middleware e configurazione.
• Swagger: set di strumenti open source come OpenAPIGenerator e SwaggerUI che generano pagine di test api che seguono la specifica OpenAPI.
• Specifica OpenAPI: documento che descrive le funzionalità dell'API, in base alle annotazioni XML e attributi all'interno dei controller e dei modelli.

Per altre informazioni sull'uso di OpenAPI e NSwag con ASP.NET, vedere la documentazione dell'API Web di ASP.NET Core con Swagger/OpenAPI.

Installare gli strumenti di Swagger

• Esegui questo comando:

  dotnet add package NSwag.AspNetCore
  

Il comando precedente aggiunge il pacchetto NSwag.AspNetCore , che contiene strumenti per generare documenti e interfaccia utente di Swagger.

Configurare il middleware Swagger

• Aggiungere il codice evidenziato seguente prima app di essere definito nella riga var app = builder.Build();

  using NSwag.AspNetCore;
  using Microsoft.EntityFrameworkCore;
  
  var builder = WebApplication.CreateBuilder(args);
  builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
  builder.Services.AddDatabaseDeveloperPageExceptionFilter();
  
  builder.Services.AddEndpointsApiExplorer();
  builder.Services.AddOpenApiDocument(config =>
  {
      config.DocumentName = "TodoAPI";
      config.Title = "TodoAPI v1";
      config.Version = "v1";
  });
  var app = builder.Build();
  

Nel codice precedente:

• builder.Services.AddEndpointsApiExplorer();: abilita Esplora API, ovvero un servizio che fornisce metadati sull'API HTTP. Esplora API viene usato da Swagger per generare il documento Swagger.

• builder.Services.AddOpenApiDocument(config => {...});: aggiunge il generatore di documenti OpenAPI di Swagger ai servizi dell'applicazione e lo configura per fornire altre informazioni sull'API, ad esempio il titolo e la versione. Per informazioni dettagliate sull'API più affidabile, vedere Introduzione a NSwag e ASP.NET Core

• Aggiungere il codice evidenziato seguente alla riga successiva dopo app la definizione nella riga var app = builder.Build();

  var app = builder.Build();
  if (app.Environment.IsDevelopment())
  {
      app.UseOpenApi();
      app.UseSwaggerUi(config =>
      {
          config.DocumentTitle = "TodoAPI";
          config.Path = "/swagger";
          config.DocumentPath = "/swagger/{documentName}/swagger.json";
          config.DocExpansion = "list";
      });
  }
  

  Il codice precedente abilita il middleware Swagger per gestire il documento JSON generato e l'interfaccia utente di Swagger. Swagger è abilitato solo in un ambiente di sviluppo. L'abilitazione di Swagger in un ambiente di produzione potrebbe esporre dettagli potenzialmente sensibili sulla struttura e l'implementazione dell'API.

Testare i dati di registrazione

Il codice seguente in Program.cs crea un endpoint /todoitems HTTP POST che aggiunge dati al database in memoria:

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

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

Eseguire l'app. Il browser visualizza un errore 404 perché non è più presente un / endpoint.

L'endpoint POST verrà usato per aggiungere dati all'app.

Visual Studio

• Selezionare Visualizza>altri endpoint di Windows>Explorer.

• Fare clic con il pulsante destro del mouse sull'endpoint POST e scegliere Genera richiesta.

  

  Viene creato un nuovo file nella cartella di progetto denominata TodoApi.http, con contenuto simile all'esempio seguente:

  @TodoApi_HostAddress = https://localhost:7031
  
  Post {{TodoApi_HostAddress}}/todoitems
  
  ###
  

  • La prima riga crea una variabile usata per tutti gli endpoint.
  • La riga successiva definisce una richiesta POST.
  • La riga triple hashtag (###) è un delimitatore di richiesta: ciò che viene dopo è per una richiesta diversa.

• La richiesta POST richiede intestazioni e corpo. Per definire le parti della richiesta, aggiungere le righe seguenti immediatamente dopo la riga di richiesta POST:

  Content-Type: application/json
  
  {
    "name":"walk dog",
    "isComplete":true
  }
  

  Il codice precedente aggiunge un'intestazione Content-Type e un corpo della richiesta JSON. Il file TodoApi.http dovrebbe ora essere simile all'esempio seguente, ma con il numero di porta:

  @TodoApi_HostAddress = https://localhost:7057
  
  Post {{TodoApi_HostAddress}}/todoitems
  Content-Type: application/json
  
  {
    "name":"walk dog",
    "isComplete":true
  }
  
  ###
  

• Eseguire l'app.

• Selezionare il collegamento Invia richiesta sopra la riga della POST richiesta.

  

  La richiesta POST viene inviata all'app e la risposta viene visualizzata nel riquadro Risposta .

  

Visual Studio Code

• Con l'app ancora in esecuzione, nel browser passare a https://localhost:<port>/swagger per visualizzare la pagina di test dell'API generata da Swagger.

  

• Nella pagina di test dell'API Swagger selezionare Post /todoitems Try it (Pubblica /todoitems>Prova).

• Si noti che il campo Corpo della richiesta contiene un formato di esempio generato che riflette i parametri per l'API.

• Nel corpo della richiesta immettere JSON per un elemento attività, senza specificare il parametro facoltativo id:

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

• Seleziona Execute.

  

Swagger fornisce un riquadro Risposte sotto il pulsante Esegui .

Si notino alcuni dei dettagli utili:

• cURL: Swagger fornisce un comando cURL di esempio nella sintassi Unix/Linux, che può essere eseguito nella riga di comando con qualsiasi shell bash che usa la sintassi Unix/Linux, incluso Git Bash da Git per Windows.
• URL richiesta: rappresentazione semplificata della richiesta HTTP effettuata dal codice JavaScript dell'interfaccia utente di Swagger per la chiamata API. Le richieste effettive possono includere dettagli come intestazioni e parametri di query e un corpo della richiesta.
• Risposta del server: include il corpo e le intestazioni della risposta. Il corpo della risposta mostra che è id stato impostato su 1.
• Codice di risposta: è stato restituito un codice di stato 201 HTTP che indica che la richiesta è stata elaborata correttamente e ha generato la creazione di una nuova risorsa.

Esaminare gli endpoint GET

L'app di esempio implementa diversi endpoint GET chiamando MapGet:

API	Descrizione	Corpo della richiesta	Corpo della risposta
GET /todoitems	Ottiene tutti gli elementi attività	None	Matrice di elementi attività
GET /todoitems/complete	Ottenere tutti gli elementi attività completati	None	Matrice di elementi attività
GET /todoitems/{id}	Ottiene un elemento in base all'ID	None	Elemento attività

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());

Testare gli endpoint GET

Visual Studio

Testare l'app chiamando gli GET endpoint da un browser o usando Esplora endpoint. I passaggi seguenti sono relativi a Esplora endpoint.

• In Esplora endpoint fare clic con il pulsante destro del mouse sul primo endpoint GET e scegliere Genera richiesta.

  Al file viene aggiunto il TodoApi.http contenuto seguente:

  Get {{TodoApi_HostAddress}}/todoitems
  
  ###
  

• Selezionare il collegamento Invia richiesta sopra la nuova GET riga di richiesta.

  La richiesta GET viene inviata all'app e la risposta viene visualizzata nel riquadro Risposta .

• Il corpo della risposta è simile al codice JSON seguente:

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

• In Esplora endpoint fare clic con il pulsante destro del mouse sull'endpoint /todoitems/{id} GET e scegliere Genera richiesta. Al file viene aggiunto il TodoApi.http contenuto seguente:

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

• Sostituisci {id} con 1.

• Selezionare il collegamento Invia richiesta sopra la nuova riga di richiesta GET.

  La richiesta GET viene inviata all'app e la risposta viene visualizzata nel riquadro Risposta .

• Il corpo della risposta è simile al codice JSON seguente:

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

Visual Studio Code

Testare l'app chiamando gli endpoint da un browser o da Swagger.

• In Swagger selezionare GET /todoitems>Try it out>Execute (Esegui).

• In alternativa, chiamare GET /todoitems da un browser immettendo l'URI http://localhost:<port>/todoitems. Ad esempio, http://localhost:5001/todoitems

La chiamata a GET /todoitems produce una risposta simile alla seguente:

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

• Chiamare GET /todoitems/{id} in Swagger per restituire dati da un ID specifico:

  • Selezionare GET /todoitems>Try it (Prova).
  • Impostare il campo ID su 1 e selezionare Esegui.

• In alternativa, chiamare GET /todoitems da un browser immettendo l'URI https://localhost:<port>/todoitems/1. Ad esempio, https://localhost:5001/todoitems/1

• La risposta è simile alla seguente:

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

Questa app usa un database in memoria. Se l'app viene riavviata, la richiesta GET non restituisce dati. Se non vengono restituiti dati, i dati POST nell'app e riprovare la richiesta GET.

Valori restituiti

ASP.NET Core serializza automaticamente l'oggetto su JSON e scrive il codice JSON nel corpo del messaggio di risposta. Il codice di risposta per questo tipo restituito è 200 OK, presupponendo che non siano presenti eccezioni non gestite. Le eccezioni non gestite vengono convertite in errori 5xx.

I tipi restituiti possono rappresentare un'ampia gamma di codici di stato HTTP. Ad esempio, GET /todoitems/{id} può restituire due valori di stato diversi:

• Se nessun elemento corrisponde all'ID richiesto, il metodo restituisce un codice di errore di stato NotFound 404.
• In caso contrario, il metodo restituisce il codice 200 con un corpo della risposta JSON. La restituzione di item risulta in una risposta HTTP 200.

Esaminare l'endpoint PUT

L'app di esempio implementa un singolo endpoint PUT usando MapPut:

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();
});

Questo metodo è simile al metodo , ad eccezione del MapPost fatto che usa HTTP PUT. Una risposta con esito positivo restituisce 204 (nessun contenuto). In base alla specifica HTTP, una richiesta PUT richiede che il client invii l'intera entità aggiornata e non solo le modifiche. Per supportare gli aggiornamenti parziali, usare HTTP PATCH.

Testare l'endpoint PUT

Questo esempio usa un database in memoria che deve essere inizializzato ogni volta che l'app viene avviata. Deve esistere un elemento nel database prima di eseguire una chiamata PUT. Chiamare GET per assicurarsi che nel database sia presente un elemento prima di effettuare una chiamata PUT.

Aggiornare l'elemento attività con Id = 1 e impostarne il nome su "feed fish".

Visual Studio

• In Esplora endpoint fare clic con il pulsante destro del mouse sull'endpoint PUT e selezionare Genera richiesta.

  Al file viene aggiunto il TodoApi.http contenuto seguente:

  Put {{TodoApi_HostAddress}}/todoitems/{id}
  
  ###
  

• Nella riga della richiesta PUT sostituire {id} con 1.

• Aggiungere le righe seguenti subito dopo la riga della richiesta PUT:

  Content-Type: application/json
  
  {
    "name": "feed fish",
    "isComplete": false
  }
  

  Il codice precedente aggiunge un'intestazione Content-Type e un corpo della richiesta JSON.

• Selezionare il collegamento Invia richiesta sopra la nuova riga di richiesta PUT.

  La richiesta PUT viene inviata all'app e la risposta viene visualizzata nel riquadro Risposta . Il corpo della risposta è vuoto e il codice di stato è 204.

Visual Studio Code

Usare Swagger per inviare una richiesta PUT:

• Selezionare Inserisci /todoitems/{id}>Prova.

• Impostare il campo ID su 1.

• Impostare il corpo della richiesta sul codice JSON seguente:

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

• Seleziona Execute.

Esaminare e testare l'endpoint DELETE

L'app di esempio implementa un singolo endpoint DELETE usando MapDelete:

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

• In Esplora endpoint fare clic con il pulsante destro del mouse sull'endpoint DELETE e scegliere Genera richiesta.

  Una richiesta DELETE viene aggiunta a TodoApi.http.

• Sostituire {id} nella riga di richiesta DELETE con 1. La richiesta DELETE dovrebbe essere simile all'esempio seguente:

  DELETE {{TodoApi_HostAddress}}/todoitems/1
  
  ###
  

• Selezionare il collegamento Invia richiesta per la richiesta DELETE.

  La richiesta DELETE viene inviata all'app e la risposta viene visualizzata nel riquadro Risposta . Il corpo della risposta è vuoto e il codice di stato è 204.

Visual Studio Code

Usare Swagger per inviare una richiesta DELETE:

• Selezionare DELETE /todoitems/{id}Try it out(Elimina /todoitems/{id}>Prova.

• Impostare il campo ID su 1 e selezionare Esegui.

  La richiesta DELETE viene inviata all'app e la risposta viene visualizzata nel riquadro Risposte . Il corpo della risposta è vuoto e il codice di stato della risposta del server è 204.

Usare l'API MapGroup

Il codice dell'app di esempio ripete il todoitems prefisso URL ogni volta che configura un endpoint. Le API hanno spesso gruppi di endpoint con un prefisso URL comune e il MapGroup metodo è disponibile per organizzare tali gruppi. Riduce il codice ripetitivo e consente di personalizzare interi gruppi di endpoint con una singola chiamata a metodi come RequireAuthorization e WithMetadata.

Sostituire il contenuto di Program.cs con il codice seguente:

Visual Studio

using Microsoft.EntityFrameworkCore;

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

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.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 NSwag.AspNetCore;
using Microsoft.EntityFrameworkCore;

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

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(config =>
{
    config.DocumentName = "TodoAPI";
    config.Title = "TodoAPI v1";
    config.Version = "v1";
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseOpenApi();
    app.UseSwaggerUi(config =>
    {
        config.DocumentTitle = "TodoAPI";
        config.Path = "/swagger";
        config.DocumentPath = "/swagger/{documentName}/swagger.json";
        config.DocExpansion = "list";
    });
}

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.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();

Il codice precedente presenta le modifiche seguenti:

• Aggiunge var todoItems = app.MapGroup("/todoitems"); per configurare il gruppo usando il prefisso /todoitemsURL .
• Modifica tutti i app.Map<HttpVerb> metodi in todoItems.Map<HttpVerb>.
• Rimuove il prefisso /todoitems URL dalle chiamate al Map<HttpVerb> metodo.

Testare gli endpoint per verificare che funzionino allo stesso modo.

Usare l'API TypedResults

La restituzione TypedResults anziché Results presenta diversi vantaggi, tra cui la testabilità e la restituzione automatica dei metadati del tipo di risposta per OpenAPI per descrivere l'endpoint. Per altre informazioni, vedere TypedResults vs Results.

I Map<HttpVerb> metodi possono chiamare metodi del gestore di route anziché usare espressioni lambda. Per visualizzare un esempio, aggiornare Program.cs con il codice seguente:

Visual Studio

using Microsoft.EntityFrameworkCore;

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

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

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
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> 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 NSwag.AspNetCore;
using Microsoft.EntityFrameworkCore;

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

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(config =>
{
    config.DocumentName = "TodoAPI";
    config.Title = "TodoAPI v1";
    config.Version = "v1";
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseOpenApi();
    app.UseSwaggerUi(config =>
    {
        config.DocumentTitle = "TodoAPI";
        config.Path = "/swagger";
        config.DocumentPath = "/swagger/{documentName}/swagger.json";
        config.DocExpansion = "list";
    });
}

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

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
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> 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();
}

Il Map<HttpVerb> codice chiama ora i metodi anziché le espressioni 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.MapDelete("/{id}", DeleteTodo);

Questi metodi restituiscono oggetti che implementano IResult e sono definiti da 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> 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();
}

Gli unit test possono chiamare questi metodi e verificare che restituiscono il tipo corretto. Ad esempio, se il metodo è GetAllTodos:

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

Il codice di unit test può verificare che un oggetto di tipo Ok<Todo[]> venga restituito dal metodo del gestore. Ad esempio:

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);
}

Impedire l'over-post

Attualmente l'app di esempio espone l'intero Todo oggetto. App di produzione Nelle applicazioni di produzione, viene spesso usato un subset del modello per limitare i dati che possono essere inseriti e restituiti. Esistono diversi motivi alla base di questa situazione e la sicurezza è una delle principali. Il subset di un modello viene in genere definito DTO (Data Transfer Object), modello di input o modello di visualizzazione. DTO viene usato in questo articolo.

Un DTO può essere usato per:

• Impedire l'over-post.
• Nascondere le proprietà che i client non devono visualizzare.
• Omettere alcune proprietà per ridurre le dimensioni del payload.
• Appiattire gli oggetti grafici che contengono oggetti annidati. Gli oggetti grafici appiattiti possono essere più pratici per i client.

Per illustrare l'approccio DTO, aggiornare la Todo classe in modo da includere un campo segreto:

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

Il campo segreto deve essere nascosto da questa app, ma un'app amministrativa potrebbe scegliere di esporla.

Verificare che sia possibile pubblicare e ottenere il campo segreto.

Creare un file denominato TodoItemDTO.cs con il codice seguente:

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);
}

Sostituire il contenuto del Program.cs file con il codice seguente per usare questo modello DTO:

Visual Studio

using Microsoft.EntityFrameworkCore;

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

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

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
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> 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 NSwag.AspNetCore;
using Microsoft.EntityFrameworkCore;

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

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(config =>
{
    config.DocumentName = "TodoAPI";
    config.Title = "TodoAPI v1";
    config.Version = "v1";
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseOpenApi();
    app.UseSwaggerUi(config =>
    {
        config.DocumentTitle = "TodoAPI";
        config.Path = "/swagger";
        config.DocumentPath = "/swagger/{documentName}/swagger.json";
        config.DocExpansion = "list";
    });
}

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

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
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> 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();
}

Verificare che sia possibile pubblicare e ottenere tutti i campi ad eccezione del campo segreto.

Risoluzione dei problemi con l'esempio completato

Se si verifica un problema che non è possibile risolvere, confrontare il codice con il progetto completato. Visualizzare o scaricare il progetto completato (come scaricare).

Passaggi successivi

• Configurare le opzioni di serializzazione JSON.
• Gestire errori ed eccezioni: la pagina delle eccezioni per sviluppatori è abilitata per impostazione predefinita nell'ambiente di sviluppo per le app per le API minime. Per informazioni su come gestire errori ed eccezioni, vedere Gestire gli errori nelle API di base di ASP.NET.
• Per un esempio di test di un'app per le API minima, vedere questo esempio di GitHub.
• Supporto openAPI nelle API minime.
• Guida introduttiva: Pubblicare in Azure.
• Organizzazione delle API minime di base ASP.NET.

Altre informazioni

Vedere Informazioni di riferimento rapido sulle API minime