Associazione di parametri nelle app per le API minime

  • Articolo

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

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.

Parametro Origine del binding
id valore di route
page stringa di query
customHeader di autorizzazione
service Fornito dall'inserimento delle dipendenze

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);
Parametro Origine del binding
id valore di route con il nome id
page stringa di query con il nome "p"
service Fornito dall'inserimento delle dipendenze
contentType intestazione con il nome "Content-Type"

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();
URI result
/products?pageNumber=3 3 restituiti
/products BadHttpRequestException: il parametro obbligatorio "int pageNumber" non è stato fornito dalla stringa di query.
/products/1 Errore HTTP 404, nessuna route corrispondente

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();
URI result
/products?pageNumber=3 3 restituiti
/products 1 restituito
/products2 1 restituito

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();
URI result
/products?pageNumber=3 3 ritornato
/products 1 ritornato
/products?pageNumber=two BadHttpRequestException: impossibile associare il parametro "Nullable<int> pageNumber" da "two".
/products/two Errore HTTP 404, nessuna route corrispondente

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

Nota

Quando si associa un oggetto string[] da una stringa di query, l'assenza di qualsiasi valore della stringa di query corrispondente genererà una matrice vuota anziché un valore Null.

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.

Modalità di errore Tipo di parametro Nullable Origine del binding Codice di stato
{ParameterType}.TryParse restituisce false yes route/query/intestazione 400
{ParameterType}.BindAsync restituisce null yes custom 400
{ParameterType}.BindAsync getta Non importa custom 500
Errore di deserializzazione del corpo JSON Non importa body 400
Tipo di contenuto errato (non application/json) Non importa body 415

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.

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.

Parametro Origine del binding
id valore di route
page stringa di query
customHeader di autorizzazione
service Fornito dall'inserimento delle dipendenze

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);
Parametro Origine del binding
id valore di route con il nome id
page stringa di query con il nome "p"
service Fornito dall'inserimento delle dipendenze
contentType intestazione con il nome "Content-Type"

Nota

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

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();
URI result
/products?pageNumber=3 3 restituiti
/products BadHttpRequestException: parametro obbligatorio "int pageNumber" non fornito dalla stringa di query.
/products/1 Errore HTTP 404, nessuna route corrispondente

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();
URI result
/products?pageNumber=3 3 restituiti
/products 1 restituito
/products2 1 restituito

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();
URI result
/products?pageNumber=3 3 ritornato
/products 1 ritornato
/products?pageNumber=two BadHttpRequestException: impossibile associare il parametro "Nullable<int> pageNumber" da "two".
/products/two Errore HTTP 404, nessuna route corrispondente

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

Nota

Quando si associa un oggetto string[] da una stringa di query, l'assenza di qualsiasi valore della stringa di query corrispondente genererà una matrice vuota anziché un valore Null.

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.

Modalità di errore Tipo di parametro Nullable Origine del binding Codice di stato
{ParameterType}.TryParse restituisce false yes route/query/intestazione 400
{ParameterType}.BindAsync restituisce null yes custom 400
{ParameterType}.BindAsync getta non importa custom 500
Errore di deserializzazione del corpo JSON non importa body 400
Tipo di contenuto errato (non application/json) non importa body 415

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.