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

WebApplication

Následující kód je generován šablonou ASP.NET Core:

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

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

app.Run();

Předchozí kód lze vytvořit prostřednictvím dotnet new web příkazového řádku nebo výběrem prázdné webové šablony v sadě Visual Studio.

Následující kód vytvoří WebApplication (app) bez explicitního vytvoření WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create inicializuje novou instanci WebApplication třídy s předkonfigurovanými výchozími nastaveními.

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

Práce s porty

Při vytvoření webové aplikace pomocí sady Visual Studio nebo dotnet newProperties/launchSettings.json se vytvoří soubor, který určuje porty, na které aplikace reaguje. V ukázkách nastavení portů, které následují, vrátí spuštění aplikace ze sady Visual Studio dialogové okno Unable to connect to web server 'AppName's chybou . Visual Studio vrátí chybu, protože očekává port zadaný v Properties/launchSettings.jsonaplikaci, ale aplikace používá port určený app.Run("http://localhost:3000"). Z příkazového řádku spusťte následující ukázky změn portů.

Následující části nastavují port, na který aplikace reaguje.

var app = WebApplication.Create(args);

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

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

V předchozím kódu aplikace reaguje na port 3000.

Několik portů

V následujícím kódu aplikace reaguje na port 3000 a 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Nastavení portu z příkazového řádku

Následující příkaz způsobí, že aplikace reaguje na port 7777:

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

Kestrel Pokud je koncový bod také nakonfigurovaný v appsettings.json souboru, appsettings.json použije se zadaná adresa URL. Další informace najdete v tématu Kestrel Konfigurace koncového bodu.

Čtení portu z prostředí

Následující kód načte port z prostředí:

var app = WebApplication.Create(args);

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

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

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

Upřednostňovaným způsobem nastavení portu z prostředí je použití ASPNETCORE_URLS proměnné prostředí, která je znázorněna v následující části.

Nastavení portů prostřednictvím proměnné prostředí ASPNETCORE_URLS

Proměnná ASPNETCORE_URLS prostředí je k dispozici pro nastavení portu:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS podporuje více adres URL:

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

Naslouchání na všech rozhraních

Následující ukázky ukazují naslouchání na všech rozhraních.

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

Naslouchání všem rozhraním pomocí ASPNETCORE_URLS

Předchozí ukázky můžou použít ASPNETCORE_URLS

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

Naslouchání všem rozhraním pomocí ASPNETCORE_HTTPS_PORTS

Předchozí ukázky mohou používat ASPNETCORE_HTTPS_PORTS a ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Další informace najdete v tématu Konfigurace koncových bodů pro webový server ASP.NET Core Kestrel .

Zadání HTTPS s vývojovým certifikátem

var app = WebApplication.Create(args);

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

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

app.Run();

Další informace o vývojovém certifikátu najdete v tématu Důvěryhodnost vývojového certifikátu ASP.NET Core HTTPS ve Windows a macOS.

Zadání HTTPS pomocí vlastního certifikátu

Následující části ukazují, jak zadat vlastní certifikát pomocí appsettings.json souboru a prostřednictvím konfigurace.

Zadání vlastního certifikátu pomocí appsettings.json

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

Zadání vlastního certifikátu prostřednictvím konfigurace

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

Použití rozhraní API pro certifikáty

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

Čtení prostředí

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

Další informace o používání prostředí najdete v tématu Použití více prostředí v ASP.NET Core

Konfigurace

Následující kód čte z konfiguračního systému:

var app = WebApplication.Create(args);

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

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

app.Run();

Další informace najdete v tématu Konfigurace v ASP.NET Core

Protokolování

Následující kód zapíše zprávu do protokolu při spuštění aplikace:

var app = WebApplication.Create(args);

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

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

app.Run();

Další informace najdete v tématu Protokolování v .NET Core a ASP.NET Core

Přístup ke kontejneru injektáže závislostí (DI)

Následující kód ukazuje, jak získat služby z kontejneru DI během spouštění aplikace:

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

Následující kód ukazuje, jak přistupovat ke klíčům z kontejneru DI pomocí atributu [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.";
}

Další informace o DI naleznete v tématu Injektáž závislostí v ASP.NET Core.

WebApplicationBuilder

Tato část obsahuje vzorový kód používající WebApplicationBuilder.

Změna kořenového adresáře obsahu, názvu aplikace a prostředí

Následující kód nastaví kořen obsahu, název aplikace a prostředí:

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 inicializuje novou instanci třídy WebApplicationBuilder s předkonfigurovanými výchozími hodnotami.

Další informace najdete v tématu ASP.NET Základní základní přehled

