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

Tento dokument:

• Poskytuje stručný přehled pro minimální 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:

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.

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.

Více 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 runtime prostředí ASP.NET Core.

Configuration

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

Logging

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

atribut	Proměnná prostředí	Argument příkazového řádku
Název aplikace	ASPNETCORE_APPLICATIONNAME	--applicationName
Název prostředí	ASPNETCORE_ENVIRONMENT	--environment
Kořenový adresář obsahu	ASPNETCORE_CONTENTROOT	--contentRoot

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. Webový kořenový adresář je místo, kde middleware statického souboru 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();

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	Description	API
Authentication	Poskytuje podporu ověřování.	UseAuthentication
Authorization	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
Přeposílané hlavičky	Předá přeposílané hlavičky do aktuálního požadavku.	UseForwardedHeaders
Přesměrování HTTPS	Přesměruje všechny požadavky HTTP na HTTPS.	UseHttpsRedirection
Zabezpečení striktního přenosu HTTP (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
Komprese odpovědí	Poskytuje podporu pro kompresi odpovědí.	UseResponseCompression
Session	Poskytuje podporu pro správu uživatelských relací.	UseSession
Statické soubory	Poskytuje podporu pro obsluhu statických souborů a procházení adresářů.	UseStaticFiles, UseFileServer
WebSockets	Povoluje protokol WebSocket.	UseWebSockets

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

Routing

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

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

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

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

app.Run();

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

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

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

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

app.MapGet("/", LocalFunction);

app.Run();

Metoda instance

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

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

using MinAPISeparateFile;

var builder = WebApplication.CreateSlimBuilder(args);

var app = builder.Build();

TodoEndpoints.Map(app);

app.Run();

TodoEndpoints.cs

namespace MinAPISeparateFile;

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

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

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:

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:

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:

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.

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

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

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


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

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

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

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

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

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

    return group;
}

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

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.

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.

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

/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
• Header
• Text (jako JSON)
• Hodnoty formuláře
• Služby poskytované injektáží závislostí
• Custom

Následující obslužná rutina trasy GET 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 { }

Funkce vazby klíčových parametrů

• Explicitní vazba: Použijte atributy, jako jsou [FromRoute], [FromQuery], [FromHeader], [FromBody], [FromForm] a [FromServices], k explicitnímu určení zdrojů vazeb.
• Vázání formuláře: Vytváření vazby hodnot formuláře pomocí [FromForm] atributu, včetně podpory pro IFormFile a IFormFileCollection pro nahrávání souborů.
• Komplexní typy: Vazba na kolekce a komplexní typy z formulářů, dotazovacích řetězců a hlaviček.
• Vlastní vazba: Implementujte vlastní logiku vazby pomocí TryParse, BindAsync nebo IBindableFromHttpContext<T> rozhraní.
• Volitelné parametry: Podporují typy s možnou hodnotou null a výchozí hodnoty pro volitelné parametry.
• Injektáž závislostí: Parametry jsou automaticky vázány ze služeb registrovaných v kontejneru DI.
• Speciální typy: Automatické vazby pro HttpContext, HttpRequest, HttpResponse, CancellationToken, ClaimsPrincipal, , , Stream, a PipeReader.

---

Víc se uč: Podrobné informace o vazbě parametrů, včetně pokročilých scénářů, ověření, priority vazeb a řešení potíží, najdete v tématu Vazby parametrů v aplikacích s minimálním rozhraním API.

Deserializace Json+PipeReader v minimálních rozhraních API

Počínaje platformou .NET 10 používají následující funkční oblasti ASP.NET Core přetížení JsonSerializer.DeserializeAsync založená na PipeReader místo streamu:

• Minimální rozhraní API (vazby parametrů, text požadavku pro čtení)
• MVC (vstupní formátovací moduly, model)
• Metody HttpRequestJsonExtensions rozšíření pro čtení těla požadavku ve formátu JSON.

U většiny aplikací poskytuje přechod ze Streamu na PipeReader lepší výkon bez nutnosti změn v kódu aplikace. Pokud ale vaše aplikace obsahuje vlastní převaděč, převaděč nemusí správně zpracovat Utf8JsonReader.HasValueSequence . Pokud ne, může dojít k chybám, jako je ArgumentOutOfRangeException nebo chybějící data při deserializaci. Pro práci převaděče bez chyb souvisejících s PipeReader máte následující možnosti.

