Informazioni di riferimento rapido sulle API minime

Questo documento:

• Fornisce un riferimento rapido per le API minime.
• È destinato agli sviluppatori esperti. Per un'introduzione, vedere Esercitazione: Creare un'API minima con ASP.NET Core.

Le API minime sono costituite da:

• WebApplication e WebApplicationBuilder
• Gestori di route

WebApplication

Il codice seguente viene generato da un modello ASP.NET Core:

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

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

app.Run();

Il codice precedente può essere creato tramite dotnet new web la riga di comando o selezionando il modello Web vuoto in Visual Studio.

Il codice seguente crea un oggetto WebApplication (app) senza creare in modo esplicito un oggetto WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create inizializza una nuova istanza della WebApplication classe con impostazioni predefinite preconfigurate.

Uso delle porte

Quando viene creata un'app Web con Visual Studio o dotnet new, viene creato un Properties/launchSettings.json file che specifica le porte a cui risponde l'app. Negli esempi di impostazione della porta che seguono, l'esecuzione dell'app da Visual Studio restituisce una finestra di dialogo Unable to connect to web server 'AppName'di errore. Visual Studio restituisce un errore perché prevede la porta specificata in Properties/launchSettings.json, ma l'app usa la porta specificata da app.Run("http://localhost:3000"). Eseguire i seguenti esempi di modifica della porta dalla riga di comando.

Le sezioni seguenti impostano la porta a cui risponde l'app.

var app = WebApplication.Create(args);

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

app.Run("http://localhost:3000");

Nel codice precedente l'app risponde alla porta 3000.

Più porte

Nel codice seguente l'app risponde alla porta 3000 e 4000a .

var app = WebApplication.Create(args);

app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");

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

app.Run();

Impostare la porta dalla riga di comando

Il comando seguente rende l'app risponde alla porta 7777:

dotnet run --urls="https://localhost:7777"

Se l'endpoint Kestrel è configurato anche nel appsettings.json file, viene usato l'URL specificato dal appsettings.json file. Per altre informazioni, vedere Kestrel Configurazione dell'endpoint

Leggere la porta dall'ambiente

Il codice seguente legge la porta dall'ambiente:

var app = WebApplication.Create(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";

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

app.Run($"http://localhost:{port}");

Il modo migliore per impostare la porta dall'ambiente consiste nell'usare la ASPNETCORE_URLS variabile di ambiente, illustrata nella sezione seguente.

Impostare le porte tramite la variabile di ambiente ASPNETCORE_URLS

La ASPNETCORE_URLS variabile di ambiente è disponibile per impostare la porta:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS supporta più URL:

ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000

Ascoltare tutte le interfacce

Gli esempi seguenti illustrano l'ascolto su tutte le interfacce

http://*:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://*:3000");

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

app.Run();

http://+:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://+:3000");

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

app.Run();

http://0.0.0.0:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://0.0.0.0:3000");

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

app.Run();

Ascoltare tutte le interfacce usando ASPNETCORE_URLS

Gli esempi precedenti possono usare ASPNETCORE_URLS

ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005

Ascoltare tutte le interfacce usando ASPNETCORE_HTTPS_PORTS

Gli esempi precedenti possono usare ASPNETCORE_HTTPS_PORTS e ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Per altre informazioni, vedere Configurare gli endpoint per il server Web ASP.NET Core Kestrel

Specificare HTTPS con il certificato di sviluppo

var app = WebApplication.Create(args);

app.Urls.Add("https://localhost:3000");

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

app.Run();

Per altre informazioni sul certificato di sviluppo, vedere Considerare attendibile il certificato di sviluppo HTTPS di ASP.NET Core in Windows e macOS.

Specificare HTTPS usando un certificato personalizzato

Le sezioni seguenti illustrano come specificare il certificato personalizzato usando il appsettings.json file e tramite la configurazione.

Specificare il certificato personalizzato con appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "cert.pem",
        "KeyPath": "key.pem"
      }
    }
  }
}

Specificare il certificato personalizzato tramite la configurazione

var builder = WebApplication.CreateBuilder(args);

// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Usare le API del certificato

using System.Security.Cryptography.X509Certificates;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
        var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");

        httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath, 
                                         keyPath);
    });
});

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Leggere l'ambiente

var app = WebApplication.Create(args);

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/oops");
}

app.MapGet("/", () => "Hello World");
app.MapGet("/oops", () => "Oops! An error happened.");

app.Run();

Per ulteriori informazioni sull'uso dell'ambiente, vedere ASP.NET Core ambienti di runtime

Configuration

Il codice seguente legge dal sistema di configurazione:

var app = WebApplication.Create(args);

var message = app.Configuration["HelloKey"] ?? "Config failed!";

app.MapGet("/", () => message);

app.Run();

Per altre informazioni, vedere Configurazione in ASP.NET Core

Logging

Il codice seguente scrive un messaggio all'avvio dell'applicazione di accesso:

var app = WebApplication.Create(args);

app.Logger.LogInformation("The app started");

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

app.Run();

Per altre informazioni, vedere Registrazione in .NET e ASP.NET Core

Accedere al contenitore di inserimento delle dipendenze