Změna kořenového adresáře obsahu, názvu aplikace a prostředí pomocí proměnných prostředí nebo příkazového řádku

Následující tabulka ukazuje proměnnou prostředí a argument příkazového řádku použitý ke změně kořenového adresáře obsahu, názvu aplikace a prostředí:

Přidání zprostředkovatelů konfigurace

Následující ukázka přidá zprostředkovatele konfigurace INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Podrobné informace najdete v tématu Zprostředkovatelé konfigurace souborů v části Konfigurace v ASP.NET Core.

Konfigurace čtení

Ve výchozím nastavení WebApplicationBuilder konfigurace čtení z více zdrojů, včetně:

• appSettings.json a appSettings.{environment}.json
• Proměnné prostředí
• Příkazový řádek

Úplný seznam přečtených zdrojů konfigurace najdete v tématu Výchozí konfigurace v konfiguraci v ASP.NET Core.

Následující kód načte HelloKey z konfigurace a zobrazí hodnotu v koncovém / bodu. Pokud má konfigurační hodnota hodnotu null, je "Hello" přiřazeno k message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Čtení prostředí

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Přidání zprostředkovatelů protokolování

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

Přidání služeb

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

Přizpůsobení nástroje IHostBuilder

K existujícím metodám IHostBuilder rozšíření lze přistupovat pomocí vlastnosti 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();

Přizpůsobení IWebHostBuilderu

Metody rozšíření lze IWebHostBuilder získat přístup pomocí WebApplicationBuilder.WebHost vlastnost.

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

Změna webového kořenového adresáře

Ve výchozím nastavení je kořenový adresář webu relativní ke kořenovému wwwroot adresáři obsahu ve složce. Web root je místo, kde middleware statických souborů hledá statické soubory. Kořenový adresář webu lze změnit pomocí WebHostOptionspříkazového řádku nebo pomocí UseWebRoot metody:

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

var app = builder.Build();

app.Run();

Kontejner injektáže vlastních závislostí (DI)

Následující příklad používá 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();

Přidání middlewaru

Jakýkoli existující middleware ASP.NET Core je možné nakonfigurovat na :WebApplication

var app = WebApplication.Create(args);

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

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

app.Run();

Další informace najdete v tématu ASP.NET Core Middleware

Stránka výjimky pro vývojáře

WebApplication.CreateBuilder inicializuje novou instanci WebApplicationBuilder třídy s předkonfigurovanými výchozími nastaveními. Stránka výjimky vývojáře je povolená v předkonfigurovaných výchozích nastaveních. Když se ve vývojovém prostředí spustí následující kód, přejdete k / vykreslení popisné stránky, která zobrazí výjimku.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

Vazba parametru je proces převodu dat požadavku na parametry silného typu, které jsou vyjádřeny obslužnými rutinami tras. Zdroj vazby určuje, odkud jsou parametry vázány. Zdroje vazeb můžou být explicitní nebo odvozené na základě metody HTTP a typu parametru.

Podporované zdroje vazeb:

• Hodnoty tras
• Řetězec dotazu
• Hlavička
• Text (jako JSON)
• Hodnoty formuláře
• Služby poskytované injektáží závislostí
• Vlastní

Následující GET obslužná rutina trasy používá některé z těchto zdrojů vazeb parametrů:

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 { }

Následující tabulka ukazuje vztah mezi parametry použitými v předchozím příkladu a přidruženými zdroji vazeb.

Metody GETHTTP , HEAD, OPTIONSa DELETE nejsou implicitně vázány z těla. Pokud chcete vytvořit vazbu z textu (jako JSON) pro tyto metody HTTP, vytvořte vazbu explicitně s [FromBody] použitím nebo čtením z objektu HttpRequest.

Následující příklad obslužné rutiny trasy POST používá pro parametr zdroj vazby těla (jako JSON):person

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

record Person(string Name, int Age);

Parametry v předchozích příkladech jsou všechny vázány z dat požadavku automaticky. Abychom si ukázali pohodlí, které poskytuje vazba parametrů, následující obslužné rutiny tras ukazují, jak číst data požadavku přímo z požadavku:

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

    // ...
});

Explicitní vazba parametru

Atributy lze použít k explicitní deklaraci, kde jsou parametry vázány.

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

Explicitní vazba z hodnot formuláře

Atribut [FromForm] sváže hodnoty formuláře:

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.

Alternativou je použití atributu [AsParameters] s vlastním typem, který má vlastnosti anotované pomocí [FromForm]. Například následující kód vytvoří vazbu z hodnot formuláře na vlastnosti struktury záznamu NewTodoRequest :

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

Další informace najdete v části o AsParameters dále v tomto článku.

