Informazioni di riferimento rapido sulle API minime

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.

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// user middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// end user middleware/endpoints

app.UseEndpoints(e => {});

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

app.UseRouting();

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

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

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 altre informazioni sull'uso dell'ambiente, vedere Usare più ambienti in ASP.NET Core

Impostazione

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

Registrazione

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 Core 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:

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

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
• Intestazione
• Corpo (come JSON)
• Valori modulo
• Servizi forniti dall'inserimento delle dipendenze
• Personalizzazione

Il gestore di route seguente GET 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 { }

Nella tabella seguente viene illustrata la relazione tra i parametri usati nell'esempio precedente e le origini di associazione associate.

I metodi GETHTTP , HEAD, OPTIONSe DELETE non si associano in modo implicito dal corpo. Per eseguire l'associazione dal corpo (come JSON) per questi metodi HTTP, associare in modo esplicito [FromBody] o leggere da HttpRequest.

Il gestore di route POST di esempio seguente usa un'origine di associazione del corpo (come JSON) per il person parametro :

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapPost("/", (Person person) => { });

record Person(string Name, int Age);

I parametri negli esempi precedenti sono associati automaticamente dai dati della richiesta. Per illustrare la praticità fornita dall'associazione di parametri, i gestori di route seguenti illustrano come leggere i dati delle richieste direttamente dalla richiesta:

app.MapGet("/{id}", (HttpRequest request) =>
{
    var id = request.RouteValues["id"];
    var page = request.Query["page"];
    var customHeader = request.Headers["X-CUSTOM-HEADER"];

    // ...
});

app.MapPost("/", async (HttpRequest request) =>
{
    var person = await request.ReadFromJsonAsync<Person>();

    // ...
});

Associazione di parametri esplicita

Gli attributi possono essere usati per dichiarare in modo esplicito il percorso da cui sono associati i parametri.

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();


app.MapGet("/{id}", ([FromRoute] int id,
                     [FromQuery(Name = "p")] int page,
                     [FromServices] Service service,
                     [FromHeader(Name = "Content-Type")] string contentType) 
                     => {});

class Service { }

record Person(string Name, int Age);

Associazione esplicita dai valori del modulo

L'attributo [FromForm] associa i valori del modulo:

app.MapPost("/todos", async ([FromForm] string name,
    [FromForm] Visibility visibility, IFormFile? attachment, TodoDb db) =>
{
    var todo = new Todo
    {
        Name = name,
        Visibility = visibility
    };

    if (attachment is not null)
    {
        var attachmentName = Path.GetRandomFileName();

        using var stream = File.Create(Path.Combine("wwwroot", attachmentName));
        await attachment.CopyToAsync(stream);
    }

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

    return Results.Ok();
});

// Remaining code removed for brevity.

Un'alternativa consiste nell'usare l'attributo [AsParameters] con un tipo personalizzato con proprietà annotate con [FromForm]. Ad esempio, il codice seguente viene associato dai valori del modulo alle proprietà dello struct del NewTodoRequest record:

app.MapPost("/ap/todos", async ([AsParameters] NewTodoRequest request, TodoDb db) =>
{
    var todo = new Todo
    {
        Name = request.Name,
        Visibility = request.Visibility
    };

    if (request.Attachment is not null)
    {
        var attachmentName = Path.GetRandomFileName();

        using var stream = File.Create(Path.Combine("wwwroot", attachmentName));
        await request.Attachment.CopyToAsync(stream);

        todo.Attachment = attachmentName;
    }

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

    return Results.Ok();
});

// Remaining code removed for brevity.

public record struct NewTodoRequest([FromForm] string Name,
    [FromForm] Visibility Visibility, IFormFile? Attachment);

Per altre informazioni, vedere la sezione asParameters più avanti in questo articolo.

Il codice di esempio completo si trova nel repository AspNetCore.Docs.Samples .

Associazione sicura da IFormFile e IFormFileCollection

L'associazione di moduli complessi è supportata tramite IFormFile e IFormFileCollection usando :[FromForm]

using Microsoft.AspNetCore.Antiforgery;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAntiforgery();

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

// Generate a form with an anti-forgery token and an /upload endpoint.
app.MapGet("/", (HttpContext context, IAntiforgery antiforgery) =>
{
    var token = antiforgery.GetAndStoreTokens(context);
    var html = MyUtils.GenerateHtmlForm(token.FormFieldName, token.RequestToken!);
    return Results.Content(html, "text/html");
});

app.MapPost("/upload", async Task<Results<Ok<string>, BadRequest<string>>>
    ([FromForm] FileUploadForm fileUploadForm, HttpContext context,
                                                IAntiforgery antiforgery) =>
{
    await MyUtils.SaveFileWithName(fileUploadForm.FileDocument!,
              fileUploadForm.Name!, app.Environment.ContentRootPath);
    return TypedResults.Ok($"Your file with the description:" +
        $" {fileUploadForm.Description} has been uploaded successfully");
});

app.Run();

I parametri associati alla richiesta con [FromForm] includono un token antiforgery. Il token antiforgery viene convalidato quando la richiesta viene elaborata. Per altre informazioni, vedere Antiforgery con API minime.

Per altre informazioni, vedere Associazione di moduli in API minime.

Il codice di esempio completo si trova nel repository AspNetCore.Docs.Samples .

Associazione di parametri con inserimento delle dipendenze

L'associazione di parametri per api minime associa i parametri tramite l'inserimento delle dipendenze quando il tipo è configurato come servizio. Non è necessario applicare in modo esplicito l'attributo [FromServices] a un parametro. Nel codice seguente entrambe le azioni restituiscono l'ora:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IDateTime, SystemDateTime>();

var app = builder.Build();

app.MapGet("/",   (               IDateTime dateTime) => dateTime.Now);
app.MapGet("/fs", ([FromServices] IDateTime dateTime) => dateTime.Now);
app.Run();

Parametri facoltativi

I parametri dichiarati nei gestori di route vengono considerati come obbligatori:

• Se una richiesta corrisponde alla route, il gestore di route viene eseguito solo se nella richiesta vengono forniti tutti i parametri obbligatori.
• Se non si specificano tutti i parametri obbligatori, viene generato un errore.

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

app.MapGet("/products", (int pageNumber) => $"Requesting page {pageNumber}");

app.Run();

Per rendere pageNumber facoltativo, definire il tipo come facoltativo o specificare un valore predefinito:

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

app.MapGet("/products", (int? pageNumber) => $"Requesting page {pageNumber ?? 1}");

string ListProducts(int pageNumber = 1) => $"Requesting page {pageNumber}";

app.MapGet("/products2", ListProducts);

app.Run();

Il valore predefinito e nullable precedente si applica a tutte le origini:

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

app.MapPost("/products", (Product? product) => { });

app.Run();

Il codice precedente chiama il metodo con un prodotto Null se non viene inviato alcun corpo della richiesta.

NOTA: se vengono forniti dati non validi e il parametro è nullable, il gestore di route non viene eseguito.

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

app.MapGet("/products", (int? pageNumber) => $"Requesting page {pageNumber ?? 1}");

app.Run();

Per altre informazioni, vedere la sezione Errori di binding .

Tipi speciali

I tipi seguenti sono associati senza attributi espliciti:

• HttpContext: contesto che contiene tutte le informazioni sulla richiesta o la risposta HTTP corrente:

  app.MapGet("/", (HttpContext context) => context.Response.WriteAsync("Hello World"));
  

• HttpRequest e HttpResponse: la richiesta HTTP e la risposta HTTP:

  app.MapGet("/", (HttpRequest request, HttpResponse response) =>
      response.WriteAsync($"Hello World {request.Query["name"]}"));
  

• CancellationToken: token di annullamento associato alla richiesta HTTP corrente:

  app.MapGet("/", async (CancellationToken cancellationToken) => 
      await MakeLongRunningRequestAsync(cancellationToken));
  

• ClaimsPrincipal: l'utente associato alla richiesta, associato da HttpContext.User:

  app.MapGet("/", (ClaimsPrincipal user) => user.Identity.Name);
  

