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

Tento dokument:

• Poskytuje stručný přehled minimálních rozhraní API.
• Je určený pro zkušené vývojáře. Úvod najdete v tématu Kurz: Vytvoření minimálního rozhraní API s ASP.NET Core.

Minimální rozhraní API se skládají z:

• WebApplication a WebApplicationBuilder
• Obslužné rutiny tras

WebApplication

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

C#

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:

C#

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.

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.

C#

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.

C#

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:

.NET CLI

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

C#

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

C#

var app = WebApplication.Create(args);

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

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

app.Run();

http://+:3000

C#

var app = WebApplication.Create(args);

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

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

app.Run();

http://0.0.0.0:3000

C#

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

C#

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

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

C#

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

C#

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í

C#

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:

C#

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:

C#

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:

C#

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

C#

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

C#

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

funkce	Proměnná prostředí	Argument příkazového řádku
Název aplikace	ASPNETCORE_APPLICATIONNAME	--applicationName
Název prostředí	ASPNETCORE_ENVIRONMENT	--životní prostředí
Kořen obsahu	ASPNETCORE_CONTENTROOT	--contentRoot

Přidání zprostředkovatelů konfigurace

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

C#

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:

C#

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Čtení prostředí

C#

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í

C#

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

C#

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:

C#

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.

C#

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:

C#

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:

C#

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

C#

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.

C#

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

Middleware ASP.NET Core

Následující tabulka uvádí některé z middlewarů, které se často používají s minimálními rozhraními API.

Middleware	Popis	rozhraní API
Authentication	Poskytuje podporu ověřování.	UseAuthentication
Autorizace	Poskytuje podporu autorizace.	UseAuthorization
CORS	Konfiguruje sdílení prostředků mezi zdroji (CORS).	UseCors
Obslužná rutina výjimky	Globálně zpracovává výjimky vyvolané kanálem middlewaru.	UseExceptionHandler
Forwarded Headers	Předá přeposílané hlavičky do aktuálního požadavku.	UseForwardedHeaders
HTTPS Redirection	Přesměruje všechny požadavky HTTP na HTTPS.	UseHttpsRedirection
HTTP Strict Transport Security (HSTS)	Middleware pro vylepšení zabezpečení, který přidává speciální hlavičku odpovědi.	UseHsts
Protokolování požadavku	Poskytuje podporu protokolování požadavků a odpovědí HTTP.	UseHttpLogging
Časové limity požadavků	Poskytuje podporu pro konfiguraci časových limitů požadavků, globálního výchozího a koncového bodu.	UseRequestTimeouts
Protokolování požadavků W3C	Poskytuje podporu pro protokolování požadavků HTTP a odpovědí ve formátu W3C.	UseW3CLogging
Ukládání odpovědí do mezipaměti	Poskytuje podporu pro ukládání odpovědí do mezipaměti.	UseResponseCaching
Response Compression	Poskytuje podporu pro kompresi odpovědí.	UseResponseCompression
Relace	Poskytuje podporu pro správu uživatelských relací.	UseSession
Static Files	Poskytuje podporu pro obsluhu statických souborů a procházení adresářů.	UseStaticFiles, UseFileServer
Webové sokety	Povoluje protokol WebSocket.	UseWebSockets

Následující části zahrnují zpracování požadavků: směrování, vazby parametrů a odpovědi.

Směrování

Nakonfigurovaná podpora a kde je metoda HTTP typu camel-cased, například WebApplication, Map{Verb}nebo MapMethods{Verb}:GetPostPutDelete

C#

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

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

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

app.Run();

Argumenty Delegate předané těmto metodám se nazývají "obslužné rutiny tras".

Obslužné rutiny tras

Obslužné rutiny tras jsou metody, které se spouštějí, když se trasa shoduje. Obslužné rutiny tras mohou být výraz lambda, místní funkce, metoda instance nebo statická metoda. Obslužné rutiny tras můžou být synchronní nebo asynchronní.

Výraz lambda

C#

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

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

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

app.MapGet("/", handler);

app.Run();

Místní funkce

C#

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

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

app.MapGet("/", LocalFunction);

app.Run();

Instanční metoda

C#

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

var handler = new HelloHandler();

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

app.Run();

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

Statická metoda

C#

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

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

app.Run();

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

Koncový bod definovaný mimo Program.cs

Minimální rozhraní API nemusí být umístěna v Program.csumístění .

Program.cs

C#

using MinAPISeparateFile;

var builder = WebApplication.CreateSlimBuilder(args);

var app = builder.Build();

TodoEndpoints.Map(app);

app.Run();

TodoEndpoints.cs

C#

namespace MinAPISeparateFile;

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

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