Kompletní ukázkový kód je v úložišti AspNetCore.Docs.Samples .

Zabezpečení vazby z IFormFile a IFormFileCollection

Komplexní vazba formuláře je podporována pomocí IFormFile a IFormFileCollection použití :[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();

Parametry vázané na požadavek zahrnují [FromForm] antiforgery token. Token antiforgery se ověří při zpracování požadavku. Další informace naleznete v tématu Antiforgery s minimálními rozhraními API.

Další informace naleznete v tématu Vazby formuláře v minimálních rozhraních API.

Kompletní ukázkový kód je v úložišti AspNetCore.Docs.Samples .

Vazba parametru s injektáží závislostí

Vazba parametrů pro minimální rozhraní API vytvoří vazbu parametrů prostřednictvím injektáže závislostí, když je typ nakonfigurovaný jako služba. Atribut není nutné explicitně použít [FromServices] u parametru. V následujícím kódu vrátí obě akce čas:

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

Volitelné parametry

Parametry deklarované v obslužných rutinách tras se považují za povinné:

• Pokud požadavek odpovídá trase, obslužná rutina trasy se spustí pouze v případě, že jsou v požadavku zadány všechny požadované parametry.
• Při zadání všech požadovaných parametrů dojde k chybě.

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

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

app.Run();

Pokud chcete nastavit pageNumber jako volitelný, definujte typ jako volitelný nebo zadejte výchozí hodnotu:

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

Předchozí hodnota s možnou hodnotou null a výchozí hodnotou platí pro všechny zdroje:

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

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

app.Run();

Předchozí kód volá metodu s produktem null, pokud není odeslán žádný text požadavku.

POZNÁMKA: Pokud jsou zadána neplatná data a parametr má hodnotu null, obslužná rutina trasy se nespustí .

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

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

app.Run();

Další informace najdete v části Selhání vazeb.

Speciální typy

Následující typy jsou vázané bez explicitních atributů:

• HttpContext: Kontext, který obsahuje všechny informace o aktuálním požadavku HTTP nebo odpovědi:

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

• HttpRequest a HttpResponse: Požadavek HTTP a odpověď HTTP:

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

• CancellationToken: Token zrušení přidružený k aktuálnímu požadavku HTTP:

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

• ClaimsPrincipal: Uživatel přidružený k požadavku vázanému z HttpContext.User:

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

Vytvoření vazby textu požadavku jako nebo StreamPipeReader

Tělo požadavku může svázat jako Stream scénáře nebo PipeReader efektivně podporovat scénáře, kdy uživatel musí zpracovávat data a:

• Uložte data do úložiště objektů blob nebo vytvořte frontu dat poskytovateli fronty.
• Zpracování uložených dat pomocí pracovního procesu nebo cloudové funkce

Data můžou být například zařazená do fronty Azure Storage nebo uložená ve službě Azure Blob Storage.

Následující kód implementuje frontu na pozadí:

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

Následující kód vytvoří vazbu textu požadavku na Stream:

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

Následující kód ukazuje úplný Program.cs soubor:

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

• Při čtení dat je stejný Stream objekt jako HttpRequest.Body.
• Tělo požadavku se ve výchozím nastavení neuloží do vyrovnávací paměti. Po přečtení těla se nedá převinout zpět. Stream nejde číst vícekrát.
• A Stream PipeReader nejsou použitelné mimo minimální obslužnou rutinu akce, protože podkladové vyrovnávací paměti budou uvolněny nebo znovu použity.

Nahrávání souborů pomocí IFormFile a IFormFileCollection

Následující kód používá IFormFile a IFormFileCollection nahrává soubor:

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

Žádosti o nahrání ověřených souborů se podporují pomocí autorizační hlavičky, klientského certifikátu nebo hlavičky cookie .

Vazba na formuláře pomocí IFormCollection, IFormFile a IFormFileCollection

Vazba z parametrů založených na formuláři pomocí IFormCollectionIFormFileIFormFileCollection a je podporována. Metadata OpenAPI se odvozuje pro parametry formuláře pro podporu integrace s uživatelským rozhraním Swagger.

Následující kód nahraje soubory pomocí odvozené vazby z IFormFile typu:

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

Upozornění: Při implementaci formulářů musí aplikace zabránit útokům XSRF/CSRF (Cross-Site Request Forgery). V předchozím kódu IAntiforgery se služba používá k prevenci útoků XSRF generováním a ověřením tokenu 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();

Další informace o útocích XSRF najdete v tématu Antiforgery s minimálními rozhraními API.

Další informace naleznete v tématu Vazby formuláře v minimálních rozhraních API;

Vazba na kolekce a komplexní typy z formulářů

Vazba je podporovaná pro:

• Kolekce, například Seznam a Slovník
• Složité typy, například nebo TodoProject

Následující kód ukazuje:

• Minimální koncový bod, který sváže vstup formuláře s více částmi na komplexní objekt.
• Jak používat antiforgery služby pro podporu generování a ověřování antiforgery tokenů.

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

V předchozím kódu:

• Cílový parametr musí být anotován atributem [FromForm] , aby se z parametrů, které by se měly číst z textu JSON, musí být nejednoznačný.
• Vazba ze složitých typů nebo typů kolekcí není podporována pro minimální rozhraní API kompilovaná pomocí generátoru delegáta požadavku.
• Revize zobrazuje další skrytý vstup s názvem isCompleted a hodnotou false. Pokud je zaškrtávací políčko zaškrtnuté isCompleted při odeslání formuláře, hodnoty true a false jsou odeslány jako hodnoty. Pokud políčko není zaškrtnuté, odešle se jenom skrytá vstupní hodnota false . Proces vazby modelu ASP.NET Core čte při vytváření vazby na bool hodnotu pouze první hodnotu, která má za true následek zaškrtnutí políček a false nezaškrtnutá zaškrtávací políčka.

Příklad dat formuláře odeslaných do předchozího koncového bodu vypadá takto:

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

Vytvoření vazby polí a řetězcových hodnot ze záhlaví a řetězců dotazu

Následující kód ukazuje vazby řetězců dotazu na pole primitivních typů, řetězcových polí a 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]}");