Možnost 1: Dočasné alternativní řešení

Rychlým alternativním řešením je vrátit se k používání Streamu bez podpory PipeReader. Pokud chcete tuto možnost implementovat, nastavte přepínač AppContext Microsoft.AspNetCore.UseStreamBasedJsonParsing na hodnotu true. Doporučujeme, abyste to udělali jenom jako dočasné alternativní řešení a co nejdříve ho aktualizujte tak, aby podporoval podporu HasValueSequence . Přepínač může být odebrán v .NET 11. Jeho jediným účelem bylo poskytnout vývojářům čas na aktualizaci jejich převaděčů.

Možnost 2: Rychlá oprava pro JsonConverter implementace

Pro tuto opravu přidělíte pole z objektu ReadOnlySequence. Tento příklad ukazuje, jak by kód vypadal:

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

Možnost 3: Složitější, ale lépe fungující oprava

Tato oprava zahrnuje nastavení samostatné cesty kódu pro ReadOnlySequence zpracování:

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

Další informace viz

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

Podpora ověřování v minimálních rozhraních API

Povolení ověřování umožňuje modulu runtime ASP.NET Core provádět ověření definovaná na:

• Query
• Header
• Obsah požadavku

Ověření jsou definována pomocí atributů v DataAnnotations oboru názvů.

Pokud je parametr minimálního koncového bodu rozhraní API třída nebo typ záznamu, automaticky se použijí ověřovací atributy. Například:

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

Vývojáři přizpůsobují chování ověřovacího systému pomocí následujících možností:

• Vytváření vlastních [Validation] implementací atributů
• Implementace rozhraní IValidatableObject pro komplexní ověřovací logiku.

Pokud se ověření nezdaří, modul runtime vrátí odpověď 400 – Chybný požadavek s podrobnostmi o chybách ověření.

Povolení integrované podpory ověřování pro minimální rozhraní API

Povolte integrovanou podporu ověřování pro minimální rozhraní API voláním AddValidation metody rozšíření pro registraci požadovaných služeb v kontejneru služby pro vaši aplikaci:

builder.Services.AddValidation();

Implementace automaticky zjišťuje typy definované v obslužných rutinách minimálního rozhraní API nebo jako základní typy typů definovaných v obslužných rutinách minimálního rozhraní API. Filtr koncového bodu provádí ověření u těchto typů a přidá se pro každý koncový bod.

Ověření je možné zakázat pro konkrétní koncové body pomocí DisableValidation metody rozšíření, jak je znázorněno v následujícím příkladu:

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

Přizpůsobení odpovědí na chyby ověřování pomocí IProblemDetailsService

Přizpůsobte odpovědi na chyby z logiky minimálního IProblemDetailsService ověření rozhraní API pomocí implementace. Zaregistrujte tuto službu v kolekci služeb vaší aplikace, abyste povolili konzistentnější odpovědi na chyby specifické pro uživatele. Podpora minimálního ověřování rozhraní API byla zavedena v ASP.NET Core v .NET 10.

Implementace vlastních odpovědí na chyby ověřování:

• Implementace IProblemDetailsService nebo použití výchozí implementace
• Registrace služby v kontejneru DI
• Ověřovací systém automaticky používá zaregistrovanou službu k formátování odpovědí na chyby ověřování.

Další informace o přizpůsobení odpovědí na chyby ověřování pomocí IProblemDetailsService najdete v tématu Vytváření odpovědí v aplikacích s minimálním rozhraním API.

Responses

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>

Návratová hodnota	Behavior	Content-Type
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

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

Návratové hodnoty JSON

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

Vrácení TypedResults

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

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

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:

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

JSON

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

Vlastní stavový kód

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

Text

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

Stream

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

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

Redirect

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

File

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:

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:

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

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 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ů. Například:

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

Filters

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

Authorization

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:

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:

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

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

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:

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:

const string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

var builder = WebApplication.CreateBuilder(args);

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

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

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

app.Run();

using Microsoft.AspNetCore.Cors;

const string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

var builder = WebApplication.CreateBuilder(args);

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

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

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

app.Run();

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

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

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:

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 rozhraních API ASP.NET Core
• 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 pozadí minimálních koncových bodů rozhraní API
• Uspořádání ASP.NET základních minimálních rozhraní API
• Diskuze o ověřování fluentu na GitHubu