Il codice seguente illustra come ottenere servizi dal contenitore di inserimento delle dipendenze durante l'avvio dell'applicazione:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();

var app = builder.Build();

app.MapControllers();

using (var scope = app.Services.CreateScope())
{
    var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
    sampleService.DoSomething();
}

app.Run();

Il codice seguente illustra come accedere alle chiavi dal contenitore di inserimento delle dipendenze usando l'attributo [FromKeyedServices] :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");

var app = builder.Build();

app.MapGet("/big", ([FromKeyedServices("big")] ICache bigCache) => bigCache.Get("date"));

app.MapGet("/small", ([FromKeyedServices("small")] ICache smallCache) => smallCache.Get("date"));

app.Run();

public interface ICache
{
    object Get(string key);
}
public class BigCache : ICache
{
    public object Get(string key) => $"Resolving {key} from big cache.";
}

public class SmallCache : ICache
{
    public object Get(string key) => $"Resolving {key} from small cache.";
}

Per altre informazioni sull'inserimento delle dipendenze, vedere Inserimento delle dipendenze in ASP.NET Core.

WebApplicationBuilder

Questa sezione contiene codice di esempio che usa WebApplicationBuilder.

Modificare la radice del contenuto, il nome dell'applicazione e l'ambiente

Il codice seguente imposta la radice del contenuto, il nome dell'applicazione e l'ambiente:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    ApplicationName = typeof(Program).Assembly.FullName,
    ContentRootPath = Directory.GetCurrentDirectory(),
    EnvironmentName = Environments.Staging,
    WebRootPath = "customwwwroot"
});

Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");

var app = builder.Build();

WebApplication.CreateBuilder inizializza una nuova istanza della classe WebApplicationBuilder con valori predefiniti preconfigurati.

Per altre informazioni, vedere ASP.NET Panoramica dei concetti fondamentali di base

Modificare la radice del contenuto, il nome dell'app e l'ambiente usando variabili di ambiente o riga di comando

La tabella seguente illustra la variabile di ambiente e l'argomento della riga di comando usati per modificare la radice del contenuto, il nome dell'app e l'ambiente:

feature	Variabile di ambiente	Argomento della riga di comando
Nome applicazione	ASPNETCORE_APPLICATIONNAME	--applicationName
Nome dell'ambiente	ASPNETCORE_ENVIRONMENT	--environment
Radice del contenuto	ASPNETCORE_CONTENTROOT	--contentRoot

Aggiungere provider di configurazione

L'esempio seguente aggiunge il provider di configurazione INI:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("appsettings.ini");

var app = builder.Build();

Per informazioni dettagliate, vedere Provider di configurazione file in Configurazione in ASP.NET Core.

Leggere la configurazione

Per impostazione predefinita, la WebApplicationBuilder configurazione legge da più origini, tra cui:

• appSettings.json e appSettings.{environment}.json
• Variabili di ambiente
• Riga di comando

Per un elenco completo delle origini di configurazione, vedere Configurazione predefinita in Configurazione in ASP.NET Core.

Il codice seguente legge HelloKey dalla configurazione e visualizza il valore nell'endpoint / . Se il valore di configurazione è Null, "Hello" viene assegnato a message:

var builder = WebApplication.CreateBuilder(args);

var message = builder.Configuration["HelloKey"] ?? "Hello";

var app = builder.Build();

app.MapGet("/", () => message);

app.Run();

Leggere l'ambiente

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine($"Running in development.");
}

var app = builder.Build();

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

app.Run();

Aggiungere provider di registrazione

var builder = WebApplication.CreateBuilder(args);

// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();

var app = builder.Build();

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

app.Run();

Aggiungere servizi

var builder = WebApplication.CreateBuilder(args);

// Add the memory cache services.
builder.Services.AddMemoryCache();

// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();

Personalizzare IHostBuilder

È possibile accedere ai metodi di estensione esistenti in IHostBuilder usando la proprietà Host:

var builder = WebApplication.CreateBuilder(args);

// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));

var app = builder.Build();

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

app.Run();

Personalizzare IWebHostBuilder

È possibile accedere ai metodi IWebHostBuilder di estensione in usando la proprietà WebApplicationBuilder.WebHost .

var builder = WebApplication.CreateBuilder(args);

// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();

var app = builder.Build();

app.MapGet("/", () => "Hello HTTP.sys");

app.Run();

Modificare la radice Web

Per impostazione predefinita, la radice Web è relativa alla radice del contenuto nella wwwroot cartella. La radice Web è la posizione in cui il middleware dei file statici cerca i file statici. La radice Web può essere modificata con WebHostOptions, la riga di comando o con il UseWebRoot metodo :

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Look for static files in webroot
    WebRootPath = "webroot"
});

var app = builder.Build();

app.Run();

Contenitore di inserimento delle dipendenze personalizzato

L'esempio seguente usa Autofac:

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));

var app = builder.Build();

Aggiungere middleware

Qualsiasi middleware core ASP.NET esistente può essere configurato in WebApplication:

var app = WebApplication.Create(args);

// Setup the file server to serve static files.
app.UseFileServer();

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

app.Run();

Per altre informazioni, vedere middleware ASP.NET Core

Pagina delle eccezioni per gli sviluppatori