Vazby řetězců dotazu nebo hodnot hlaviček na pole komplexních typů se podporují, když je TryParse typ implementovaný. Následující kód se sváže s řetězcovým polem a vrátí všechny položky se zadanými značkami:

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

Následující kód ukazuje model a požadovanou TryParse implementaci:

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

Následující kód se sváže s polem int :

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

Pokud chcete otestovat předchozí kód, přidejte následující koncový bod pro naplnění databáze položkami Todo :

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

    return Results.Ok(todos);
});

Pomocí nástroje, jako HttpRepl je předání následujících dat do předchozího koncového bodu:

[
    {
        "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"
        }
    }
]

Následující kód vytvoří vazbu na klíč X-Todo-Id záhlaví a vrátí Todo položky s odpovídajícími Id hodnotami:

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

Vazba parametrů pro seznamy argumentů s [AsParameters]

AsParametersAttribute umožňuje jednoduchou vazbu parametrů na typy, nikoli komplexní nebo rekurzivní vazbu modelu.

Uvažujte následující kód:

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.

Zvažte následující GET koncový bod:

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

K nahrazení předchozích zvýrazněných parametrů můžete použít následující struct :

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

Refaktorovaný GET koncový bod používá předchozí struct s atributem 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());

Následující kód ukazuje další koncové body v aplikaci:

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

K refaktoringu seznamů parametrů se používají následující třídy:

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

Následující kód ukazuje refaktorované koncové body používající AsParameters a předchozí struct a třídy:

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

K nahrazení předchozích parametrů je možné použít následující record typy:

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

Použití funkce with struct AsParameters může být výkonnější než použití record typu.

Kompletní ukázkový kód v úložišti AspNetCore.Docs.Samples .

Vlastní vazba

Vazby parametrů můžete přizpůsobit dvěma způsoby:

1. Pro zdroje vazeb tras, dotazů a hlaviček vytvořte vazbu vlastních typů přidáním statické TryParse metody pro tento typ.
2. Proces vazby můžete řídit implementací BindAsync metody typu.

TryParse

TryParse má dvě rozhraní API:

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

Následující kód se zobrazí Point: 12.3, 10.1 s identifikátorem 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 má následující rozhraní API:

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

Následující kód se zobrazí SortBy:xyz, SortDirection:Desc, CurrentPage:99 s identifikátorem 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
}

Selhání vazeb

Pokud vazba selže, architektura zaznamená ladicí zprávu a v závislosti na režimu selhání vrátí klientovi různé stavové kódy.

Priorita vazby

Pravidla pro určení zdroje vazby z parametru:

1. Explicitní atribut definovaný u atributů parametru (From*) v následujícím pořadí:
   1. Hodnoty tras: [FromRoute]
   2. Řetězec dotazu: [FromQuery]
   3. Záhlaví: [FromHeader]
   4. Tělo: [FromBody]
   5. Formulář: [FromForm]
   6. Služba: [FromServices]
   7. Hodnoty parametrů: [AsParameters]
2. Speciální typy
   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. Typ parametru má platnou statickou BindAsync metodu.