Viz také skupiny Směrování dále v tomto článku.

Pojmenované koncové body a generování propojení

Koncové body můžou mít názvy, aby se vygenerovaly adresy URL koncového bodu. Použitím pojmenovaného koncového bodu se v aplikaci nemusíte pevně zakódovat cesty:

C#

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

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

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

app.Run();

Předchozí kód se zobrazí The link to the hello route is /hello z koncového / bodu.

POZNÁMKA: V názvech koncových bodů se rozlišují malá a velká písmena.

Názvy koncových bodů:

• Musí být globálně jedinečný.
• Používají se jako ID operace OpenAPI, pokud je povolená podpora OpenAPI. Další informace najdete v tématu OpenAPI.

Parametry trasy

Parametry trasy je možné zachytit jako součást definice vzoru trasy:

C#

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

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

app.Run();

Předchozí kód vrátí The user id is 3 and book id is 7 z identifikátoru URI /users/3/books/7.

Obslužná rutina trasy může deklarovat parametry, které se mají zachytit. Při provedení požadavku na trasu s parametry deklarovanými k zachycení se parametry parsují a předávají obslužné rutině. To usnadňuje zachytávání hodnot v bezpečném typu. V předchozím kódu userId a bookId jsou oba int.

Pokud v předchozím kódu nelze převést intna některou hodnotu trasy , vyvolá se výjimka. Požadavek /users/hello/books/3 GET vyvolá následující výjimku:

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

Zástupný znak a zachycení všech tras

Následující zachytávání všech návratových tras Routing to hello z koncového bodu /posts/hello:

C#

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

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

app.Run();

Omezení trasy

Omezení trasy omezují odpovídající chování trasy.

C#

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

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

app.Run();

Následující tabulka ukazuje předchozí šablony tras a jejich chování:

Šablona trasy	Příklad odpovídajícího identifikátoru URI
/todos/{id:int}	/todos/1
/todos/{text}	/todos/something
/posts/{slug:regex(^[a-z0-9_-]+$)}	/posts/mypost

Další informace najdete v tématu Referenční informace o omezení trasy ve směrování v ASP.NET Core.

Skupiny tras

Metoda MapGroup rozšíření pomáhá uspořádat skupiny koncových bodů s běžnou předponou. Snižuje opakující se kód a umožňuje přizpůsobit celé skupiny koncových bodů jediným voláním metod, jako RequireAuthorization jsou a WithMetadata které přidávají metadata koncového bodu.

Například následující kód vytvoří dvě podobné skupiny koncových bodů:

C#

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

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


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

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

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

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

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

C#

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

    return group;
}

V tomto scénáři můžete použít relativní adresu hlavičky Location ve výsledku 201 Created :

C#

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

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

První skupina koncových bodů se bude shodovat pouze s požadavky s předponou /public/todos a jsou přístupná bez ověřování. Druhá skupina koncových bodů bude odpovídat pouze požadavkům s předponou /private/todos a vyžaduje ověření.

Objekt QueryPrivateTodospro filtrování koncových bodů je místní funkce, která upravuje parametry obslužné rutiny TodoDb trasy tak, aby umožňovala přístup k privátním datům úkolů a jejich ukládání.

Skupiny tras také podporují vnořené skupiny a složité vzory předpon s parametry trasy a omezeními. V následujícím příkladu a obslužná rutina trasy namapovaná na user skupinu může zachytit {org} parametry a {group} parametry trasy definované v předponách vnější skupiny.

Předpona může být také prázdná. To může být užitečné pro přidání metadat koncového bodu nebo filtrů do skupiny koncových bodů beze změny vzoru trasy.

C#

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

Přidání filtrů nebo metadat do skupiny se chová stejně jako jejich individuální přidání do každého koncového bodu před přidáním dalších filtrů nebo metadat, které mohly být přidány do vnitřní skupiny nebo konkrétního koncového bodu.

C#

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

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

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

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

V předchozím příkladu vnější filtr zapíše příchozí požadavek před vnitřním filtrem, i když byl přidán druhý. Vzhledem k tomu, že filtry byly použity u různých skupin, pořadí, které byly přidány vzhledem k sobě, nezáleží. Přidají se filtry objednávek bez ohledu na to, jestli se použije na stejnou skupinu nebo konkrétní koncový bod.

Žádost o /outer/inner/ protokolování bude následující:

.NET CLI

/outer group filter
/inner group filter
MapGet filter

Vazba parametru

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

C#

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.

Parametr	Zdroj vazby
id	hodnota trasy
page	řetězec dotazu
customHeader	záhlaví
service	Poskytuje injektáž závislostí

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

C#

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:

C#

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.