WebApplication.CreateBuilder inizializza una nuova istanza della WebApplicationBuilder classe con impostazioni predefinite preconfigurate. La pagina delle eccezioni per sviluppatori è abilitata nelle impostazioni predefinite preconfigurate. Quando il codice seguente viene eseguito nell'ambiente di sviluppo, spostarsi per eseguire / il rendering di una pagina descrittiva che mostra l'eccezione.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () =>
{
    throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});

app.Run();

Middleware di ASP.NET Core

La tabella seguente elenca alcuni dei middleware usati di frequente con API minime.

Middleware	Description	API
Authentication	Offre il supporto dell'autenticazione.	UseAuthentication
Authorization	Fornisce il supporto per l'autorizzazione.	UseAuthorization
CORS	Configura la condivisione di risorse tra le origini (CORS).	UseCors
Gestore eccezioni	Gestisce globalmente le eccezioni generate dalla pipeline middleware.	UseExceptionHandler
Intestazioni inoltrate	Inoltra le intestazioni proxy nella richiesta corrente.	UseForwardedHeaders
Reindirizzamento HTTPS	Reindirizza tutte le richieste HTTP a HTTPS.	UseHttpsRedirection
Protocollo HTTP Strict Transport Security (HSTS)	Middleware di ottimizzazione della sicurezza che aggiunge un'intestazione della risposta speciale.	UseHsts
Registrazione richieste	Fornisce supporto per la registrazione di richieste e risposte HTTP.	UseHttpLogging
Timeout delle richieste	Fornisce il supporto per la configurazione dei timeout delle richieste, impostazione predefinita globale e per endpoint.	UseRequestTimeouts
Registrazione delle richieste W3C	Fornisce il supporto per la registrazione di richieste e risposte HTTP nel formato W3C.	UseW3CLogging
Memorizzazione nella cache delle risposte	Offre il supporto per la memorizzazione delle risposte nella cache.	UseResponseCaching
Compressione della risposta	Offre il supporto per la compressione delle risposte.	UseResponseCompression
Session	Offre il supporto per la gestione delle sessioni utente.	UseSession
File statici	Offre il supporto per la gestione di file statici e l'esplorazione directory.	UseStaticFiles, UseFileServer
WebSockets	Abilita il protocollo WebSocket.	UseWebSockets

Le sezioni seguenti illustrano la gestione delle richieste: routing, associazione di parametri e risposte.

Routing

Un oggetto configurato supporta e dove è un metodo HTTP con maiuscole e minuscole camel come WebApplication, Map{Verb}MapMethods, o {Verb}:GetPostPutDelete

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

app.MapGet("/", () => "This is a GET");
app.MapPost("/", () => "This is a POST");
app.MapPut("/", () => "This is a PUT");
app.MapDelete("/", () => "This is a DELETE");

app.MapMethods("/options-or-head", new[] { "OPTIONS", "HEAD" }, 
                          () => "This is an options or head request ");

app.Run();

Gli Delegate argomenti passati a questi metodi sono denominati "gestori di route".

Gestori di route

I gestori di route sono metodi eseguiti quando la route corrisponde. I gestori di route possono essere un'espressione lambda, una funzione locale, un metodo di istanza o un metodo statico. I gestori di route possono essere sincroni o asincroni.

Espressione lambda

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

app.MapGet("/inline", () => "This is an inline lambda");

var handler = () => "This is a lambda variable";

app.MapGet("/", handler);

app.Run();

Funzione locale

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

string LocalFunction() => "This is local function";

app.MapGet("/", LocalFunction);

app.Run();

Metodo dell'istanza

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

var handler = new HelloHandler();

app.MapGet("/", handler.Hello);

app.Run();

class HelloHandler
{
    public string Hello()
    {
        return "Hello Instance method";
    }
}

Metodo statico

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

app.MapGet("/", HelloHandler.Hello);

app.Run();

class HelloHandler
{
    public static string Hello()
    {
        return "Hello static method";
    }
}

Endpoint definito all'esterno di Program.cs

Non è necessario che le API minime si trovino in Program.cs.

Program.cs

using MinAPISeparateFile;

var builder = WebApplication.CreateSlimBuilder(args);

var app = builder.Build();

TodoEndpoints.Map(app);

app.Run();

TodoEndpoints.cs

namespace MinAPISeparateFile;

public static class TodoEndpoints
{
    public static void Map(WebApplication app)
    {
        app.MapGet("/", async context =>
        {
            // Get all todo items
            await context.Response.WriteAsJsonAsync(new { Message = "All todo items" });
        });

        app.MapGet("/{id}", async context =>
        {
            // Get one todo item
            await context.Response.WriteAsJsonAsync(new { Message = "One todo item" });
        });
    }
}

Vedere anche Instradare i gruppi più avanti in questo articolo.

Endpoint denominati e generazione di collegamenti

Gli endpoint possono essere assegnati ai nomi per generare URL all'endpoint. L'uso di un endpoint denominato evita di dover impostare percorsi hardcoded in un'app:

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

app.MapGet("/hello", () => "Hello named route")
   .WithName("hi");

app.MapGet("/", (LinkGenerator linker) => 
        $"The link to the hello route is {linker.GetPathByName("hi", values: null)}");