4. Typ parametru je řetězec nebo má platnou statickou TryParse metodu.
   1. Pokud například název parametru existuje v šabloně app.Map("/todo/{id}", (int id) => {});trasy, je svázaný s trasou.
   2. Vázáno z řetězce dotazu.
5. Pokud je typ parametru služba poskytovaná injektáží závislostí, použije tuto službu jako zdroj.
6. Parametr je z těla.

Konfigurace možností deserializace JSON pro vazbu textu

Zdroj vazby těla používá System.Text.Json k deserializaci. Toto výchozí nastavení není možné změnit, ale je možné nakonfigurovat serializaci JSON a možnosti deserializace.

Globální konfigurace možností deserializace JSON

Možnosti, které platí globálně pro aplikaci, je možné nakonfigurovat vyvoláním ConfigureHttpJsonOptions. Následující příklad obsahuje veřejná pole a formátuje výstup 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
// }

Vzhledem k tomu, že vzorový kód konfiguruje serializaci i deserializaci, může číst NameField a zahrnout NameField do výstupního kódu JSON.

Konfigurace možností deserializace JSON pro koncový bod

ReadFromJsonAsync má přetížení, které přijímají JsonSerializerOptions objekt. Následující příklad obsahuje veřejná pole a formátuje výstup 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
// }

Vzhledem k tomu, že předchozí kód aplikuje přizpůsobené možnosti pouze na deserializaci, výstupní JSON vylučuje NameField.

Čtení textu požadavku

Text požadavku si můžete přečíst přímo pomocí parametru nebo parametru HttpContext 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();

Předchozí kód:

• Přistupuje k textu požadavku pomocí HttpRequest.BodyReader.
• Zkopíruje text požadavku do místního souboru.

WebApplication

Následující kód je generován šablonou ASP.NET Core:

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

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

app.Run();

Předchozí kód lze vytvořit prostřednictvím dotnet new web příkazového řádku nebo výběrem prázdné webové šablony v sadě Visual Studio.

Následující kód vytvoří WebApplication (app) bez explicitního vytvoření WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create inicializuje novou instanci WebApplication třídy s předkonfigurovanými výchozími nastaveními.

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

Práce s porty

Při vytvoření webové aplikace pomocí sady Visual Studio nebo dotnet newProperties/launchSettings.json se vytvoří soubor, který určuje porty, na které aplikace reaguje. V ukázkách nastavení portů, které následují, vrátí spuštění aplikace ze sady Visual Studio dialogové okno Unable to connect to web server 'AppName's chybou . Visual Studio vrátí chybu, protože očekává port zadaný v Properties/launchSettings.jsonaplikaci, ale aplikace používá port určený app.Run("http://localhost:3000"). Z příkazového řádku spusťte následující ukázky změn portů.

Následující části nastavují port, na který aplikace reaguje.

var app = WebApplication.Create(args);

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

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

V předchozím kódu aplikace reaguje na port 3000.

Několik portů

V následujícím kódu aplikace reaguje na port 3000 a 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Nastavení portu z příkazového řádku

Následující příkaz způsobí, že aplikace reaguje na port 7777:

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

Kestrel Pokud je koncový bod také nakonfigurovaný v appsettings.json souboru, appsettings.json použije se zadaná adresa URL. Další informace najdete v tématu Kestrel Konfigurace koncového bodu.

Čtení portu z prostředí

Následující kód načte port z prostředí:

var app = WebApplication.Create(args);

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

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

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

Upřednostňovaným způsobem nastavení portu z prostředí je použití ASPNETCORE_URLS proměnné prostředí, která je znázorněna v následující části.

Nastavení portů prostřednictvím proměnné prostředí ASPNETCORE_URLS

Proměnná ASPNETCORE_URLS prostředí je k dispozici pro nastavení portu:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS podporuje více adres URL:

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

Další informace o používání prostředí najdete v tématu Použití více prostředí v ASP.NET Core

Naslouchání na všech rozhraních

Následující ukázky ukazují naslouchání na všech rozhraních.

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

Naslouchání všem rozhraním pomocí ASPNETCORE_URLS

Předchozí ukázky můžou použít ASPNETCORE_URLS

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

Zadání HTTPS s vývojovým certifikátem

var app = WebApplication.Create(args);

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

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

app.Run();

Další informace o vývojovém certifikátu najdete v tématu Důvěryhodnost vývojového certifikátu ASP.NET Core HTTPS ve Windows a macOS.

Zadání HTTPS pomocí vlastního certifikátu

Následující části ukazují, jak zadat vlastní certifikát pomocí appsettings.json souboru a prostřednictvím konfigurace.