Associare il corpo della richiesta come o StreamPipeReader

Il corpo della richiesta può essere associato come o Stream PipeReader per supportare in modo efficiente gli scenari in cui l'utente deve elaborare i dati e:

• Archiviare i dati nell'archivio BLOB o accodare i dati a un provider di code.
• Elaborare i dati archiviati con un processo di lavoro o una funzione cloud.

Ad esempio, i dati potrebbero essere accodati all'archiviazione code di Azure o archiviati nell'archivio BLOB di Azure.

Il codice seguente implementa una coda in background:

using System.Text.Json;
using System.Threading.Channels;

namespace BackgroundQueueService;

class BackgroundQueue : BackgroundService
{
    private readonly Channel<ReadOnlyMemory<byte>> _queue;
    private readonly ILogger<BackgroundQueue> _logger;

    public BackgroundQueue(Channel<ReadOnlyMemory<byte>> queue,
                               ILogger<BackgroundQueue> logger)
    {
        _queue = queue;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var dataStream in _queue.Reader.ReadAllAsync(stoppingToken))
        {
            try
            {
                var person = JsonSerializer.Deserialize<Person>(dataStream.Span)!;
                _logger.LogInformation($"{person.Name} is {person.Age} " +
                                       $"years and from {person.Country}");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex.Message);
            }
        }
    }
}

class Person
{
    public string Name { get; set; } = String.Empty;
    public int Age { get; set; }
    public string Country { get; set; } = String.Empty;
}

Il codice seguente associa il corpo della richiesta a un Streamoggetto :

app.MapPost("/register", async (HttpRequest req, Stream body,
                                 Channel<ReadOnlyMemory<byte>> queue) =>
{
    if (req.ContentLength is not null && req.ContentLength > maxMessageSize)
    {
        return Results.BadRequest();
    }

    // We're not above the message size and we have a content length, or
    // we're a chunked request and we're going to read up to the maxMessageSize + 1. 
    // We add one to the message size so that we can detect when a chunked request body
    // is bigger than our configured max.
    var readSize = (int?)req.ContentLength ?? (maxMessageSize + 1);

    var buffer = new byte[readSize];

    // Read at least that many bytes from the body.
    var read = await body.ReadAtLeastAsync(buffer, readSize, throwOnEndOfStream: false);

    // We read more than the max, so this is a bad request.
    if (read > maxMessageSize)
    {
        return Results.BadRequest();
    }

    // Attempt to send the buffer to the background queue.
    if (queue.Writer.TryWrite(buffer.AsMemory(0..read)))
    {
        return Results.Accepted();
    }

    // We couldn't accept the message since we're overloaded.
    return Results.StatusCode(StatusCodes.Status429TooManyRequests);
});

Il codice seguente mostra il file completo Program.cs :

using System.Threading.Channels;
using BackgroundQueueService;

var builder = WebApplication.CreateBuilder(args);
// The max memory to use for the upload endpoint on this instance.
var maxMemory = 500 * 1024 * 1024;

// The max size of a single message, staying below the default LOH size of 85K.
var maxMessageSize = 80 * 1024;

// The max size of the queue based on those restrictions
var maxQueueSize = maxMemory / maxMessageSize;

// Create a channel to send data to the background queue.
builder.Services.AddSingleton<Channel<ReadOnlyMemory<byte>>>((_) =>
                     Channel.CreateBounded<ReadOnlyMemory<byte>>(maxQueueSize));

// Create a background queue service.
builder.Services.AddHostedService<BackgroundQueue>();
var app = builder.Build();

// curl --request POST 'https://localhost:<port>/register' --header 'Content-Type: application/json' --data-raw '{ "Name":"Samson", "Age": 23, "Country":"Nigeria" }'
// curl --request POST "https://localhost:<port>/register" --header "Content-Type: application/json" --data-raw "{ \"Name\":\"Samson\", \"Age\": 23, \"Country\":\"Nigeria\" }"
app.MapPost("/register", async (HttpRequest req, Stream body,
                                 Channel<ReadOnlyMemory<byte>> queue) =>
{
    if (req.ContentLength is not null && req.ContentLength > maxMessageSize)
    {
        return Results.BadRequest();
    }

    // We're not above the message size and we have a content length, or
    // we're a chunked request and we're going to read up to the maxMessageSize + 1. 
    // We add one to the message size so that we can detect when a chunked request body
    // is bigger than our configured max.
    var readSize = (int?)req.ContentLength ?? (maxMessageSize + 1);

    var buffer = new byte[readSize];

    // Read at least that many bytes from the body.
    var read = await body.ReadAtLeastAsync(buffer, readSize, throwOnEndOfStream: false);

    // We read more than the max, so this is a bad request.
    if (read > maxMessageSize)
    {
        return Results.BadRequest();
    }

    // Attempt to send the buffer to the background queue.
    if (queue.Writer.TryWrite(buffer.AsMemory(0..read)))
    {
        return Results.Accepted();
    }

    // We couldn't accept the message since we're overloaded.
    return Results.StatusCode(StatusCodes.Status429TooManyRequests);
});

app.Run();

• Durante la lettura dei dati, è Stream lo stesso oggetto di HttpRequest.Body.
• Il corpo della richiesta non viene memorizzato nel buffer per impostazione predefinita. Dopo aver letto il corpo, non è riavvolgibile. Il flusso non può essere letto più volte.
• e Stream PipeReader non sono utilizzabili al di fuori del gestore di azioni minimo perché i buffer sottostanti verranno eliminati o riutilizzati.

Caricamenti di file con IFormFile e IFormFileCollection

Il codice seguente usa IFormFile e IFormFileCollection per caricare il file:

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

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

app.MapPost("/upload", async (IFormFile file) =>
{
    var tempFile = Path.GetTempFileName();
    app.Logger.LogInformation(tempFile);
    using var stream = File.OpenWrite(tempFile);
    await file.CopyToAsync(stream);
});

app.MapPost("/upload_many", async (IFormFileCollection myFiles) =>
{
    foreach (var file in myFiles)
    {
        var tempFile = Path.GetTempFileName();
        app.Logger.LogInformation(tempFile);
        using var stream = File.OpenWrite(tempFile);
        await file.CopyToAsync(stream);
    }
});

app.Run();

Le richieste di caricamento di file autenticate sono supportate tramite un'intestazione di autorizzazione, un certificato client o un'intestazionecookie.

Associazione a moduli con IFormCollection, IFormFile e IFormFileCollection

L'associazione da parametri basati su form tramite IFormCollection, IFormFilee IFormFileCollection è supportata. I metadati OpenAPI vengono dedotti per i parametri del modulo per supportare l'integrazione con l'interfaccia utente di Swagger.

Il codice seguente carica i file usando l'associazione dedotta dal IFormFile tipo :

using Microsoft.AspNetCore.Antiforgery;
using Microsoft.AspNetCore.Http.HttpResults;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAntiforgery();

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

string GetOrCreateFilePath(string fileName, string filesDirectory = "uploadFiles")
{
    var directoryPath = Path.Combine(app.Environment.ContentRootPath, filesDirectory);
    Directory.CreateDirectory(directoryPath);
    return Path.Combine(directoryPath, fileName);
}

async Task UploadFileWithName(IFormFile file, string fileSaveName)
{
    var filePath = GetOrCreateFilePath(fileSaveName);
    await using var fileStream = new FileStream(filePath, FileMode.Create);
    await file.CopyToAsync(fileStream);
}

app.MapGet("/", (HttpContext context, IAntiforgery antiforgery) =>
{
    var token = antiforgery.GetAndStoreTokens(context);
    var html = $"""
      <html>
        <body>
          <form action="/upload" method="POST" enctype="multipart/form-data">
            <input name="{token.FormFieldName}" type="hidden" value="{token.RequestToken}"/>
            <input type="file" name="file" placeholder="Upload an image..." accept=".jpg, 
                                                                            .jpeg, .png" />
            <input type="submit" />
          </form> 
        </body>
      </html>
    """;

    return Results.Content(html, "text/html");
});