app.Run();

Il codice precedente viene visualizzato The link to the hello route is /hello dall'endpoint / .

NOTA: i nomi degli endpoint fanno distinzione tra maiuscole e minuscole.

Nomi degli endpoint:

• Deve essere univoco a livello globale.
• Vengono usati come ID operazione OpenAPI quando è abilitato il supporto OpenAPI. Per altre informazioni, vedere OpenAPI.

Parametri di route

I parametri di route possono essere acquisiti come parte della definizione del modello di route:

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

app.MapGet("/users/{userId}/books/{bookId}", 
    (int userId, int bookId) => $"The user id is {userId} and book id is {bookId}");

app.Run();

Il codice precedente restituisce The user id is 3 and book id is 7 dall'URI /users/3/books/7.

Il gestore di route può dichiarare i parametri da acquisire. Quando viene effettuata una richiesta a una route con parametri dichiarati per l'acquisizione, i parametri vengono analizzati e passati al gestore. In questo modo è facile acquisire i valori in modo sicuro per il tipo. Nel codice userId precedente e bookId sono entrambi int.

Nel codice precedente, se uno dei valori di route non può essere convertito in int, viene generata un'eccezione. La richiesta /users/hello/books/3 GET genera l'eccezione seguente:

BadHttpRequestException: Failed to bind parameter "int userId" from "hello".

Carattere jolly e intercettare tutte le route

Il seguente catch all route restituisce Routing to hello dall'endpoint '/posts/hello':

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

app.MapGet("/posts/{*rest}", (string rest) => $"Routing to {rest}");

app.Run();

Vincoli della route

I vincoli di route vincolano il comportamento di corrispondenza di una route.

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