C#

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

Parametr	Zdroj vazby
id	hodnota trasy s názvem id
page	řetězec dotazu s názvem "p"
service	Poskytuje injektáž závislostí
contentType	header with the name "Content-Type"

Explicitní vazba z hodnot formuláře

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

C#

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 :

C#

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.

C#

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]

C#

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:

C#

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ě.

C#

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

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

app.Run();

Identifikátor URI	result
/products?pageNumber=3	Vráceno 3
/products	BadHttpRequestException: Požadovaný parametr int pageNumber nebyl poskytnut z řetězce dotazu.
/products/1	Chyba HTTP 404, žádná odpovídající trasa

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

C#

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

Identifikátor URI	result
/products?pageNumber=3	Vráceno 3
/products	1 vráceno
/products2	1 vráceno

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

C#

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í .

C#

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

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

app.Run();

Identifikátor URI	result
/products?pageNumber=3	3 vrácený
/products	1 vrácený
/products?pageNumber=two	BadHttpRequestException: Nepodařilo se vytvořit vazbu parametru "Nullable<int> pageNumber" ze dvou.
/products/two	Chyba HTTP 404, žádná odpovídající trasa

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:

  C#

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

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

  C#

  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:

  C#

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

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

  C#

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

C#

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:

C#

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:

C#

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

C#

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:

C#

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:

C#

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ů.

C#

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:

txt

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

C#

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

C#

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

C#

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 :

C#

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

C#

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

C#

[
    {
        "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:

C#

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

Poznámka

Když vytvoříte vazbu string[] z řetězce dotazu, absence odpovídající hodnoty řetězce dotazu bude mít místo hodnoty null prázdné pole.

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:

C#

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:

C#

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 :

C#

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

Refaktorovaný GET koncový bod používá předchozí struct s atributem AsParameters :

C#

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:

C#

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:

C#

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:

C#

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:

C#

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

Použití funkce with structAsParameters 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:

C#

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:

C#

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:

C#

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:

C#

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.

Režim selhání	Typ parametru s možnou hodnotou null	Zdroj vazby	Stavový kód
{ParameterType}.TryParse návraty false	ano	route/query/header	400
{ParameterType}.BindAsync návraty null	ano	vlastní	400
{ParameterType}.BindAsync hází	Nezáleží	vlastní	500
Selhání deserializace textu JSON	Nezáleží	text	400
Nesprávný typ obsahu (ne application/json)	Nezáleží	text	415

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.

C#

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.

C#

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

C#

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.

Odpovědi

Obslužné rutiny tras podporují následující typy návratových hodnot:

1. IResult na základě – to zahrnuje Task<IResult> a ValueTask<IResult>
2. string - To zahrnuje Task<string> a ValueTask<string>
3. T (Jakýkoli jiný typ) – to zahrnuje Task<T> a ValueTask<T>

Vrácená hodnota	Chování	Typ obsahu
IResult	Architektura volá IResult.ExecuteAsync.	Rozhodlo se implementací IResult
string	Architektura zapíše řetězec přímo do odpovědi.	text/plain
T (Jakýkoli jiný typ)	Rozhraní JSON serializuje odpověď.	application/json

Podrobnější průvodce směrováním vrácených hodnot obslužné rutiny najdete v tématu Vytváření odpovědí v aplikacích s minimálním rozhraním API.

Příklad návratových hodnot

řetězcové návratové hodnoty

C#

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

Návratové hodnoty JSON

C#

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

Vrácení TypedResults

Následující kód vrátí TypedResults:

C#

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

TypedResults Vrácení je upřednostňované pro vrácení Results. Další informace naleznete v tématu TypedResults vs Výsledky.

Návratové hodnoty IResult

C#

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

Následující příklad používá předdefinované typy výsledků k přizpůsobení odpovědi:

C#

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

JSON

C#

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

Vlastní stavový kód

C#

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

Text

C#

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

Stream

C#

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

Další příklady najdete v tématu Vytváření odpovědí v aplikacích s minimálním rozhraním API.

Přesměrování

C#

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

Soubor

C#

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

Předdefinované výsledky

Běžné pomocné rutiny výsledků existují ve statických ResultsTypedResults třídách. TypedResults Vrácení je upřednostňované pro vrácení Results. Další informace naleznete v tématu TypedResults vs Výsledky.

Úprava hlaviček

Pomocí objektu HttpResponse upravte hlavičky odpovědi:

C#

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

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

    return "Hello World";
});

Přizpůsobení výsledků

Aplikace můžou řídit odpovědi implementací vlastního IResult typu. Následující kód je příkladem typu výsledku HTML:

C#

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

        return new HtmlResult(html);
    }
}