Zadání vlastního certifikátu pomocí appsettings.json

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

Zadání vlastního certifikátu prostřednictvím konfigurace

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

Použití rozhraní API pro certifikáty

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

Konfigurace

Následující kód čte z konfiguračního systému:

var app = WebApplication.Create(args);

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

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

app.Run();

Další informace najdete v tématu Konfigurace v ASP.NET Core

Protokolování

Následující kód zapíše zprávu do protokolu při spuštění aplikace:

var app = WebApplication.Create(args);

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

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

app.Run();

Další informace najdete v tématu Protokolování v .NET Core a ASP.NET Core

Přístup ke kontejneru injektáže závislostí (DI)

Následující kód ukazuje, jak získat služby z kontejneru DI během spouštění aplikace:

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

Další informace naleznete v tématu Injektáž závislostí v ASP.NET Core.

WebApplicationBuilder

Tato část obsahuje vzorový kód používající WebApplicationBuilder.

Změna kořenového adresáře obsahu, názvu aplikace a prostředí

Následující kód nastaví kořen obsahu, název aplikace a prostředí:

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 inicializuje novou instanci třídy WebApplicationBuilder s předkonfigurovanými výchozími hodnotami.

Další informace najdete v tématu ASP.NET Základní základní přehled

Změna kořenového adresáře obsahu, názvu aplikace a prostředí podle proměnných prostředí nebo příkazového řádku

Následující tabulka ukazuje proměnnou prostředí a argument příkazového řádku použitý ke změně kořenového adresáře obsahu, názvu aplikace a prostředí:

Přidání zprostředkovatelů konfigurace

Následující ukázka přidá zprostředkovatele konfigurace INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Podrobné informace najdete v tématu Zprostředkovatelé konfigurace souborů v části Konfigurace v ASP.NET Core.

Konfigurace čtení

Ve výchozím nastavení WebApplicationBuilder konfigurace čtení z více zdrojů, včetně:

• appSettings.json a appSettings.{environment}.json
• Proměnné prostředí
• Příkazový řádek

Následující kód načte HelloKey z konfigurace a zobrazí hodnotu v koncovém / bodu. Pokud má konfigurační hodnota hodnotu null, je "Hello" přiřazeno k message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Úplný seznam přečtených zdrojů konfigurace najdete v tématu Výchozí konfigurace v konfiguraci v ASP.NET Core.

Přidání zprostředkovatelů protokolování

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

Přidání služeb

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

Přizpůsobení nástroje IHostBuilder

K existujícím metodám IHostBuilder rozšíření lze přistupovat pomocí vlastnosti 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();

Přizpůsobení IWebHostBuilderu

Metody rozšíření lze IWebHostBuilder získat přístup pomocí WebApplicationBuilder.WebHost vlastnost.

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

Změna webového kořenového adresáře

Ve výchozím nastavení je kořenový adresář webu relativní ke kořenovému wwwroot adresáři obsahu ve složce. Web root je místo, kde middleware statických souborů hledá statické soubory. Kořenový adresář webu lze změnit pomocí WebHostOptionspříkazového řádku nebo pomocí UseWebRoot metody:

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

var app = builder.Build();

app.Run();

Kontejner injektáže vlastních závislostí (DI)

Následující příklad používá 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();

Přidání middlewaru

Jakýkoli existující middleware ASP.NET Core je možné nakonfigurovat na :WebApplication

var app = WebApplication.Create(args);

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

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

app.Run();

Další informace najdete v tématu ASP.NET Core Middleware

Stránka výjimky pro vývojáře

WebApplication.CreateBuilder inicializuje novou instanci WebApplicationBuilder třídy s předkonfigurovanými výchozími nastaveními. Stránka výjimky vývojáře je povolená v předkonfigurovaných výchozích nastaveních. Když se ve vývojovém prostředí spustí následující kód, přejdete k / vykreslení popisné stránky, která zobrazí výjimku.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

Vazba parametru je proces převodu dat požadavku na parametry silného typu, které jsou vyjádřeny obslužnými rutinami tras. Zdroj vazby určuje, odkud jsou parametry vázány. Zdroje vazeb můžou být explicitní nebo odvozené na základě metody HTTP a typu parametru.

Podporované zdroje vazeb:

• Hodnoty tras
• Řetězec dotazu
• Hlavička
• Text (jako JSON)
• Služby poskytované injektáží závislostí
• Vlastní

Vazba z hodnot formulářů není nativně podporována v .NET 6 a 7.

Následující GET obslužná rutina trasy používá některé z těchto zdrojů vazeb parametrů:

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 { }