app.MapGet("/todos/{id:int}", (int id) => db.Todos.Find(id));
app.MapGet("/todos/{text}", (string text) => db.Todos.Where(t => t.Text.Contains(text));
app.MapGet("/posts/{slug:regex(^[a-z0-9_-]+$)}", (string slug) => $"Post {slug}");

app.Run();

La tabella seguente illustra i modelli di route precedenti e il relativo comportamento:

Modello di route	URI corrispondente di esempio
/todos/{id:int}	/todos/1
/todos/{text}	/todos/something
/posts/{slug:regex(^[a-z0-9_-]+$)}	/posts/mypost

Per altre informazioni, vedere Informazioni di riferimento sui vincoli di route in Routing in ASP.NET Core.

Gruppi di route

Il MapGroup metodo di estensione consente di organizzare gruppi di endpoint con un prefisso comune. Riduce il codice ripetitivo e consente di personalizzare interi gruppi di endpoint con una singola chiamata a metodi come RequireAuthorization e WithMetadata che aggiungono metadati dell'endpoint.

Ad esempio, il codice seguente crea due gruppi simili di endpoint:

app.MapGroup("/public/todos")
    .MapTodosApi()
    .WithTags("Public");

app.MapGroup("/private/todos")
    .MapTodosApi()
    .WithTags("Private")
    .AddEndpointFilterFactory(QueryPrivateTodos)
    .RequireAuthorization();


EndpointFilterDelegate QueryPrivateTodos(EndpointFilterFactoryContext factoryContext, EndpointFilterDelegate next)
{
    var dbContextIndex = -1;

    foreach (var argument in factoryContext.MethodInfo.GetParameters())
    {
        if (argument.ParameterType == typeof(TodoDb))
        {
            dbContextIndex = argument.Position;
            break;
        }
    }

    // Skip filter if the method doesn't have a TodoDb parameter.
    if (dbContextIndex < 0)
    {
        return next;
    }

    return async invocationContext =>
    {
        var dbContext = invocationContext.GetArgument<TodoDb>(dbContextIndex);
        dbContext.IsPrivate = true;

        try
        {
            return await next(invocationContext);
        }
        finally
        {
            // This should only be relevant if you're pooling or otherwise reusing the DbContext instance.
            dbContext.IsPrivate = false;
        }
    };
}

public static RouteGroupBuilder MapTodosApi(this RouteGroupBuilder group)
{
    group.MapGet("/", GetAllTodos);
    group.MapGet("/{id}", GetTodo);
    group.MapPost("/", CreateTodo);
    group.MapPut("/{id}", UpdateTodo);
    group.MapDelete("/{id}", DeleteTodo);

    return group;
}

In questo scenario è possibile usare un indirizzo relativo per l'intestazione Location nel 201 Created risultato:

public static async Task<Created<Todo>> CreateTodo(Todo todo, TodoDb database)
{
    await database.AddAsync(todo);
    await database.SaveChangesAsync();

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

Il primo gruppo di endpoint corrisponderà solo alle richieste precedute da /public/todos e sono accessibili senza alcuna autenticazione. Il secondo gruppo di endpoint corrisponderà solo alle richieste precedute /private/todos da e richiederanno l'autenticazione.

La QueryPrivateTodosfactory del filtro endpoint è una funzione locale che modifica i parametri del TodoDb gestore di route per consentire l'accesso e l'archiviazione di dati todo privati.

I gruppi di route supportano anche gruppi annidati e modelli di prefisso complessi con parametri e vincoli di route. Nell'esempio seguente e il gestore di route mappato al user gruppo possono acquisire i {org} parametri e {group} di route definiti nei prefissi del gruppo esterno.

Il prefisso può anche essere vuoto. Ciò può essere utile per l'aggiunta di metadati o filtri dell'endpoint a un gruppo di endpoint senza modificare il modello di route.

var all = app.MapGroup("").WithOpenApi();
var org = all.MapGroup("{org}");
var user = org.MapGroup("{user}");
user.MapGet("", (string org, string user) => $"{org}/{user}");

L'aggiunta di filtri o metadati a un gruppo ha lo stesso comportamento dell'aggiunta singolarmente a ogni endpoint prima di aggiungere altri filtri o metadati che potrebbero essere stati aggiunti a un gruppo interno o a un endpoint specifico.

var outer = app.MapGroup("/outer");
var inner = outer.MapGroup("/inner");

inner.AddEndpointFilter((context, next) =>
{
    app.Logger.LogInformation("/inner group filter");
    return next(context);
});

outer.AddEndpointFilter((context, next) =>
{
    app.Logger.LogInformation("/outer group filter");
    return next(context);
});

inner.MapGet("/", () => "Hi!").AddEndpointFilter((context, next) =>
{
    app.Logger.LogInformation("MapGet filter");
    return next(context);
});

Nell'esempio precedente, il filtro esterno registra la richiesta in ingresso prima del filtro interno anche se è stato aggiunto secondo. Poiché i filtri sono stati applicati a gruppi diversi, l'ordine in cui sono stati aggiunti l'uno rispetto all'altro non è importante. I filtri dell'ordine vengono aggiunti se applicati allo stesso gruppo o allo stesso endpoint specifico.

Una richiesta per /outer/inner/ registrare quanto segue:

/outer group filter
/inner group filter
MapGet filter

Associazione di parametri

L'associazione di parametri è il processo di conversione dei dati delle richieste in parametri fortemente tipizzato espressi dai gestori di route. Un'origine di associazione determina la posizione da cui sono associati i parametri. Le origini di associazione possono essere esplicite o dedotte in base al metodo HTTP e al tipo di parametro.

Origini di associazione supportate:

• Valori di route
• Stringa di query
• Header
• Corpo (come JSON)
• Valori modulo
• Servizi forniti dall'inserimento delle dipendenze
• Custom

Il gestore di route GET seguente usa alcune di queste origini di associazione di parametri:

var builder = WebApplication.CreateBuilder(args);

// Added as service
builder.Services.AddSingleton<Service>();

var app = builder.Build();

app.MapGet("/{id}", (int id,
                     int page,
                     [FromHeader(Name = "X-CUSTOM-HEADER")] string customHeader,
                     Service service) => { });

class Service { }

Funzionalità di associazione dei parametri chiave

• Associazione esplicita: usare attributi come [FromRoute], [FromQuery][FromHeader], [FromBody], [FromForm], e [FromServices] per specificare in modo esplicito le origini di associazione.
• Associazione di moduli: associare i valori dei moduli usando l'attributo [FromForm] , incluso il supporto per IFormFile e IFormFileCollection per i caricamenti di file.
• Tipi complessi: Legare alle raccolte e ai tipi complessi nei moduli, nelle stringhe di query e nelle intestazioni.
• Associazione personalizzata: implementare la logica di associazione personalizzata usando TryParse, BindAsynco l'interfaccia IBindableFromHttpContext<T> .
• Parametri facoltativi: supportano i tipi nullable e i valori predefiniti per i parametri facoltativi.
• Inserimento delle dipendenze: i parametri vengono automaticamente associati ai servizi registrati nel contenitore DI.
• Tipi speciali: associazione automatica per HttpContext, HttpRequest, HttpResponse, CancellationTokenClaimsPrincipal, Stream, e PipeReader.

---

Ulteriori informazioni: Per informazioni dettagliate sull'associazione di parametri, inclusi scenari avanzati, convalida, precedenza di associazione e risoluzione dei problemi, vedere Associazione di parametri nelle applicazioni API minime.

Deserializzazione json+PipeReader nelle API minime

A partire da .NET 10, le seguenti aree funzionali di ASP.NET Core usano gli overload di JsonSerializer.DeserializeAsync basati su PipeReader anziché su Stream.

• API minime (associazione di parametri, corpo della richiesta di lettura)
• MVC (formattatori di input, modello)
• Metodi HttpRequestJsonExtensions di estensione per leggere il corpo della richiesta come JSON.

Per la maggior parte delle applicazioni, una transizione da Stream a PipeReader offre prestazioni migliori senza richiedere modifiche al codice dell'applicazione. Tuttavia, se l'applicazione dispone di un convertitore personalizzato, il convertitore potrebbe non essere gestito Utf8JsonReader.HasValueSequence correttamente. In caso contrario, il risultato potrebbe essere un errore, ArgumentOutOfRangeException ad esempio o dati mancanti durante la deserializzazione. Sono disponibili le opzioni seguenti per il corretto funzionamento del convertitore senza errori correlati a PipeReader.

Opzione 1: Soluzione temporanea

La soluzione alternativa rapida consiste nel tornare all'uso di Stream senza il supporto di PipeReader. Per implementare questa opzione, impostare l'opzione AppContext "Microsoft.AspNetCore.UseStreamBasedJsonParsing" su "true". È consigliabile eseguire questa operazione solo come soluzione alternativa temporanea e aggiornare il convertitore per supportare HasValueSequence il più presto possibile. L'opzione potrebbe essere rimossa in .NET 11. L'unico scopo era quello di offrire agli sviluppatori il tempo necessario per aggiornare i convertitori.

Opzione 2: Una correzione rapida per le implementazioni di JsonConverter

Per questa correzione, si alloca un array da ReadOnlySequence. Questo esempio mostra l'aspetto del codice:

public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
    var span = reader.HasValueSequence ? reader.ValueSequence.ToArray() : reader.ValueSpan;
    // previous code
}

Opzione 3: Una correzione più complessa ma più efficiente

Questa correzione comporta la configurazione di un percorso di codice separato per la ReadOnlySequence gestione:

public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
    if (reader.HasValueSequence)
    {
        reader.ValueSequence;
        // ReadOnlySequence optimized path
    }
    else
    {
        reader.ValueSpan;
        // ReadOnlySpan optimized path
    }
}