class HtmlResult : IResult
{
    private readonly string _html;

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

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

Doporučujeme přidat metodu rozšíření, aby Microsoft.AspNetCore.Http.IResultExtensions byly tyto vlastní výsledky lépe zjistitelné.

C#

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

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

app.Run();

Zadané výsledky

Rozhraní IResult může představovat hodnoty vrácené z minimálních rozhraní API, která nevyužívají implicitní podporu pro serializaci JSON vráceného objektu do odpovědi HTTP. Static Results třída slouží k vytvoření různých IResult objektů, které představují různé typy odpovědí. Můžete například nastavit stavový kód odpovědi nebo přesměrovat na jinou adresu URL.

Implementované IResult typy jsou veřejné, což umožňuje při testování kontrolní výrazy typů. Příklad:

C#

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

Můžete se podívat na návratové typy odpovídajících metod ve statické TypedResults třídy najít správný veřejný IResult typ, na který se má přetypovat.

Další příklady najdete v tématu Vytváření odpovědí v aplikacích s minimálním rozhraním API.

Filtry

Další informace najdete v tématu Filtry v minimálních aplikacích API.

Autorizace

Trasy je možné chránit pomocí zásad autorizace. Tyto můžou být deklarovány prostřednictvím atributu [Authorize] nebo pomocí RequireAuthorization metody:

C#

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

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

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

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

var app = builder.Build();

app.UseAuthorization();

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

app.Run();

Předchozí kód lze napsat takto RequireAuthorization:

C#

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

Následující ukázka používá autorizaci založenou na zásadách:

C#

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

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

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

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

var app = builder.Build();

app.UseAuthorization();

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

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

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

app.Run();

Povolit neověřeným uživatelům přístup ke koncovému bodu

Umožňuje [AllowAnonymous] neověřeným uživatelům přístup ke koncovým bodům:

C#

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


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

CORS

Trasy můžou být povolené CORS pomocí zásad CORS. CORS lze deklarovat prostřednictvím atributu [EnableCors] nebo pomocí RequireCors metody. Následující ukázky umožňují CORS:

C#

const string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

var builder = WebApplication.CreateBuilder(args);

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

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

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

app.Run();

C#

using Microsoft.AspNetCore.Cors;

const string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

var builder = WebApplication.CreateBuilder(args);

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

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

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

app.Run();

Další informace najdete v tématu Povolení žádostí mezi zdroji (CORS) v ASP.NET Core

ValidateScopes a ValidateOnBuild

ValidateScopesa ValidateOnBuild jsou ve výchozím nastavení povolené ve vývojovém prostředí, ale jsou zakázané v jiných prostředích.

Pokud ValidateOnBuild je , truekontejner DI ověří konfiguraci služby v době sestavení. Pokud je konfigurace služby neplatná, sestavení selže při spuštění aplikace, a ne za běhu při vyžádání služby.

V ValidateScopes takovém případě truekontejner DI ověří, že služba s vymezeným oborem není přeložena z kořenového oboru. Překlad služby s vymezeným oborem z kořenového oboru může vést k nevracení paměti, protože služba je zachována v paměti delší než rozsah požadavku.

ValidateScopes a ValidateOnBuild jsou ve výchozím nastavení nepravdivé v režimech mimo vývoj z důvodů výkonu.

Následující kód je ValidateScopes ve výchozím nastavení povolený ve vývojovém režimu, ale v režimu vydání je zakázaný:

C#

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<MyScopedService>();

var app = builder.Build();

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

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

app.Run();

public class MyScopedService { }

Následující kód je ValidateOnBuild ve výchozím nastavení povolený ve vývojovém režimu, ale v režimu vydání je zakázaný:

C#

var builder = WebApplication.CreateBuilder(args);

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

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

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

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

app.Run();

public class MyScopedService { }

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

public class BrokenService { }

Následující kód zakáže ValidateScopes a ValidateOnBuild v Development:

C#

var builder = WebApplication.CreateBuilder(args);

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

Viz také

• Stručná referenční dokumentace k minimálním rozhraním API
• Generování dokumentů OpenAPI
• Vytváření odpovědí v aplikacích s minimálním rozhraním API
• Filtry v minimálních aplikacích API
• Zpracování chyb v minimálních rozhraních API
• Ověřování a autorizace v minimálních rozhraních API
• Testování minimálních aplikací API
• Směrování zkratek
• Identity Koncové body rozhraní API
• Podpora kontejneru injektáže závislostí služby s klíči
• Pohled na minimální koncové body rozhraní API
• Uspořádání ASP.NET základních minimálních rozhraní API
• Diskuze o ověřování fluentu na GitHubu