Následující tabulka ukazuje vztah mezi parametry použitými v předchozím příkladu a přidruženými zdroji vazeb.

Metody GETHTTP , HEAD, OPTIONSa DELETE nejsou implicitně vázány z těla. Pokud chcete vytvořit vazbu z textu (jako JSON) pro tyto metody HTTP, vytvořte vazbu explicitně s [FromBody] použitím nebo čtením z objektu HttpRequest.

Následující příklad obslužné rutiny trasy POST používá pro parametr zdroj vazby těla (jako JSON):person

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

record Person(string Name, int Age);

Parametry v předchozích příkladech jsou všechny vázány z dat požadavku automaticky. Abychom si ukázali pohodlí, které poskytuje vazba parametrů, následující obslužné rutiny tras ukazují, jak číst data požadavku přímo z požadavku:

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

    // ...
});

Explicitní vazba parametru

Atributy lze použít k explicitní deklaraci, kde jsou parametry vázány.

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

Vazba parametru s injektáží závislostí

Vazba parametrů pro minimální rozhraní API vytvoří vazbu parametrů prostřednictvím injektáže závislostí, když je typ nakonfigurovaný jako služba. Atribut není nutné explicitně použít [FromServices] u parametru. V následujícím kódu vrátí obě akce čas:

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

Volitelné parametry

Parametry deklarované v obslužných rutinách tras se považují za povinné:

• Pokud požadavek odpovídá trase, obslužná rutina trasy se spustí pouze v případě, že jsou v požadavku zadány všechny požadované parametry.
• Při zadání všech požadovaných parametrů dojde k chybě.

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

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

app.Run();

Pokud chcete nastavit pageNumber jako volitelný, definujte typ jako volitelný nebo zadejte výchozí hodnotu:

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

Předchozí hodnota s možnou hodnotou null a výchozí hodnotou platí pro všechny zdroje:

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

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

app.Run();

Předchozí kód volá metodu s produktem null, pokud není odeslán žádný text požadavku.

POZNÁMKA: Pokud jsou zadána neplatná data a parametr má hodnotu null, obslužná rutina trasy se nespustí .

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

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

app.Run();

Další informace najdete v části Selhání vazeb.

Speciální typy

Následující typy jsou vázané bez explicitních atributů:

• HttpContext: Kontext, který obsahuje všechny informace o aktuálním požadavku HTTP nebo odpovědi:

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

• HttpRequest a HttpResponse: Požadavek HTTP a odpověď HTTP:

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

• CancellationToken: Token zrušení přidružený k aktuálnímu požadavku HTTP:

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

• ClaimsPrincipal: Uživatel přidružený k požadavku vázanému z HttpContext.User:

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

Vytvoření vazby textu požadavku jako nebo StreamPipeReader

Tělo požadavku může svázat jako Stream scénáře nebo PipeReader efektivně podporovat scénáře, kdy uživatel musí zpracovávat data a:

• Uložte data do úložiště objektů blob nebo vytvořte frontu dat poskytovateli fronty.
• Zpracování uložených dat pomocí pracovního procesu nebo cloudové funkce

Data můžou být například zařazená do fronty Azure Storage nebo uložená ve službě Azure Blob Storage.

Následující kód implementuje frontu na pozadí:

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

Následující kód vytvoří vazbu textu požadavku na Stream:

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

Následující kód ukazuje úplný Program.cs soubor:

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

• Při čtení dat je stejný Stream objekt jako HttpRequest.Body.
• Tělo požadavku se ve výchozím nastavení neuloží do vyrovnávací paměti. Po přečtení těla se nedá převinout zpět. Stream nejde číst vícekrát.
• A Stream PipeReader nejsou použitelné mimo minimální obslužnou rutinu akce, protože podkladové vyrovnávací paměti budou uvolněny nebo znovu použity.

Nahrávání souborů pomocí IFormFile a IFormFileCollection

Následující kód používá IFormFile a IFormFileCollection nahrává soubor:

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

Žádosti o nahrání ověřených souborů se podporují pomocí autorizační hlavičky, klientského certifikátu nebo hlavičky cookie .

V systému ASP.NET Core 7.0 neexistuje integrovaná podpora antiforgery . Antiforgery je k dispozici v systému ASP.NET Core 8.0 a novějším. Dá se ale implementovat pomocí IAntiforgery služby.

Vytvoření vazby polí a řetězcových hodnot ze záhlaví a řetězců dotazu

Následující kód ukazuje vazby řetězců dotazu na pole primitivních typů, řetězcových polí a 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]}");

Vazby řetězců dotazu nebo hodnot hlaviček na pole komplexních typů se podporují, když je TryParse typ implementovaný. Následující kód se sváže s řetězcovým polem a vrátí všechny položky se zadanými značkami:

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