app.MapPost("/upload", async Task<Results<Ok<string>,
   BadRequest<string>>> (IFormFile file, HttpContext context, IAntiforgery antiforgery) =>
{
    var fileSaveName = Guid.NewGuid().ToString("N") + Path.GetExtension(file.FileName);
    await UploadFileWithName(file, fileSaveName);
    return TypedResults.Ok("File uploaded successfully!");
});

app.Run();

Avviso: quando si implementano moduli, l'app deve prevenire attacchi XSRF/CSRF (Cross-Site Request Forgery). Nel codice precedente il IAntiforgery servizio viene usato per evitare attacchi XSRF generando e convalidando un token antiforgery:

using Microsoft.AspNetCore.Antiforgery;
using Microsoft.AspNetCore.Http.HttpResults;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAntiforgery();

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

string GetOrCreateFilePath(string fileName, string filesDirectory = "uploadFiles")
{
    var directoryPath = Path.Combine(app.Environment.ContentRootPath, filesDirectory);
    Directory.CreateDirectory(directoryPath);
    return Path.Combine(directoryPath, fileName);
}

async Task UploadFileWithName(IFormFile file, string fileSaveName)
{
    var filePath = GetOrCreateFilePath(fileSaveName);
    await using var fileStream = new FileStream(filePath, FileMode.Create);
    await file.CopyToAsync(fileStream);
}

app.MapGet("/", (HttpContext context, IAntiforgery antiforgery) =>
{
    var token = antiforgery.GetAndStoreTokens(context);
    var html = $"""
      <html>
        <body>
          <form action="/upload" method="POST" enctype="multipart/form-data">
            <input name="{token.FormFieldName}" type="hidden" value="{token.RequestToken}"/>
            <input type="file" name="file" placeholder="Upload an image..." accept=".jpg, 
                                                                            .jpeg, .png" />
            <input type="submit" />
          </form> 
        </body>
      </html>
    """;

    return Results.Content(html, "text/html");
});

app.MapPost("/upload", async Task<Results<Ok<string>,
   BadRequest<string>>> (IFormFile file, HttpContext context, IAntiforgery antiforgery) =>
{
    var fileSaveName = Guid.NewGuid().ToString("N") + Path.GetExtension(file.FileName);
    await UploadFileWithName(file, fileSaveName);
    return TypedResults.Ok("File uploaded successfully!");
});

app.Run();

Per altre informazioni sugli attacchi XSRF, vedere Antiforgery con API minime

Per altre informazioni, vedere Associazione di moduli nelle API minime;

Eseguire l'associazione a raccolte e tipi complessi da moduli

L'associazione è supportata per:

• Raccolte, ad esempio List e Dictionary
• Tipi complessi, ad esempio o TodoProject

Il codice seguente include:

• Endpoint minimo che associa un input in più parti a un oggetto complesso.
• Come usare i servizi antiforgery per supportare la generazione e la convalida dei token antiforgery.

using Microsoft.AspNetCore.Antiforgery;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAntiforgery();

var app = builder.Build();

app.UseAntiforgery();

app.MapGet("/", (HttpContext context, IAntiforgery antiforgery) =>
{
    var token = antiforgery.GetAndStoreTokens(context);
    var html = $"""
        <html><body>
           <form action="/todo" method="POST" enctype="multipart/form-data">
               <input name="{token.FormFieldName}" 
                                type="hidden" value="{token.RequestToken}" />
               <input type="text" name="name" />
               <input type="date" name="dueDate" />
               <input type="checkbox" name="isCompleted" value="true" />
               <input type="submit" />
               <input name="isCompleted" type="hidden" value="false" /> 
           </form>
        </body></html>
    """;
    return Results.Content(html, "text/html");
});

app.MapPost("/todo", async Task<Results<Ok<Todo>, BadRequest<string>>> 
               ([FromForm] Todo todo, HttpContext context, IAntiforgery antiforgery) =>
{
    try
    {
        await antiforgery.ValidateRequestAsync(context);
        return TypedResults.Ok(todo);
    }
    catch (AntiforgeryValidationException e)
    {
        return TypedResults.BadRequest("Invalid antiforgery token");
    }
});

app.Run();

class Todo
{
    public string Name { get; set; } = string.Empty;
    public bool IsCompleted { get; set; } = false;
    public DateTime DueDate { get; set; } = DateTime.Now.Add(TimeSpan.FromDays(1));
}

Nel codice precedente:

• Il parametro di destinazione deve essere annotato con l'attributo [FromForm] per evitare ambiguità con i parametri che devono essere letti dal corpo JSON.
• L'associazione da tipi complessi o di raccolta non è supportata per le API minime compilate con il generatore di delegati di richiesta.
• Il markup mostra un input nascosto aggiuntivo con un nome e isCompleted un valore di false. Se la isCompleted casella di controllo viene selezionata quando il modulo viene inviato, entrambi i valori true e false vengono inviati come valori. Se la casella di controllo è deselezionata, viene inviato solo il valore false di input nascosto. Il processo di associazione di modelli core ASP.NET legge solo il primo valore quando si esegue l'associazione a un bool valore, che restituisce true le caselle false di controllo e per le caselle di controllo deselezionate.

Un esempio dei dati del modulo inviati all'endpoint precedente è simile al seguente:

__RequestVerificationToken: CfDJ8Bveip67DklJm5vI2PF2VOUZ594RC8kcGWpTnVV17zCLZi1yrs-CSz426ZRRrQnEJ0gybB0AD7hTU-0EGJXDU-OaJaktgAtWLIaaEWMOWCkoxYYm-9U9eLV7INSUrQ6yBHqdMEE_aJpD4AI72gYiCqc
name: Walk the dog
dueDate: 2024-04-06
isCompleted: true
isCompleted: false

Associare matrici e valori stringa da intestazioni e stringhe di query

Il codice seguente illustra l'associazione di stringhe di query a una matrice di tipi primitivi, matrici di stringhe e StringValues:

// Bind query string values to a primitive type array.
// GET  /tags?q=1&q=2&q=3
app.MapGet("/tags", (int[] q) =>
                      $"tag1: {q[0]} , tag2: {q[1]}, tag3: {q[2]}");

// Bind to a string array.
// GET /tags2?names=john&names=jack&names=jane
app.MapGet("/tags2", (string[] names) =>
            $"tag1: {names[0]} , tag2: {names[1]}, tag3: {names[2]}");

// Bind to StringValues.
// GET /tags3?names=john&names=jack&names=jane
app.MapGet("/tags3", (StringValues names) =>
            $"tag1: {names[0]} , tag2: {names[1]}, tag3: {names[2]}");

L'associazione di stringhe di query o valori di intestazione a una matrice di tipi complessi è supportata quando il tipo è TryParse stato implementato. Il codice seguente viene associato a una matrice di stringhe e restituisce tutti gli elementi con i tag specificati:

// GET /todoitems/tags?tags=home&tags=work
app.MapGet("/todoitems/tags", async (Tag[] tags, TodoDb db) =>
{
    return await db.Todos
        .Where(t => tags.Select(i => i.Name).Contains(t.Tag.Name))
        .ToListAsync();
});

Il codice seguente illustra il modello e l'implementazione necessaria TryParse :

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

    // This is an owned entity. 
    public Tag Tag { get; set; } = new();
}

[Owned]
public class Tag
{
    public string? Name { get; set; } = "n/a";

    public static bool TryParse(string? name, out Tag tag)
    {
        if (name is null)
        {
            tag = default!;
            return false;
        }

        tag = new Tag { Name = name };
        return true;
    }
}

Il codice seguente viene associato a una int matrice:

// GET /todoitems/query-string-ids?ids=1&ids=3
app.MapGet("/todoitems/query-string-ids", async (int[] ids, TodoDb db) =>
{
    return await db.Todos
        .Where(t => ids.Contains(t.Id))
        .ToListAsync();
});

Per testare il codice precedente, aggiungere l'endpoint seguente per popolare il database con Todo elementi:

// POST /todoitems/batch
app.MapPost("/todoitems/batch", async (Todo[] todos, TodoDb db) =>
{
    await db.Todos.AddRangeAsync(todos);
    await db.SaveChangesAsync();

    return Results.Ok(todos);
});

Usare uno strumento come HttpRepl per passare i dati seguenti all'endpoint precedente:

[
    {
        "id": 1,
        "name": "Have Breakfast",
        "isComplete": true,
        "tag": {
            "name": "home"
        }
    },
    {
        "id": 2,
        "name": "Have Lunch",
        "isComplete": true,
        "tag": {
            "name": "work"
        }
    },
    {
        "id": 3,
        "name": "Have Supper",
        "isComplete": true,
        "tag": {
            "name": "home"
        }
    },
    {
        "id": 4,
        "name": "Have Snacks",
        "isComplete": true,
        "tag": {
            "name": "N/A"
        }
    }
]

Il codice seguente viene associato alla chiave X-Todo-Id di intestazione e restituisce gli Todo elementi con valori corrispondenti Id :

// GET /todoitems/header-ids
// The keys of the headers should all be X-Todo-Id with different values
app.MapGet("/todoitems/header-ids", async ([FromHeader(Name = "X-Todo-Id")] int[] ids, TodoDb db) =>
{
    return await db.Todos
        .Where(t => ids.Contains(t.Id))
        .ToListAsync();
});

Associazione di parametri per gli elenchi di argomenti con [AsParameters]

AsParametersAttribute consente l'associazione di parametri semplice ai tipi e non l'associazione di modelli complessi o ricorsivi.

Si consideri il seguente codice :

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

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

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

app.MapGet("/todoitems/{id}",
                             async (int Id, TodoDb Db) =>
    await Db.Todos.FindAsync(Id)
        is Todo todo
            ? Results.Ok(new TodoItemDTO(todo))
            : Results.NotFound());
// Remaining code removed for brevity.

Si consideri l'endpoint seguente GET :

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

Per sostituire i parametri evidenziati precedenti, è possibile usare quanto segue struct :

struct TodoItemRequest
{
    public int Id { get; set; }
    public TodoDb Db { get; set; }
}

L'endpoint sottoposto a refactoring GET usa il precedente struct con l'attributo AsParameters :

app.MapGet("/ap/todoitems/{id}",
                                async ([AsParameters] TodoItemRequest request) =>
    await request.Db.Todos.FindAsync(request.Id)
        is Todo todo
            ? Results.Ok(new TodoItemDTO(todo))
            : Results.NotFound());

Il codice seguente mostra altri endpoint nell'app:

app.MapPost("/todoitems", async (TodoItemDTO Dto, TodoDb Db) =>
{
    var todoItem = new Todo
    {
        IsComplete = Dto.IsComplete,
        Name = Dto.Name
    };

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

    return Results.Created($"/todoitems/{todoItem.Id}", new TodoItemDTO(todoItem));
});

app.MapPut("/todoitems/{id}", async (int Id, TodoItemDTO Dto, TodoDb Db) =>
{
    var todo = await Db.Todos.FindAsync(Id);

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

    todo.Name = Dto.Name;
    todo.IsComplete = Dto.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.Ok(new TodoItemDTO(todo));
    }

    return Results.NotFound();
});

Per effettuare il refactoring degli elenchi di parametri vengono usate le classi seguenti:

class CreateTodoItemRequest
{
    public TodoItemDTO Dto { get; set; } = default!;
    public TodoDb Db { get; set; } = default!;
}

class EditTodoItemRequest
{
    public int Id { get; set; }
    public TodoItemDTO Dto { get; set; } = default!;
    public TodoDb Db { get; set; } = default!;
}

Il codice seguente illustra gli endpoint di refactoring che usano AsParameters e le classi e precedenti struct :

app.MapPost("/ap/todoitems", async ([AsParameters] CreateTodoItemRequest request) =>
{
    var todoItem = new Todo
    {
        IsComplete = request.Dto.IsComplete,
        Name = request.Dto.Name
    };

    request.Db.Todos.Add(todoItem);
    await request.Db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todoItem.Id}", new TodoItemDTO(todoItem));
});

app.MapPut("/ap/todoitems/{id}", async ([AsParameters] EditTodoItemRequest request) =>
{
    var todo = await request.Db.Todos.FindAsync(request.Id);

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

    todo.Name = request.Dto.Name;
    todo.IsComplete = request.Dto.IsComplete;

    await request.Db.SaveChangesAsync();

    return Results.NoContent();
});

app.MapDelete("/ap/todoitems/{id}", async ([AsParameters] TodoItemRequest request) =>
{
    if (await request.Db.Todos.FindAsync(request.Id) is Todo todo)
    {
        request.Db.Todos.Remove(todo);
        await request.Db.SaveChangesAsync();
        return Results.Ok(new TodoItemDTO(todo));
    }

    return Results.NotFound();
});

Per sostituire i parametri precedenti, è possibile usare i tipi seguenti record :

record TodoItemRequest(int Id, TodoDb Db);
record CreateTodoItemRequest(TodoItemDTO Dto, TodoDb Db);
record EditTodoItemRequest(int Id, TodoItemDTO Dto, TodoDb Db);

L'uso di con struct AsParameters può essere più efficiente rispetto all'uso di un record tipo .

Codice di esempio completo nel repository AspNetCore.Docs.Samples .

Associazione personalizzata

Esistono due modi per personalizzare l'associazione di parametri:

1. Per le origini di associazione di route, query e intestazione, associare tipi personalizzati aggiungendo un metodo statico TryParse per il tipo.
2. Controllare il processo di associazione implementando un BindAsync metodo su un tipo.

TryParse

TryParse ha due API:

public static bool TryParse(string value, out T result);
public static bool TryParse(string value, IFormatProvider provider, out T result);

Il codice seguente viene visualizzato Point: 12.3, 10.1 con l'URI /map?Point=12.3,10.1:

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

// GET /map?Point=12.3,10.1
app.MapGet("/map", (Point point) => $"Point: {point.X}, {point.Y}");

app.Run();

public class Point
{
    public double X { get; set; }
    public double Y { get; set; }

    public static bool TryParse(string? value, IFormatProvider? provider,
                                out Point? point)
    {
        // Format is "(12.3,10.1)"
        var trimmedValue = value?.TrimStart('(').TrimEnd(')');
        var segments = trimmedValue?.Split(',',
                StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        if (segments?.Length == 2
            && double.TryParse(segments[0], out var x)
            && double.TryParse(segments[1], out var y))
        {
            point = new Point { X = x, Y = y };
            return true;
        }

        point = null;
        return false;
    }
}

BindAsync

BindAsync include le API seguenti:

public static ValueTask<T?> BindAsync(HttpContext context, ParameterInfo parameter);
public static ValueTask<T?> BindAsync(HttpContext context);

Il codice seguente viene visualizzato SortBy:xyz, SortDirection:Desc, CurrentPage:99 con l'URI /products?SortBy=xyz&SortDir=Desc&Page=99:

using System.Reflection;

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

// GET /products?SortBy=xyz&SortDir=Desc&Page=99
app.MapGet("/products", (PagingData pageData) => $"SortBy:{pageData.SortBy}, " +
       $"SortDirection:{pageData.SortDirection}, CurrentPage:{pageData.CurrentPage}");

app.Run();

public class PagingData
{
    public string? SortBy { get; init; }
    public SortDirection SortDirection { get; init; }
    public int CurrentPage { get; init; } = 1;