Per ulteriori informazioni, vedere

• System.Text.Json.Serialization.JsonConverter
• github.com/dotnet/aspnetcore/pull/62895

Supporto della convalida nelle API minime

L'abilitazione della convalida consente al runtime di ASP.NET Core di eseguire le convalide definite in:

• Query
• Header
• Testo della richiesta

Le validazioni vengono definite usando attributi nello spazio dei nomi DataAnnotations.

Quando un parametro per un endpoint API minimo è una classe o un tipo di record, gli attributi di convalida vengono applicati automaticamente. Per esempio:

public record Product(
    [Required] string Name,
    [Range(1, 1000)] int Quantity);

Gli sviluppatori personalizzano il comportamento del sistema di convalida in base a:

• Creazione di implementazioni di attributi personalizzati[Validation].
• Implementazione dell'IValidatableObject interfaccia per la logica di convalida complessa.

Se la convalida ha esito negativo, il runtime restituisce una risposta 400 - Richiesta non valida con i dettagli degli errori di convalida.

Abilitare il supporto di convalida predefinito per le API minime

Abilitare il supporto di convalida predefinito per le API minime chiamando il AddValidation metodo di estensione per registrare i servizi necessari nel contenitore di servizi per l'applicazione:

builder.Services.AddValidation();

L'implementazione individua automaticamente i tipi definiti nei gestori API minimi o come tipi di base definiti nei gestori API minimi. Un filtro per gli endpoint esegue la convalida su questi tipi ed è aggiunto per ciascun endpoint.

La convalida può essere disabilitata per endpoint specifici usando il DisableValidation metodo di estensione, come nell'esempio seguente:

app.MapPost("/products",
    ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name)
        => TypedResults.Ok(productId))
    .DisableValidation();

Personalizzare le risposte agli errori di convalida usando IProblemDetailsService

Personalizzare le risposte di errore dalla logica di convalida minima dell'API con un'implementazione IProblemDetailsService . Registrare questo servizio nella raccolta di servizi dell'applicazione per abilitare risposte di errore più coerenti e specifiche dell'utente. Il supporto per la convalida minima dell'API è stato introdotto in ASP.NET Core in .NET 10.

Per implementare risposte di errore di convalida personalizzate:

• Implementare o usare l'implementazione IProblemDetailsService predefinita
• Registrare il servizio nel contenitore di inserimento delle dipendenze
• Il sistema di convalida usa automaticamente il servizio registrato per formattare le risposte agli errori di convalida

Per altre informazioni sulla personalizzazione delle risposte agli errori di convalida con IProblemDetailsService, vedere Creare risposte nelle applicazioni API minime.

Responses

I gestori di route supportano i tipi di valori restituiti seguenti:

1. IResult based : include Task<IResult> e ValueTask<IResult>
2. string - Questo include Task<string> e ValueTask<string>
3. T (Qualsiasi altro tipo) - Include Task<T> e ValueTask<T>

Valore restituito	Behavior	Content-Type
IResult	Il framework chiama IResult.ExecuteAsync	Deciso dall'implementazione IResult
string	Il framework scrive la stringa direttamente nella risposta	text/plain
T (Qualsiasi altro tipo)	Il framework JSON serializza la risposta	application/json

Per una guida più approfondita ai valori restituiti del gestore di route, vedere Creare risposte nelle applicazioni API minime

Valori restituiti di esempio

valori restituiti di stringa

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

Valori restituiti JSON

app.MapGet("/hello", () => new { Message = "Hello World" });

Restituisci TypedResults

Il codice seguente restituisce un oggetto TypedResults:

app.MapGet("/hello", () => TypedResults.Ok(new Message() {  Text = "Hello World!" }));

La restituzione di è preferibile TypedResultsResultsper restituire . Per altre informazioni, vedere TypedResults vs Results.

Valori restituiti IResult

app.MapGet("/hello", () => Results.Ok(new { Message = "Hello World" }));

Nell'esempio seguente vengono usati i tipi di risultati predefiniti per personalizzare la risposta:

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

JSON