Následující kód ukazuje model a požadovanou TryParse implementaci:

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

Následující kód se sváže s polem int :

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

Pokud chcete otestovat předchozí kód, přidejte následující koncový bod pro naplnění databáze položkami Todo :

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

    return Results.Ok(todos);
});

Použijte testovací nástroj rozhraní API, jako HttpRepl je předání následujících dat do předchozího koncového bodu:

[
    {
        "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"
        }
    }
]

Následující kód vytvoří vazbu na klíč X-Todo-Id záhlaví a vrátí Todo položky s odpovídajícími Id hodnotami:

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

Vazba parametrů pro seznamy argumentů s [AsParameters]

AsParametersAttribute umožňuje jednoduchou vazbu parametrů na typy, nikoli komplexní nebo rekurzivní vazbu modelu.

Uvažujte následující kód:

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.

Zvažte následující GET koncový bod:

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

K nahrazení předchozích zvýrazněných parametrů můžete použít následující struct :

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

Refaktorovaný GET koncový bod používá předchozí struct s atributem 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());

Následující kód ukazuje další koncové body v aplikaci:

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

K refaktoringu seznamů parametrů se používají následující třídy:

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

Následující kód ukazuje refaktorované koncové body používající AsParameters a předchozí struct a třídy:

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

K nahrazení předchozích parametrů je možné použít následující record typy:

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

Použití funkce with struct AsParameters může být výkonnější než použití record typu.

Kompletní ukázkový kód v úložišti AspNetCore.Docs.Samples .

Vlastní vazba

Vazby parametrů můžete přizpůsobit dvěma způsoby:

1. Pro zdroje vazeb tras, dotazů a hlaviček vytvořte vazbu vlastních typů přidáním statické TryParse metody pro tento typ.
2. Proces vazby můžete řídit implementací BindAsync metody typu.

TryParse

TryParse má dvě rozhraní API:

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

Následující kód se zobrazí Point: 12.3, 10.1 s identifikátorem 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 má následující rozhraní API:

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

Následující kód se zobrazí SortBy:xyz, SortDirection:Desc, CurrentPage:99 s identifikátorem 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
}

Selhání vazeb

Pokud vazba selže, architektura zaznamená ladicí zprávu a v závislosti na režimu selhání vrátí klientovi různé stavové kódy.

Priorita vazby

Pravidla pro určení zdroje vazby z parametru:

1. Explicitní atribut definovaný u atributů parametru (From*) v následujícím pořadí:
   1. Hodnoty tras: [FromRoute]
   2. Řetězec dotazu: [FromQuery]
   3. Záhlaví: [FromHeader]
   4. Tělo: [FromBody]
   5. Služba: [FromServices]
   6. Hodnoty parametrů: [AsParameters]
2. Speciální typy
   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. Typ parametru má platnou statickou BindAsync metodu.
4. Typ parametru je řetězec nebo má platnou statickou TryParse metodu.
   1. Pokud název parametru existuje v šabloně trasy. V app.Map("/todo/{id}", (int id) => {});, id je vázána z trasy.
   2. Vázáno z řetězce dotazu.
5. Pokud je typ parametru služba poskytovaná injektáží závislostí, použije tuto službu jako zdroj.
6. Parametr je z těla.

Konfigurace možností deserializace JSON pro vazbu textu

Zdroj vazby těla používá System.Text.Json k deserializaci. Toto výchozí nastavení není možné změnit, ale je možné nakonfigurovat serializaci JSON a možnosti deserializace.

Globální konfigurace možností deserializace JSON

Možnosti, které platí globálně pro aplikaci, je možné nakonfigurovat vyvoláním ConfigureHttpJsonOptions. Následující příklad obsahuje veřejná pole a formátuje výstup 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
// }

Vzhledem k tomu, že vzorový kód konfiguruje serializaci i deserializaci, může číst NameField a zahrnout NameField do výstupního kódu JSON.

Konfigurace možností deserializace JSON pro koncový bod

ReadFromJsonAsync má přetížení, které přijímají JsonSerializerOptions objekt. Následující příklad obsahuje veřejná pole a formátuje výstup 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
// }

Vzhledem k tomu, že předchozí kód aplikuje přizpůsobené možnosti pouze na deserializaci, výstupní JSON vylučuje NameField.

Čtení textu požadavku

Text požadavku si můžete přečíst přímo pomocí parametru nebo parametru HttpContext 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();

Předchozí kód:

• Přistupuje k textu požadavku pomocí HttpRequest.BodyReader.
• Zkopíruje text požadavku do místního souboru.