    public static ValueTask<PagingData?> BindAsync(HttpContext context,
                                                   ParameterInfo parameter)
    {
        const string sortByKey = "sortBy";
        const string sortDirectionKey = "sortDir";
        const string currentPageKey = "page";

        Enum.TryParse<SortDirection>(context.Request.Query[sortDirectionKey],
                                     ignoreCase: true, out var sortDirection);
        int.TryParse(context.Request.Query[currentPageKey], out var page);
        page = page == 0 ? 1 : page;

        var result = new PagingData
        {
            SortBy = context.Request.Query[sortByKey],
            SortDirection = sortDirection,
            CurrentPage = page
        };

        return ValueTask.FromResult<PagingData?>(result);
    }
}

public enum SortDirection
{
    Default,
    Asc,
    Desc
}

Errori di associazione

Quando l'associazione non riesce, il framework registra un messaggio di debug e restituisce vari codici di stato al client a seconda della modalità di errore.

Precedenza di binding

Regole per determinare un'origine di associazione da un parametro:

1. Attributo esplicito definito per il parametro (attributi From*) nell'ordine seguente:
   1. Valori di route: [FromRoute]
   2. Stringa di query: [FromQuery]
   3. Intestazione: [FromHeader]
   4. Corpo: [FromBody]
   5. Modulo: [FromForm]
   6. Servizio: [FromServices]
   7. Valori dei parametri: [AsParameters]
2. Tipi speciali
   1. HttpContext
   2. HttpRequest (HttpContext.Request)
   3. HttpResponse (HttpContext.Response)
   4. ClaimsPrincipal (HttpContext.User)
   5. CancellationToken (HttpContext.RequestAborted)
   6. IFormCollection (HttpContext.Request.Form)
   7. IFormFileCollection (HttpContext.Request.Form.Files)
   8. IFormFile (HttpContext.Request.Form.Files[paramName])
   9. Stream (HttpContext.Request.Body)
   10. PipeReader (HttpContext.Request.BodyReader)
3. Il tipo di parametro ha un metodo statico BindAsync valido.
4. Il tipo di parametro è una stringa o ha un metodo statico TryParse valido.
   1. Se il nome del parametro esiste nel modello di route, ad esempio , app.Map("/todo/{id}", (int id) => {});è associato dalla route.
   2. Associato dalla stringa di query.
5. Se il tipo di parametro è un servizio fornito dall'inserimento delle dipendenze, usa tale servizio come origine.
6. Il parametro proviene dal corpo.

Configurare le opzioni di deserializzazione JSON per l'associazione del corpo

L'origine di associazione del corpo usa System.Text.Json per la deserializzazione. Non è possibile modificare questa impostazione predefinita, ma è possibile configurare le opzioni di serializzazione e deserializzazione JSON.

Configurare le opzioni di deserializzazione JSON a livello globale

Le opzioni applicabili a livello globale per un'app possono essere configurate richiamando ConfigureHttpJsonOptions. L'esempio seguente include campi pubblici e formatta l'output JSON.

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureHttpJsonOptions(options => {
    options.SerializerOptions.WriteIndented = true;
    options.SerializerOptions.IncludeFields = true;
});

var app = builder.Build();

app.MapPost("/", (Todo todo) => {
    if (todo is not null) {
        todo.Name = todo.NameField;
    }
    return todo;
});

app.Run();

class Todo {
    public string? Name { get; set; }
    public string? NameField;
    public bool IsComplete { get; set; }
}
// If the request body contains the following JSON:
//
// {"nameField":"Walk dog", "isComplete":false}
//
// The endpoint returns the following JSON:
//
// {
//    "name":"Walk dog",
//    "nameField":"Walk dog",
//    "isComplete":false
// }

Poiché il codice di esempio configura sia la serializzazione che la deserializzazione, può leggere NameField e includere NameField nel codice JSON di output.

Configurare le opzioni di deserializzazione JSON per un endpoint

ReadFromJsonAsync dispone di overload che accettano un JsonSerializerOptions oggetto . L'esempio seguente include campi pubblici e formatta l'output JSON.

using System.Text.Json;

var app = WebApplication.Create();

var options = new JsonSerializerOptions(JsonSerializerDefaults.Web) { 
    IncludeFields = true, 
    WriteIndented = true
};

app.MapPost("/", async (HttpContext context) => {
    if (context.Request.HasJsonContentType()) {
        var todo = await context.Request.ReadFromJsonAsync<Todo>(options);
        if (todo is not null) {
            todo.Name = todo.NameField;
        }
        return Results.Ok(todo);
    }
    else {
        return Results.BadRequest();
    }
});

app.Run();

class Todo
{
    public string? Name { get; set; }
    public string? NameField;
    public bool IsComplete { get; set; }
}
// If the request body contains the following JSON:
//
// {"nameField":"Walk dog", "isComplete":false}
//
// The endpoint returns the following JSON:
//
// {
//    "name":"Walk dog",
//    "isComplete":false
// }

Poiché il codice precedente applica le opzioni personalizzate solo alla deserializzazione, il codice JSON di output esclude NameField.

Leggere il corpo della richiesta

Leggere il corpo della richiesta direttamente usando un HttpContext parametro o HttpRequest :

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

app.MapPost("/uploadstream", async (IConfiguration config, HttpRequest request) =>
{
    var filePath = Path.Combine(config["StoredFilesPath"], Path.GetRandomFileName());

    await using var writeStream = File.Create(filePath);
    await request.BodyReader.CopyToAsync(writeStream);
});

app.Run();

Il codice precedente:

• Accede al corpo della richiesta usando HttpRequest.BodyReader.
• Copia il corpo della richiesta in un file locale.

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.

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// user middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// end user middleware/endpoints

app.UseEndpoints(e => {});

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

app.UseRouting();

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

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

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

Per altre informazioni sull'uso dell'ambiente, vedere Usare più ambienti in ASP.NET Core

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

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

Impostazione

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

Registrazione

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

Per altre informazioni, vedere Inserimento di 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 in base alle variabili di ambiente o alla 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:

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

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

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

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

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
• Intestazione
• Corpo (come JSON)
• Servizi forniti dall'inserimento delle dipendenze
• Personalizzazione

L'associazione dai valori del modulo non è supportata in modo nativo in .NET 6 e 7.

Il gestore di route seguente GET 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 { }

Nella tabella seguente viene illustrata la relazione tra i parametri usati nell'esempio precedente e le origini di associazione associate.

I metodi GETHTTP , HEAD, OPTIONSe DELETE non si associano in modo implicito dal corpo. Per eseguire l'associazione dal corpo (come JSON) per questi metodi HTTP, associare in modo esplicito [FromBody] o leggere da HttpRequest.

Il gestore di route POST di esempio seguente usa un'origine di associazione del corpo (come JSON) per il person parametro :

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapPost("/", (Person person) => { });

record Person(string Name, int Age);

I parametri negli esempi precedenti sono associati automaticamente dai dati della richiesta. Per illustrare la praticità fornita dall'associazione di parametri, i gestori di route seguenti illustrano come leggere i dati delle richieste direttamente dalla richiesta:

app.MapGet("/{id}", (HttpRequest request) =>
{
    var id = request.RouteValues["id"];
    var page = request.Query["page"];
    var customHeader = request.Headers["X-CUSTOM-HEADER"];

    // ...
});

app.MapPost("/", async (HttpRequest request) =>
{
    var person = await request.ReadFromJsonAsync<Person>();

    // ...
});

Associazione di parametri esplicita

Gli attributi possono essere usati per dichiarare in modo esplicito il percorso da cui sono associati i parametri.

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();


app.MapGet("/{id}", ([FromRoute] int id,
                     [FromQuery(Name = "p")] int page,
                     [FromServices] Service service,
                     [FromHeader(Name = "Content-Type")] string contentType) 
                     => {});

class Service { }

record Person(string Name, int Age);

Associazione di parametri con inserimento delle dipendenze

L'associazione di parametri per api minime associa i parametri tramite l'inserimento delle dipendenze quando il tipo è configurato come servizio. Non è necessario applicare in modo esplicito l'attributo [FromServices] a un parametro. Nel codice seguente entrambe le azioni restituiscono l'ora:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IDateTime, SystemDateTime>();

var app = builder.Build();

app.MapGet("/",   (               IDateTime dateTime) => dateTime.Now);
app.MapGet("/fs", ([FromServices] IDateTime dateTime) => dateTime.Now);
app.Run();

Parametri facoltativi

I parametri dichiarati nei gestori di route vengono considerati come obbligatori:

• Se una richiesta corrisponde alla route, il gestore di route viene eseguito solo se nella richiesta vengono forniti tutti i parametri obbligatori.
• Se non si specificano tutti i parametri obbligatori, viene generato un errore.

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

app.MapGet("/products", (int pageNumber) => $"Requesting page {pageNumber}");

app.Run();

Per rendere pageNumber facoltativo, definire il tipo come facoltativo o specificare un valore predefinito:

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

app.MapGet("/products", (int? pageNumber) => $"Requesting page {pageNumber ?? 1}");

string ListProducts(int pageNumber = 1) => $"Requesting page {pageNumber}";

app.MapGet("/products2", ListProducts);

app.Run();

Il valore predefinito e nullable precedente si applica a tutte le origini:

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

app.MapPost("/products", (Product? product) => { });

app.Run();

Il codice precedente chiama il metodo con un prodotto Null se non viene inviato alcun corpo della richiesta.

NOTA: se vengono forniti dati non validi e il parametro è nullable, il gestore di route non viene eseguito.

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

app.MapGet("/products", (int? pageNumber) => $"Requesting page {pageNumber ?? 1}");

app.Run();

Per altre informazioni, vedere la sezione Errori di binding .

Tipi speciali

I tipi seguenti sono associati senza attributi espliciti:

• HttpContext: contesto che contiene tutte le informazioni sulla richiesta o la risposta HTTP corrente:

  app.MapGet("/", (HttpContext context) => context.Response.WriteAsync("Hello World"));
  

• HttpRequest e HttpResponse: la richiesta HTTP e la risposta HTTP:

  app.MapGet("/", (HttpRequest request, HttpResponse response) =>
      response.WriteAsync($"Hello World {request.Query["name"]}"));
  

• CancellationToken: token di annullamento associato alla richiesta HTTP corrente:

  app.MapGet("/", async (CancellationToken cancellationToken) => 
      await MakeLongRunningRequestAsync(cancellationToken));
  

• ClaimsPrincipal: l'utente associato alla richiesta, associato da HttpContext.User:

  app.MapGet("/", (ClaimsPrincipal user) => user.Identity.Name);
  

Associare il corpo della richiesta come o StreamPipeReader

Il corpo della richiesta può essere associato come o Stream PipeReader per supportare in modo efficiente gli scenari in cui l'utente deve elaborare i dati e:

• Archiviare i dati nell'archivio BLOB o accodare i dati a un provider di code.
• Elaborare i dati archiviati con un processo di lavoro o una funzione cloud.

Ad esempio, i dati potrebbero essere accodati all'archiviazione code di Azure o archiviati nell'archivio BLOB di Azure.

Il codice seguente implementa una coda in background:

using System.Text.Json;
using System.Threading.Channels;

namespace BackgroundQueueService;

class BackgroundQueue : BackgroundService
{
    private readonly Channel<ReadOnlyMemory<byte>> _queue;
    private readonly ILogger<BackgroundQueue> _logger;

    public BackgroundQueue(Channel<ReadOnlyMemory<byte>> queue,
                               ILogger<BackgroundQueue> logger)
    {
        _queue = queue;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var dataStream in _queue.Reader.ReadAllAsync(stoppingToken))
        {
            try
            {
                var person = JsonSerializer.Deserialize<Person>(dataStream.Span)!;
                _logger.LogInformation($"{person.Name} is {person.Age} " +
                                       $"years and from {person.Country}");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex.Message);
            }
        }
    }
}

class Person
{
    public string Name { get; set; } = String.Empty;
    public int Age { get; set; }
    public string Country { get; set; } = String.Empty;
}

Il codice seguente associa il corpo della richiesta a un Streamoggetto :

app.MapPost("/register", async (HttpRequest req, Stream body,
                                 Channel<ReadOnlyMemory<byte>> queue) =>
{
    if (req.ContentLength is not null && req.ContentLength > maxMessageSize)
    {
        return Results.BadRequest();
    }

    // We're not above the message size and we have a content length, or
    // we're a chunked request and we're going to read up to the maxMessageSize + 1. 
    // We add one to the message size so that we can detect when a chunked request body
    // is bigger than our configured max.
    var readSize = (int?)req.ContentLength ?? (maxMessageSize + 1);

    var buffer = new byte[readSize];

    // Read at least that many bytes from the body.
    var read = await body.ReadAtLeastAsync(buffer, readSize, throwOnEndOfStream: false);

    // We read more than the max, so this is a bad request.
    if (read > maxMessageSize)
    {
        return Results.BadRequest();
    }

    // Attempt to send the buffer to the background queue.
    if (queue.Writer.TryWrite(buffer.AsMemory(0..read)))
    {
        return Results.Accepted();
    }

    // We couldn't accept the message since we're overloaded.
    return Results.StatusCode(StatusCodes.Status429TooManyRequests);
});

Il codice seguente mostra il file completo Program.cs :

using System.Threading.Channels;
using BackgroundQueueService;

var builder = WebApplication.CreateBuilder(args);
// The max memory to use for the upload endpoint on this instance.
var maxMemory = 500 * 1024 * 1024;

// The max size of a single message, staying below the default LOH size of 85K.
var maxMessageSize = 80 * 1024;

// The max size of the queue based on those restrictions
var maxQueueSize = maxMemory / maxMessageSize;

// Create a channel to send data to the background queue.
builder.Services.AddSingleton<Channel<ReadOnlyMemory<byte>>>((_) =>
                     Channel.CreateBounded<ReadOnlyMemory<byte>>(maxQueueSize));

// Create a background queue service.
builder.Services.AddHostedService<BackgroundQueue>();
var app = builder.Build();

// curl --request POST 'https://localhost:<port>/register' --header 'Content-Type: application/json' --data-raw '{ "Name":"Samson", "Age": 23, "Country":"Nigeria" }'
// curl --request POST "https://localhost:<port>/register" --header "Content-Type: application/json" --data-raw "{ \"Name\":\"Samson\", \"Age\": 23, \"Country\":\"Nigeria\" }"
app.MapPost("/register", async (HttpRequest req, Stream body,
                                 Channel<ReadOnlyMemory<byte>> queue) =>
{
    if (req.ContentLength is not null && req.ContentLength > maxMessageSize)
    {
        return Results.BadRequest();
    }

    // We're not above the message size and we have a content length, or
    // we're a chunked request and we're going to read up to the maxMessageSize + 1. 
    // We add one to the message size so that we can detect when a chunked request body
    // is bigger than our configured max.
    var readSize = (int?)req.ContentLength ?? (maxMessageSize + 1);

    var buffer = new byte[readSize];

    // Read at least that many bytes from the body.
    var read = await body.ReadAtLeastAsync(buffer, readSize, throwOnEndOfStream: false);

    // We read more than the max, so this is a bad request.
    if (read > maxMessageSize)
    {
        return Results.BadRequest();
    }

    // Attempt to send the buffer to the background queue.
    if (queue.Writer.TryWrite(buffer.AsMemory(0..read)))
    {
        return Results.Accepted();
    }

    // We couldn't accept the message since we're overloaded.
    return Results.StatusCode(StatusCodes.Status429TooManyRequests);
});

app.Run();

• Durante la lettura dei dati, è Stream lo stesso oggetto di HttpRequest.Body.
• Il corpo della richiesta non viene memorizzato nel buffer per impostazione predefinita. Dopo aver letto il corpo, non è riavvolgibile. Il flusso non può essere letto più volte.
• e Stream PipeReader non sono utilizzabili al di fuori del gestore di azioni minimo perché i buffer sottostanti verranno eliminati o riutilizzati.

Caricamenti di file con IFormFile e IFormFileCollection

Il codice seguente usa IFormFile e IFormFileCollection per caricare il file:

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

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

app.MapPost("/upload", async (IFormFile file) =>
{
    var tempFile = Path.GetTempFileName();
    app.Logger.LogInformation(tempFile);
    using var stream = File.OpenWrite(tempFile);
    await file.CopyToAsync(stream);
});