app.MapGet("/hello", () => Results.Json(new { Message = "Hello World" }));

Codice di stato personalizzato

app.MapGet("/405", () => Results.StatusCode(405));

Text

app.MapGet("/text", () => Results.Text("This is some text"));

Stream

var proxyClient = new HttpClient();
app.MapGet("/pokemon", async () => 
{
    var stream = await proxyClient.GetStreamAsync("http://contoso/pokedex.json");
    // Proxy the response as JSON
    return Results.Stream(stream, "application/json");
});

Per altri esempi, vedere Creare risposte nelle applicazioni API minime.

Redirect

app.MapGet("/old-path", () => Results.Redirect("/new-path"));

File

app.MapGet("/download", () => Results.File("myfile.text"));

Risultati predefiniti

Gli helper di risultati comuni esistono nelle Results classi statiche e TypedResults . La restituzione di è preferibile TypedResultsResultsper restituire . Per altre informazioni, vedere TypedResults vs Results.

Modifica delle intestazioni

Usare l'oggetto HttpResponse per modificare le intestazioni di risposta:

app.MapGet("/", (HttpContext context) => {
    // Set a custom header
    context.Response.Headers["X-Custom-Header"] = "CustomValue";

    // Set a known header
    context.Response.Headers.CacheControl = $"public,max-age=3600";

    return "Hello World";
});

Personalizzazione dei risultati

Le applicazioni possono controllare le risposte implementando un tipo personalizzato IResult . Il codice seguente è un esempio di tipo di risultato HTML:

using System.Net.Mime;
using System.Text;
static class ResultsExtensions
{
    public static IResult Html(this IResultExtensions resultExtensions, string html)
    {
        ArgumentNullException.ThrowIfNull(resultExtensions);

        return new HtmlResult(html);
    }
}

class HtmlResult : IResult
{
    private readonly string _html;

    public HtmlResult(string html)
    {
        _html = html;
    }

    public Task ExecuteAsync(HttpContext httpContext)
    {
        httpContext.Response.ContentType = MediaTypeNames.Text.Html;
        httpContext.Response.ContentLength = Encoding.UTF8.GetByteCount(_html);
        return httpContext.Response.WriteAsync(_html);
    }
}

È consigliabile aggiungere un metodo di estensione per Microsoft.AspNetCore.Http.IResultExtensions rendere questi risultati personalizzati più individuabili.

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