app.MapPost("/upload_many", async (IFormFileCollection myFiles) =>
{
    foreach (var file in myFiles)
    {
        var tempFile = Path.GetTempFileName();
        app.Logger.LogInformation(tempFile);
        using var stream = File.OpenWrite(tempFile);
        await file.CopyToAsync(stream);
    }
});

app.Run();

Le richieste di caricamento di file autenticate sono supportate tramite un'intestazione di autorizzazione, un certificato client o un'intestazionecookie.

Non è disponibile alcun supporto predefinito per l'antiforgeria in ASP.NET Core 7.0. L'antiforgeria è disponibile in ASP.NET Core 8.0 e versioni successive. Tuttavia, può essere implementata usando il IAntiforgery servizio .

Associare matrici e valori stringa da intestazioni e stringhe di query

Il codice seguente illustra l'associazione di stringhe di query a una matrice di tipi primitivi, matrici di stringhe e StringValues:

// Bind query string values to a primitive type array.
// GET  /tags?q=1&q=2&q=3
app.MapGet("/tags", (int[] q) =>
                      $"tag1: {q[0]} , tag2: {q[1]}, tag3: {q[2]}");

// Bind to a string array.
// GET /tags2?names=john&names=jack&names=jane
app.MapGet("/tags2", (string[] names) =>
            $"tag1: {names[0]} , tag2: {names[1]}, tag3: {names[2]}");

// Bind to StringValues.
// GET /tags3?names=john&names=jack&names=jane
app.MapGet("/tags3", (StringValues names) =>
            $"tag1: {names[0]} , tag2: {names[1]}, tag3: {names[2]}");

L'associazione di stringhe di query o valori di intestazione a una matrice di tipi complessi è supportata quando il tipo è TryParse stato implementato. Il codice seguente viene associato a una matrice di stringhe e restituisce tutti gli elementi con i tag specificati:

// GET /todoitems/tags?tags=home&tags=work
app.MapGet("/todoitems/tags", async (Tag[] tags, TodoDb db) =>
{
    return await db.Todos
        .Where(t => tags.Select(i => i.Name).Contains(t.Tag.Name))
        .ToListAsync();
});

Il codice seguente illustra il modello e l'implementazione necessaria TryParse :

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

    // This is an owned entity. 
    public Tag Tag { get; set; } = new();
}

[Owned]
public class Tag
{
    public string? Name { get; set; } = "n/a";

    public static bool TryParse(string? name, out Tag tag)
    {
        if (name is null)
        {
            tag = default!;
            return false;
        }

        tag = new Tag { Name = name };
        return true;
    }
}

Il codice seguente viene associato a una int matrice:

// GET /todoitems/query-string-ids?ids=1&ids=3
app.MapGet("/todoitems/query-string-ids", async (int[] ids, TodoDb db) =>
{
    return await db.Todos
        .Where(t => ids.Contains(t.Id))
        .ToListAsync();
});

Per testare il codice precedente, aggiungere l'endpoint seguente per popolare il database con Todo elementi:

// POST /todoitems/batch
app.MapPost("/todoitems/batch", async (Todo[] todos, TodoDb db) =>
{
    await db.Todos.AddRangeAsync(todos);
    await db.SaveChangesAsync();

    return Results.Ok(todos);
});

Usare uno strumento di test api come HttpRepl per passare i dati seguenti all'endpoint precedente:

[
    {
        "id": 1,
        "name": "Have Breakfast",
        "isComplete": true,
        "tag": {
            "name": "home"
        }
    },
    {
        "id": 2,
        "name": "Have Lunch",
        "isComplete": true,
        "tag": {
            "name": "work"
        }
    },
    {
        "id": 3,
        "name": "Have Supper",
        "isComplete": true,
        "tag": {
            "name": "home"
        }
    },
    {
        "id": 4,
        "name": "Have Snacks",
        "isComplete": true,
        "tag": {
            "name": "N/A"
        }
    }
]

Il codice seguente viene associato alla chiave X-Todo-Id di intestazione e restituisce gli Todo elementi con valori corrispondenti Id :

// GET /todoitems/header-ids
// The keys of the headers should all be X-Todo-Id with different values
app.MapGet("/todoitems/header-ids", async ([FromHeader(Name = "X-Todo-Id")] int[] ids, TodoDb db) =>
{
    return await db.Todos
        .Where(t => ids.Contains(t.Id))
        .ToListAsync();
});

Associazione di parametri per gli elenchi di argomenti con [AsParameters]

AsParametersAttribute consente l'associazione di parametri semplice ai tipi e non l'associazione di modelli complessi o ricorsivi.

Si consideri il seguente codice :

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

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

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

app.MapGet("/todoitems/{id}",
                             async (int Id, TodoDb Db) =>
    await Db.Todos.FindAsync(Id)
        is Todo todo
            ? Results.Ok(new TodoItemDTO(todo))
            : Results.NotFound());
// Remaining code removed for brevity.

Si consideri l'endpoint seguente GET :

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

Per sostituire i parametri evidenziati precedenti, è possibile usare quanto segue struct :

struct TodoItemRequest
{
    public int Id { get; set; }
    public TodoDb Db { get; set; }
}

L'endpoint sottoposto a refactoring GET usa il precedente struct con l'attributo AsParameters :

app.MapGet("/ap/todoitems/{id}",
                                async ([AsParameters] TodoItemRequest request) =>
    await request.Db.Todos.FindAsync(request.Id)
        is Todo todo
            ? Results.Ok(new TodoItemDTO(todo))
            : Results.NotFound());

Il codice seguente mostra altri endpoint nell'app:

app.MapPost("/todoitems", async (TodoItemDTO Dto, TodoDb Db) =>
{
    var todoItem = new Todo
    {
        IsComplete = Dto.IsComplete,
        Name = Dto.Name
    };

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

    return Results.Created($"/todoitems/{todoItem.Id}", new TodoItemDTO(todoItem));
});

app.MapPut("/todoitems/{id}", async (int Id, TodoItemDTO Dto, TodoDb Db) =>
{
    var todo = await Db.Todos.FindAsync(Id);

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

    todo.Name = Dto.Name;
    todo.IsComplete = Dto.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.Ok(new TodoItemDTO(todo));
    }

    return Results.NotFound();
});

Per effettuare il refactoring degli elenchi di parametri vengono usate le classi seguenti:

class CreateTodoItemRequest
{
    public TodoItemDTO Dto { get; set; } = default!;
    public TodoDb Db { get; set; } = default!;
}

class EditTodoItemRequest
{
    public int Id { get; set; }
    public TodoItemDTO Dto { get; set; } = default!;
    public TodoDb Db { get; set; } = default!;
}

Il codice seguente illustra gli endpoint di refactoring che usano AsParameters e le classi e precedenti struct :

app.MapPost("/ap/todoitems", async ([AsParameters] CreateTodoItemRequest request) =>
{
    var todoItem = new Todo
    {
        IsComplete = request.Dto.IsComplete,
        Name = request.Dto.Name
    };

    request.Db.Todos.Add(todoItem);
    await request.Db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todoItem.Id}", new TodoItemDTO(todoItem));
});

app.MapPut("/ap/todoitems/{id}", async ([AsParameters] EditTodoItemRequest request) =>
{
    var todo = await request.Db.Todos.FindAsync(request.Id);

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

    todo.Name = request.Dto.Name;
    todo.IsComplete = request.Dto.IsComplete;

    await request.Db.SaveChangesAsync();

    return Results.NoContent();
});

app.MapDelete("/ap/todoitems/{id}", async ([AsParameters] TodoItemRequest request) =>
{
    if (await request.Db.Todos.FindAsync(request.Id) is Todo todo)
    {
        request.Db.Todos.Remove(todo);
        await request.Db.SaveChangesAsync();
        return Results.Ok(new TodoItemDTO(todo));
    }

    return Results.NotFound();
});

Per sostituire i parametri precedenti, è possibile usare i tipi seguenti record :

record TodoItemRequest(int Id, TodoDb Db);
record CreateTodoItemRequest(TodoItemDTO Dto, TodoDb Db);
record EditTodoItemRequest(int Id, TodoItemDTO Dto, TodoDb Db);

L'uso di con struct AsParameters può essere più efficiente rispetto all'uso di un record tipo .

Codice di esempio completo nel repository AspNetCore.Docs.Samples .

Associazione personalizzata

Esistono due modi per personalizzare l'associazione di parametri:

1. Per le origini di associazione di route, query e intestazione, associare tipi personalizzati aggiungendo un metodo statico TryParse per il tipo.
2. Controllare il processo di associazione implementando un BindAsync metodo su un tipo.

TryParse

TryParse ha due API:

public static bool TryParse(string value, out T result);
public static bool TryParse(string value, IFormatProvider provider, out T result);

Il codice seguente viene visualizzato Point: 12.3, 10.1 con l'URI /map?Point=12.3,10.1:

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

// GET /map?Point=12.3,10.1
app.MapGet("/map", (Point point) => $"Point: {point.X}, {point.Y}");

app.Run();

public class Point
{
    public double X { get; set; }
    public double Y { get; set; }

    public static bool TryParse(string? value, IFormatProvider? provider,
                                out Point? point)
    {
        // Format is "(12.3,10.1)"
        var trimmedValue = value?.TrimStart('(').TrimEnd(')');
        var segments = trimmedValue?.Split(',',
                StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        if (segments?.Length == 2
            && double.TryParse(segments[0], out var x)
            && double.TryParse(segments[1], out var y))
        {
            point = new Point { X = x, Y = y };
            return true;
        }

        point = null;
        return false;
    }
}

BindAsync

BindAsync include le API seguenti:

public static ValueTask<T?> BindAsync(HttpContext context, ParameterInfo parameter);
public static ValueTask<T?> BindAsync(HttpContext context);

Il codice seguente viene visualizzato SortBy:xyz, SortDirection:Desc, CurrentPage:99 con l'URI /products?SortBy=xyz&SortDir=Desc&Page=99:

using System.Reflection;

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

// GET /products?SortBy=xyz&SortDir=Desc&Page=99
app.MapGet("/products", (PagingData pageData) => $"SortBy:{pageData.SortBy}, " +
       $"SortDirection:{pageData.SortDirection}, CurrentPage:{pageData.CurrentPage}");

app.Run();

public class PagingData
{
    public string? SortBy { get; init; }
    public SortDirection SortDirection { get; init; }
    public int CurrentPage { get; init; } = 1;

    public static ValueTask<PagingData?> BindAsync(HttpContext context,
                                                   ParameterInfo parameter)
    {
        const string sortByKey = "sortBy";
        const string sortDirectionKey = "sortDir";
        const string currentPageKey = "page";

        Enum.TryParse<SortDirection>(context.Request.Query[sortDirectionKey],
                                     ignoreCase: true, out var sortDirection);
        int.TryParse(context.Request.Query[currentPageKey], out var page);
        page = page == 0 ? 1 : page;

        var result = new PagingData
        {
            SortBy = context.Request.Query[sortByKey],
            SortDirection = sortDirection,
            CurrentPage = page
        };

        return ValueTask.FromResult<PagingData?>(result);
    }
}

public enum SortDirection
{
    Default,
    Asc,
    Desc
}

Errori di associazione

Quando l'associazione non riesce, il framework registra un messaggio di debug e restituisce vari codici di stato al client a seconda della modalità di errore.

Precedenza di binding

Regole per determinare un'origine di associazione da un parametro:

1. Attributo esplicito definito per il parametro (attributi From*) nell'ordine seguente:
   1. Valori di route: [FromRoute]
   2. Stringa di query: [FromQuery]
   3. Intestazione: [FromHeader]
   4. Corpo: [FromBody]
   5. Servizio: [FromServices]
   6. Valori dei parametri: [AsParameters]
2. Tipi speciali
   1. HttpContext
   2. HttpRequest (HttpContext.Request)
   3. HttpResponse (HttpContext.Response)
   4. ClaimsPrincipal (HttpContext.User)
   5. CancellationToken (HttpContext.RequestAborted)
   6. IFormFileCollection (HttpContext.Request.Form.Files)
   7. IFormFile (HttpContext.Request.Form.Files[paramName])
   8. Stream (HttpContext.Request.Body)
   9. PipeReader (HttpContext.Request.BodyReader)
3. Il tipo di parametro ha un metodo statico BindAsync valido.
4. Il tipo di parametro è una stringa o ha un metodo statico TryParse valido.
   1. Se il nome del parametro esiste nel modello di route. id In app.Map("/todo/{id}", (int id) => {});è associato dalla route.
   2. Associato dalla stringa di query.
5. Se il tipo di parametro è un servizio fornito dall'inserimento delle dipendenze, usa tale servizio come origine.
6. Il parametro proviene dal corpo.

Configurare le opzioni di deserializzazione JSON per l'associazione del corpo

L'origine di associazione del corpo usa System.Text.Json per la deserializzazione. Non è possibile modificare questa impostazione predefinita, ma è possibile configurare le opzioni di serializzazione e deserializzazione JSON.

Configurare le opzioni di deserializzazione JSON a livello globale

Le opzioni applicabili a livello globale per un'app possono essere configurate richiamando ConfigureHttpJsonOptions. L'esempio seguente include campi pubblici e formatta l'output JSON.

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureHttpJsonOptions(options => {
    options.SerializerOptions.WriteIndented = true;
    options.SerializerOptions.IncludeFields = true;
});

var app = builder.Build();

app.MapPost("/", (Todo todo) => {
    if (todo is not null) {
        todo.Name = todo.NameField;
    }
    return todo;
});

app.Run();

class Todo {
    public string? Name { get; set; }
    public string? NameField;
    public bool IsComplete { get; set; }
}
// If the request body contains the following JSON:
//
// {"nameField":"Walk dog", "isComplete":false}
//
// The endpoint returns the following JSON:
//
// {
//    "name":"Walk dog",
//    "nameField":"Walk dog",
//    "isComplete":false
// }

Poiché il codice di esempio configura sia la serializzazione che la deserializzazione, può leggere NameField e includere NameField nel codice JSON di output.

Configurare le opzioni di deserializzazione JSON per un endpoint

ReadFromJsonAsync dispone di overload che accettano un JsonSerializerOptions oggetto . L'esempio seguente include campi pubblici e formatta l'output JSON.

using System.Text.Json;

var app = WebApplication.Create();

var options = new JsonSerializerOptions(JsonSerializerDefaults.Web) { 
    IncludeFields = true, 
    WriteIndented = true
};

app.MapPost("/", async (HttpContext context) => {
    if (context.Request.HasJsonContentType()) {
        var todo = await context.Request.ReadFromJsonAsync<Todo>(options);
        if (todo is not null) {
            todo.Name = todo.NameField;
        }
        return Results.Ok(todo);
    }
    else {
        return Results.BadRequest();
    }
});

app.Run();

class Todo
{
    public string? Name { get; set; }
    public string? NameField;
    public bool IsComplete { get; set; }
}
// If the request body contains the following JSON:
//
// {"nameField":"Walk dog", "isComplete":false}
//
// The endpoint returns the following JSON:
//
// {
//    "name":"Walk dog",
//    "isComplete":false
// }

Poiché il codice precedente applica le opzioni personalizzate solo alla deserializzazione, il codice JSON di output esclude NameField.

Leggere il corpo della richiesta

Leggere il corpo della richiesta direttamente usando un HttpContext parametro o HttpRequest :

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

app.MapPost("/uploadstream", async (IConfiguration config, HttpRequest request) =>
{
    var filePath = Path.Combine(config["StoredFilesPath"], Path.GetRandomFileName());

    await using var writeStream = File.Create(filePath);
    await request.BodyReader.CopyToAsync(writeStream);
});

app.Run();

Il codice precedente:

• Accede al corpo della richiesta usando HttpRequest.BodyReader.
• Copia il corpo della richiesta in un file locale.