app.MapGet("/html", () => Results.Extensions.Html(@$"<!doctype html>
<html>
    <head><title>miniHTML</title></head>
    <body>
        <h1>Hello World</h1>
        <p>The time on the server is {DateTime.Now:O}</p>
    </body>
</html>"));

app.Run();

Risultati tipizzato

L'interfaccia IResult può rappresentare i valori restituiti dalle API minime che non usano il supporto implicito per la serializzazione JSON dell'oggetto restituito alla risposta HTTP. La classe static Results viene usata per creare oggetti variabili IResult che rappresentano tipi diversi di risposte. Ad esempio, impostare il codice di stato della risposta o reindirizzare a un altro URL.

I tipi che implementano IResult sono pubblici, consentendo le asserzioni di tipo durante il test. Per esempio:

[TestClass()]
public class WeatherApiTests
{
    [TestMethod()]
    public void MapWeatherApiTest()
    {
        var result = WeatherApi.GetAllWeathers();
        Assert.IsInstanceOfType(result, typeof(Ok<WeatherForecast[]>));
    }      
}

È possibile esaminare i tipi restituiti dei metodi corrispondenti nella classe Static TypedResults per trovare il tipo pubblico IResult corretto a cui eseguire il cast.

Per altri esempi, vedere Creare risposte nelle applicazioni API minime.

Filters

Per altre informazioni, vedere Filtri nelle app per le API minime.

Authorization

Le route possono essere protette usando i criteri di autorizzazione. Questi valori possono essere dichiarati tramite l'attributo [Authorize] o usando il RequireAuthorization metodo :

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using WebRPauth.Data;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization(o => o.AddPolicy("AdminsOnly", 
                                  b => b.RequireClaim("admin", "true")));

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();

var app = builder.Build();

app.UseAuthorization();

app.MapGet("/auth", [Authorize] () => "This endpoint requires authorization.");
app.MapGet("/", () => "This endpoint doesn't require authorization.");
app.MapGet("/Identity/Account/Login", () => "Sign in page at this endpoint.");

app.Run();

Il codice precedente può essere scritto con RequireAuthorization:

app.MapGet("/auth", () => "This endpoint requires authorization")
   .RequireAuthorization();

L'esempio seguente usa l'autorizzazione basata su criteri:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using WebRPauth.Data;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization(o => o.AddPolicy("AdminsOnly", 
                                  b => b.RequireClaim("admin", "true")));

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();

var app = builder.Build();

app.UseAuthorization();

app.MapGet("/admin", [Authorize("AdminsOnly")] () => 
                             "The /admin endpoint is for admins only.");

app.MapGet("/admin2", () => "The /admin2 endpoint is for admins only.")
   .RequireAuthorization("AdminsOnly");

app.MapGet("/", () => "This endpoint doesn't require authorization.");
app.MapGet("/Identity/Account/Login", () => "Sign in page at this endpoint.");

app.Run();

Consentire agli utenti non autenticati di accedere a un endpoint

[AllowAnonymous] consente agli utenti non autenticati di accedere agli endpoint:

app.MapGet("/login", [AllowAnonymous] () => "This endpoint is for all roles.");


app.MapGet("/login2", () => "This endpoint also for all roles.")
   .AllowAnonymous();

CORS

Le route possono essere abilitate per CORS usando i criteri CORS. È possibile dichiarare CORS tramite l'attributo [EnableCors] o usando il RequireCors metodo . Gli esempi seguenti abilitano CORS:

const string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors(options =>
{
    options.AddPolicy(name: MyAllowSpecificOrigins,
                      builder =>
                      {
                          builder.WithOrigins("http://example.com",
                                              "http://www.contoso.com");
                      });
});

var app = builder.Build();
app.UseCors();

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

app.Run();

using Microsoft.AspNetCore.Cors;

const string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors(options =>
{
    options.AddPolicy(name: MyAllowSpecificOrigins,
                      builder =>
                      {
                          builder.WithOrigins("http://example.com",
                                              "http://www.contoso.com");
                      });
});

var app = builder.Build();
app.UseCors();

app.MapGet("/cors", [EnableCors(MyAllowSpecificOrigins)] () => 
                           "This endpoint allows cross origin requests!");
app.MapGet("/cors2", () => "This endpoint allows cross origin requests!")
                     .RequireCors(MyAllowSpecificOrigins);

app.Run();

Per altre informazioni, vedere Abilitare le richieste tra le origini (CORS) in ASP.NET Core

ValidateScopes e ValidateOnBuild

ValidateScopes e ValidateOnBuild sono abilitati per impostazione predefinita nell'ambiente di sviluppo , ma disabilitati in altri ambienti.

Quando ValidateOnBuild è true, il contenitore di inserimento delle dipendenze convalida la configurazione del servizio in fase di compilazione. Se la configurazione del servizio non è valida, la compilazione non riesce all'avvio dell'app, anziché in fase di esecuzione quando viene richiesto il servizio.

Quando ValidateScopes è true, il contenitore di inserimento delle dipendenze verifica che un servizio con ambito non venga risolto dall'ambito radice. La risoluzione di un servizio con ambito dall'ambito radice può causare una perdita di memoria perché il servizio viene mantenuto in memoria più lungo dell'ambito della richiesta.

ValidateScopes e ValidateOnBuild sono false per impostazione predefinita nelle modalità non di sviluppo per motivi di prestazioni.

Il codice seguente mostra ValidateScopes che è abilitato per impostazione predefinita in modalità di sviluppo, ma disabilitato in modalità di rilascio:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<MyScopedService>();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    Console.WriteLine("Development environment");
}
else
{
    Console.WriteLine("Release environment");
}

app.MapGet("/", context =>
{
    // Intentionally getting service provider from app, not from the request
    // This causes an exception from attempting to resolve a scoped service
    // outside of a scope.
    // Throws System.InvalidOperationException:
    // 'Cannot resolve scoped service 'MyScopedService' from root provider.'
    var service = app.Services.GetRequiredService<MyScopedService>();
    return context.Response.WriteAsync("Service resolved");
});

app.Run();

public class MyScopedService { }

Il codice seguente mostra ValidateOnBuild che è abilitato per impostazione predefinita in modalità di sviluppo, ma disabilitato in modalità di rilascio:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<MyScopedService>();
builder.Services.AddScoped<AnotherService>();

// System.AggregateException: 'Some services are not able to be constructed (Error
// while validating the service descriptor 'ServiceType: AnotherService Lifetime:
// Scoped ImplementationType: AnotherService': Unable to resolve service for type
// 'BrokenService' while attempting to activate 'AnotherService'.)'
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    Console.WriteLine("Development environment");
}
else
{
    Console.WriteLine("Release environment");
}

app.MapGet("/", context =>
{
    var service = context.RequestServices.GetRequiredService<MyScopedService>();
    return context.Response.WriteAsync("Service resolved correctly!");
});

app.Run();

public class MyScopedService { }

public class AnotherService
{
    public AnotherService(BrokenService brokenService) { }
}

public class BrokenService { }

Il codice seguente disabilita ValidateScopes e ValidateOnBuild in Development:

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine("Development environment");
    // Doesn't detect the validation problems because ValidateScopes is false.
    builder.Host.UseDefaultServiceProvider(options =>
    {
        options.ValidateScopes = false;
        options.ValidateOnBuild = false;
    });
}

Vedere anche

• Informazioni di riferimento rapido sulle API minime
• Generare documenti OpenAPI
• Creare risposte in applicazioni API minime
• Filtri nelle app per le API minime
• Gestire gli errori nelle API core di ASP.NET
• Autenticazione e autorizzazione in API minime
• Testare le app per le API minime
• Routing a corto circuito
• Identity Endpoint API
• Supporto del contenitore di inserimento delle dipendenze del servizio con chiave
• Un'occhiata dietro le quinte degli endpoint API minimi
• Organizzazione delle API minime di base di ASP.NET
• Discussione sulla convalida Fluent su GitHub