Consulta rápida sobre as APIs mínimas

Este documento:

• Fornece uma referência rápida para APIs mínimas.
• Destina-se a desenvolvedores experientes. Para ver uma introdução, consulte Tutorial: Criar uma API mínima com o ASP.NET Core.

As APIs mínimas consistem em:

• WebApplication e WebApplicationBuilder
• Manipuladores de Rotas

WebApplication

O código a seguir é gerado por um modelo do ASP.NET Core:

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

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

app.Run();

O código anterior pode ser criado por meio de dotnet new web na linha de comando ou da seleção do modelo Empty Web no Visual Studio.

O código a seguir cria um WebApplication (app) sem criar explicitamente um WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create inicializa uma nova instância da classe WebApplication com padrões pré-configurados.

Trabalho com portas

Quando um aplicativo Web é criado com o Visual Studio ou com o dotnet new, aparece um arquivo Properties/launchSettings.json que especifica as portas às quais responde aplicativo. Nos exemplos de configuração de portas a seguir, a execução do aplicativo no Visual Studio retorna uma caixa de diálogo de erro Unable to connect to web server 'AppName'. O Visual Studio retorna um erro porque espera a porta especificada em Properties/launchSettings.json, mas o aplicativo está usando a porta especificada por app.Run("http://localhost:3000"). Execute a porta a seguir, alterando exemplos da linha de comando.

As seções a seguir definem a porta à qual responde o aplicativo.

var app = WebApplication.Create(args);

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

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

No código anterior, o aplicativo responde à porta 3000.

Várias portas

No código a seguir, o aplicativo responde às portas 3000 e 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Defina a porta na linha de comando

O comando a seguir faz com que o aplicativo responda à porta 7777:

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

Se o ponto de extremidade Kestrel também estiver configurado no arquivo appsettings.json, a URL especificada do arquivo appsettings.jsonserá usada. Para obter mais informações, consulte Configuração de ponto de extremidade Kestrel

Leia a porta do ambiente

O código a seguir lê a porta do ambiente:

var app = WebApplication.Create(args);

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

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

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

A maneira preferencial de definir a porta do ambiente é usar a variável de ambiente ASPNETCORE_URLS, que é mostrada na seção a seguir.

Defina as portas por meio da variável de ambiente ASPNETCORE_URLS

A variável de ambiente ASPNETCORE_URLS está disponível para definir a porta:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS dá suporte a várias URLs:

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

Escute em todas as interfaces

Os exemplos a seguir demonstram a escuta em todas as interfaces

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

Escute em todas as interfaces usando ASPNETCORE_URLS

Os exemplos anteriores podem usar ASPNETCORE_URLS

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

Escute em todas as interfaces usando ASPNETCORE_HTTPS_PORTS

Os exemplos anteriores podem usar ASPNETCORE_HTTPS_PORTS e ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Para obter mais informações, consulte Configure pontos de extremidade para o Kestrel servidor de rede ASP.NET Core

Especifique HTTPS com certificado de desenvolvimento

var app = WebApplication.Create(args);

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

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

app.Run();

Para obter mais informações sobre o certificado de desenvolvimento, consulte Confie no certificado de desenvolvimento HTTPS ASP.NET Core no Windows e no macOS.

Especifique HTTPS usando um certificado personalizado

As seções a seguir mostram como especificar o certificado personalizado usando o arquivo appsettings.json e por meio de configuração.

Especifique o certificado personalizado com appsettings.json

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

Especifique o certificado personalizado por meio de configuração

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

Use as APIs de certificado

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

Leia o ambiente

var app = WebApplication.Create(args);

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/oops");
}

app.MapGet("/", () => "Hello World");
app.MapGet("/oops", () => "Oops! An error happened.");

app.Run();

Para obter mais informações sobre como usar o ambiente, consulte ASP.NET Ambientes de runtime do Core

Configuration

O código a seguir lê a partir do sistema de configuração:

var app = WebApplication.Create(args);

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

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

app.Run();

Para obter mais informações, consulte Configuração no ASP.NET Core

Logging

O código a seguir grava uma mensagem na inicialização do aplicativo de logon:

var app = WebApplication.Create(args);

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

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

app.Run();

Para obter mais informações, consulte Log no .NET e no ASP.NET Core

Acesse o contêiner Injeção de Dependência (DI)

O código a seguir mostra como obter serviços do contêiner de DI durante a inicialização do aplicativo:

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

O código a seguir mostra como acessar chaves do contêiner de DI usando o atributo [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.";
}

Para obter mais informações sobre DI, confira Injeção de dependência no ASP.NET Core.

WebApplicationBuilder

Esta seção contém o código de exemplo usando o WebApplicationBuilder.

Altere a raiz do conteúdo, o nome do aplicativo e o ambiente

O código a seguir define a raiz do conteúdo, o nome do aplicativo e o ambiente:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    ApplicationName = typeof(Program).Assembly.FullName,
    ContentRootPath = Directory.GetCurrentDirectory(),
    EnvironmentName = Environments.Staging,
    WebRootPath = "customwwwroot"
});

Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");

var app = builder.Build();

O WebApplication.CreateBuilder inicializa uma nova instância da classe WebApplicationBuilder com os padrões pré-configurados.

Para obter mais informações, consulte visão geral dos conceitos básicos do ASP.NET Core

Altere a raiz do conteúdo, o nome do aplicativo e o ambiente usando variáveis de ambiente ou linha de comando

A tabela a seguir mostra a variável de ambiente e o argumento de linha de comando usados para alterar a raiz do conteúdo, o nome do aplicativo e o ambiente:

funcionalidade	Variável de ambiente	Argumento de linha de comando
Nome do aplicativo	ASPNETCORE_APPLICATIONNAME	--applicationName
Nome do ambiente	ASPNETCORE_ENVIRONMENT	--environment
Raiz de conteúdo	ASPNETCORE_CONTENTROOT	--contentRoot

Adicionar provedores de configuração

O exemplo a seguir adiciona o provedor de configuração INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Para maior detalhamento, consulte Provedores de configuração de arquivo em Configuração no ASP.NET Core.

Configuração de leitura

Por padrão, o WebApplicationBuilder lê a configuração de várias fontes, incluindo:

• appSettings.json e appSettings.{environment}.json
• Variáveis de ambiente
• A linha de comando

Para obter uma lista completa das fontes de configuração lidas, confira a Configuração padrão em Configuração no ASP.NET Core.

O código a seguir lê HelloKey a partir da configuração e exibe o valor no ponto de extremidade/. Se o valor de configuração for nulo, "Hello" será atribuído a message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Leia o ambiente

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Adicione provedores de login

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

Adicionar serviços

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

Personalize o IHostBuilder

Os métodos de extensão existentes no IHostBuilder podem ser acessados usando a propriedade 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();

Personalize o IWebHostBuilder

Os métodos de extensão no IWebHostBuilder podem ser acessados usando a propriedade WebApplicationBuilder.WebHost.

var builder = WebApplication.CreateBuilder(args);

// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();

var app = builder.Build();

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

app.Run();

Altere a raiz da Web

Por padrão, a raiz da Web refere-se à raiz do conteúdo na pasta wwwroot. Raiz da Web é onde o Middleware de Arquivo Estático procura arquivos estáticos. A raiz da Web pode ser alterada com o WebHostOptions, com a linha de comando ou com o método UseWebRoot:

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

var app = builder.Build();

app.Run();

Personalize o contêiner de Injeção de Dependência (DI)

O exemplo a seguir usa o 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();

Adicionar middleware

Qualquer middleware do ASP.NET Core pode ser configurado no WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Para obter mais informações, consulte Middleware do ASP.NET Core

Página de exceção do desenvolvedor

WebApplication.CreateBuilder inicializa uma nova instância da classe WebApplicationBuilder com padrões pré-configurados. A página de exceção do desenvolvedor está habilitada nos padrões pré-configurados. Quando o código a seguir é executado no ambiente de desenvolvimento, navegar para / renderiza uma página amigável que mostra a exceção.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

Middleware do ASP.NET Core

A tabela a seguir lista alguns dos middlewares usados com frequência com APIs mínimas.

Middleware	Description	API
Authentication	Fornece suporte à autenticação.	UseAuthentication
Authorization	Fornece suporte à autorização.	UseAuthorization
CORS	Configura o Compartilhamento de Recursos entre Origens.	UseCors
Manipulador de exceção	Lida globalmente com exceções geradas pelo pipeline de middleware.	UseExceptionHandler
Cabeçalhos encaminhados	Encaminha cabeçalhos como proxy para a solicitação atual.	UseForwardedHeaders
Redirecionamento https	Redireciona todas as solicitações HTTP para HTTPS.	UseHttpsRedirection
Segurança de Transporte Estrita de HTTP (HSTS)	Middleware de aprimoramento de segurança que adiciona um cabeçalho de resposta especial.	UseHsts
Solicitar registro em log	Fornece suporte para registro de solicitações e respostas HTTP.	UseHttpLogging
Tempos limite de solicitação	Fornece suporte para configurar tempos limite de solicitação, padrão global e por ponto de extremidade.	UseRequestTimeouts
Registro em log de solicitação em W3C	Fornece suporte para registro em log de solicitações e respostas HTTP no formato W3C.	UseW3CLogging
Cache de resposta	Fornece suporte para as respostas em cache.	UseResponseCaching
Compactação de resposta	Fornece suporte para a compactação de respostas.	UseResponseCompression
Session	Fornece suporte para gerenciar sessões de usuário.	UseSession
Arquivos estáticos	Fornece suporte para servir arquivos estáticos e pesquisa no diretório.	UseStaticFiles, UseFileServer
WebSockets	Habilita o protocolo WebSockets.	UseWebSockets

As seções a seguir abrangem o tratamento de solicitações: roteamento, associação de parâmetros e respostas.

Routing

Um suporte configurado e onde está um método HTTP com maiúsculas WebApplication e minúsculas, comoMap{Verb}, MapMethods, {Verb}ou Get:PostPutDelete

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

Os argumentos Delegate passados para esses métodos são chamados de "manipuladores de rota".

Manipuladores de Rotas

Manipuladores de rotas são métodos executados quando a rota corresponde. Os manipuladores de rotas podem ser uma expressão lambda, uma função local, um método de instância ou um método estático. Os manipuladores de rota podem ser síncronos ou assíncronos.

Expressão 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();

Função local

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

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

app.MapGet("/", LocalFunction);

app.Run();

Método de instância

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

Método estático

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

Ponto de extremidade definido fora do Program.cs

As APIs mínimas não precisam estar localizadas em Program.cs.

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

Também consulte Grupos de rota mais adiante neste artigo.

Pontos de extremidade nomeados e geração de link

Os pontos de extremidade podem receber nomes para gerar URLs para o ponto de extremidade. O uso de um ponto de extremidade nomeado evita ter que codificar caminhos em um aplicativo:

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

O código anterior exibe The link to the hello route is /hello do ponto de extremidade /.

OBSERVAÇÃO: os nomes de ponto de extremidade diferenciam maiúsculas e minúsculas.

Nomes de ponto de extremidade:

• Deve ser globalmente exclusivo.
• São usados como a ID da operação OpenAPI quando o suporte ao OpenAPI está habilitado. Para obter mais informações, confira OpenAPI.

Parâmetros de rota

Os parâmetros de rota podem ser capturados como parte da definição do padrão de rota:

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

O código anterior retorna The user id is 3 and book id is 7 do URI /users/3/books/7.

O manipulador de rotas pode declarar os parâmetros a serem capturados. Quando uma solicitação é feita em uma rota com parâmetros declarados para captura, os parâmetros são analisados e passados para o manipulador. Isso facilita a captura dos valores de uma maneira segura de tipo. No código anterior, userId e bookId são int.

No código anterior, se qualquer valor de rota não puder ser convertido em um int, uma exceção será gerada. A solicitação GET /users/hello/books/3 gera a seguinte exceção:

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

Caractere curinga e capturar todas as rotas

A rota catch-all a seguir retorna Routing to hello do ponto de extremidade '/posts/hello':

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

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

app.Run();

Restrições da rota

As restrições de rota restringem o comportamento correspondente de uma rota.

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

A tabela a seguir demonstra modelos de rota anteriores e seu comportamento:

Modelo de rota	URI de correspondência de exemplo
/todos/{id:int}	/todos/1
/todos/{text}	/todos/something
/posts/{slug:regex(^[a-z0-9_-]+$)}	/posts/mypost

Para obter mais informações, confira Referência de restrição de rota no Roteamento no ASP.NET Core.

Grupos de rotas

O método de extensão MapGroup ajuda a organizar grupos de pontos de extremidade com um prefixo comum. Isso reduz o código repetitivo e permite personalizar grupos inteiros de pontos de extremidade com uma única chamada a métodos como RequireAuthorization e WithMetadata, que adicionam os metadados de ponto de extremidade.

Por exemplo, o código a seguir cria dois grupos de pontos de extremidade semelhantes:

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

Nesse cenário, você pode usar um endereço relativo para o cabeçalho Location no resultado 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);
}

O primeiro grupo de pontos de extremidade corresponderá apenas às solicitações prefixadas com /public/todos e estará acessível sem autenticação. O segundo grupo de pontos de extremidade corresponderá apenas às solicitações prefixadas com /private/todos e exigirá autenticação.

A QueryPrivateTodosfábrica de filtro de ponto de extremidade é uma função local que modifica os TodoDb parâmetros do manipulador de rota para permitir o acesso e armazenamento de dados privados de tarefas.

Os grupos de rotas também permitem grupos aninhados e padrões de prefixo complexos com parâmetros de rota e restrições. No exemplo a seguir, o manipulador de rotas mapeado para o grupo user pode capturar os parâmetros de rota {org} e {group} definidos nos prefixos do grupo externo.

O prefixo também pode estar vazio. Isso pode ser útil para adicionar metadados ou filtros de ponto de extremidade a um grupo de pontos de extremidade, sem alterar o padrão de rota.

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

Adicionar filtros ou metadados a um grupo é igual a adicioná-los individualmente a cada ponto de extremidade, antes de adicionar filtros ou metadados extras que possam ter sido adicionados a um grupo interno ou ponto de extremidade específico.

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

No exemplo acima, o filtro externo registrará a solicitação de entrada antes do filtro interno, mesmo que tenha sido adicionado depois. Como os filtros foram aplicados a grupos diferentes, a ordem em que foram adicionados em relação uns aos outros não importa. A ordem em que os filtros são adicionados importa se aplicados ao mesmo grupo ou ponto de extremidade específico.

Uma solicitação para /outer/inner/ registrará o seguinte:

/outer group filter
/inner group filter
MapGet filter

Associação de parâmetros

Associação de parâmetro é o processo de converter dados de solicitação em parâmetros fortemente tipados que são expressos por manipuladores de rota. A origem de uma associação determina de onde os parâmetros são associados. As origens de associação podem ser explícitas ou inferidas com base no método HTTP e no tipo de parâmetro.

Origens de associação com suporte:

• Valores de rota
• Cadeia de consulta
• Header
• Corpo (como JSON)
• Valores de formulário
• Serviços fornecidos pela injeção de dependência
• Custom

O seguinte manipulador de rotas GET usa algumas dessas fontes de associação de parâmetros:

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

Principais recursos de associação de parâmetro

• Associação explícita: use atributos como [FromRoute], [FromQuery], [FromHeader], , [FromBody][FromForm]e [FromServices] para especificar explicitamente fontes de associação.
• : usar o atributo para associar os valores do formulário, incluindo suporte para e para uploads de arquivo.
• Tipos complexos: Vincular a coleções e tipos complexos de formulários, strings de consulta e cabeçalhos.
• Associação personalizada: implemente a lógica de associação personalizada usando TryParse, BindAsyncou a IBindableFromHttpContext<T> interface.
• Parâmetros opcionais: dão suporte a tipos anuláveis e valores padrão para parâmetros opcionais.
• Injeção de dependência: os parâmetros são automaticamente associados a serviços registrados no contêiner de DI.
• Tipos especiais: associação automática para HttpContext, HttpRequest, HttpResponse, CancellationToken, , ClaimsPrincipal, Streame PipeReader.

---

Saiba Mais: Para obter informações detalhadas sobre a associação de parâmetros, incluindo cenários avançados, validação, precedência de associação e solução de problemas, consulte Associação de parâmetros em aplicativos de API mínimos.

Desserialização de Json+PipeReader em APIs mínimas

A partir do .NET 10, as seguintes áreas funcionais do ASP.NET Core usam sobrecargas de JsonSerializer.DeserializeAsync baseadas no PipeReader em vez do Stream.

• APIs mínimas (associação de parâmetro, leitura do corpo da solicitação)
• MVC (formatores de entrada, modelo)
• Os métodos de extensão HttpRequestJsonExtensions para ler o corpo da solicitação como JSON.

Para a maioria dos aplicativos, uma transição do Stream para o PipeReader fornece melhor desempenho sem a necessidade de alterações no código do aplicativo. No entanto, se o aplicativo tiver um conversor personalizado, o conversor poderá não lidar Utf8JsonReader.HasValueSequence corretamente. Se isso não ocorrer, o resultado poderá ser erros como ArgumentOutOfRangeException ou dados ausentes ao desserializar. Você tem as seguintes opções para fazer o conversor funcionar sem erros relacionados ao PipeReader.

Opção 1: solução alternativa temporária

A solução alternativa rápida é voltar a usar o Stream sem o suporte do PipeReader. Para implementar essa alternativa, defina a opção "Microsoft.AspNetCore.UseStreamBasedJsonParsing" no AppContext como "true". Recomendamos que você faça isso apenas como uma solução alternativa temporária e atualize o conversor para dar suporte HasValueSequence o mais rápido possível. A opção pode ser removida no .NET 11. Sua única finalidade era dar aos desenvolvedores tempo para atualizar seus conversores.

Opção 2: uma correção rápida para JsonConverter implementações

Para esta correção, você aloca um array a partir do ReadOnlySequence. Este exemplo mostra como seria a aparência do código:

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

Opção 3: Uma correção mais complicada, mas com melhor desempenho

Essa correção envolve a configuração de um caminho de código separado para o tratamento do ReadOnlySequence.

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

Para obter mais informações, consulte

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

Suporte à validação em APIs mínimas

Habilitar a validação permite que o runtime do ASP.NET Core execute validações definidas no:

• Query
• Header
• Corpo da solicitação

As validações são definidas usando atributos no DataAnnotations namespace.

Quando um parâmetro de um endpoint de Minimal API é um tipo de classe ou tipo de registro, os atributos de validação são aplicados automaticamente. Por exemplo:

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

Os desenvolvedores personalizam o comportamento do sistema de validação:

• Criando implementações de atributo personalizado[Validation].
• Implementando a IValidatableObject interface para lógica de validação complexa.

Se a validação falhar, o runtime retornará uma resposta 400 – Solicitação Incorreta com detalhes dos erros de validação.

Habilitar o suporte de validação interna para APIs mínimas

Habilite o suporte de validação interna para APIs mínimas chamando o AddValidation método de extensão para registrar os serviços necessários no contêiner de serviço para seu aplicativo:

builder.Services.AddValidation();

A implementação descobre automaticamente tipos definidos em manipuladores de API mínimos ou como tipos base de tipos definidos em manipuladores de API Mínimo. Um filtro de ponto de extremidade executa a validação nesses tipos e é adicionado para cada ponto de extremidade.

A validação pode ser desabilitada para pontos de extremidade específicos usando o DisableValidation método de extensão, como no exemplo a seguir:

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

Personalizar respostas de erro de validação usando IProblemDetailsService

Personalize as respostas de erro da lógica de validação de API mínima com uma implementação IProblemDetailsService . Registre esse serviço na coleção de serviços do aplicativo para habilitar respostas de erro mais consistentes e específicas do usuário. O suporte para validação mínima de API foi introduzido no ASP.NET Core no .NET 10.

Para implementar respostas de erro de validação personalizadas:

• Implementar IProblemDetailsService ou usar a implementação padrão
• Registrar o serviço no contêiner de DI
• O sistema de validação usa automaticamente o serviço registrado para formatar respostas de erro de validação

Para obter mais informações sobre como personalizar respostas de erro de validação com IProblemDetailsService, consulte Criar respostas em aplicativos de API mínimos.

Responses

Os manipuladores de rota dão suporte aos seguintes tipos de valores retornados:

1. Baseado em IResult - Inclui Task<IResult> e ValueTask<IResult>
2. string - Inclui Task<string> e ValueTask<string>
3. T (Qualquer outro tipo) – inclui Task<T> e ValueTask<T>

Valor de retorno	Behavior	Content-Type
IResult	A estrutura chama IResult.ExecuteAsync	Decidido pela implementação de IResult
string	A estrutura grava a cadeia de caracteres diretamente na resposta	text/plain
T (Qualquer outro tipo)	A estrutura JSON serializa a resposta	application/json

Obtenha um guia mais detalhado dos valores retornados do manipulador de rota em Crie respostas em aplicativos de APIs mínimas

Exemplo de valores retornados

valores retornados de cadeias de caracteres

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

Valores JSON retornados

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

Retornar TypedResults

O código a seguir retorna um TypedResults:

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

É preferível retornar TypedResults a retornar Results. Para obter mais informações, consulte TypedResults vs Resultados.

Valores retornados de IResult

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

O exemplo a seguir usa os tipos de resultados internos para personalizar a resposta:

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

Código de status personalizado

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

Texto

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

Obtenha mais exemplos em Crie respostas em aplicativos de APIs mínimas.

Redirect

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

File

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

Resultados internos

Auxiliares de resultados comuns existem no Results e nas classes estáticas TypedResults. É preferível retornar TypedResults a retornar Results. Para obter mais informações, consulte TypedResults vs Resultados.

Modificando cabeçalhos

Use o objeto HttpResponse para modificar cabeçalhos de resposta:

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

Personalizando resultados

Aplicativos podem controlar as respostas implementando um tipo IResult personalizado. O código a seguir é um exemplo de um tipo de resultado 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);
    }
}

Recomenda-se adicionar um método de extensão a Microsoft.AspNetCore.Http.IResultExtensions para tornar esses resultados personalizados mais detectáveis.

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

Resultados tipado

A IResult interface pode representar valores retornados de APIs mínimas que não utilizam o suporte implícito para O JSON serializando o objeto retornado para a resposta HTTP. A classe estática Results é usada para criar objetos IResult variados que representam diferentes tipos de respostas. Por exemplo, configurando o código de status de resposta ou redirecionando para outra URL.

Os tipos de implementação IResult são públicos, permitindo instruções de declaração de tipo durante o teste. Por exemplo:

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

É possível examinar os tipos de retorno dos métodos correspondentes na classe estática TypedResults e localizar o tipo público IResult correto para converter.

Obtenha mais exemplos em Crie respostas em aplicativos de APIs mínimas.

Filters

Para obter mais informações, veja Filtros em aplicativos API mínimos.

Authorization

Rotas podem ser protegidas por meio de políticas de autorização. É possível declará-las por meio do atributo [Authorize] ou utilizando o método RequireAuthorization:

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

O código anterior pode ser gravado com RequireAuthorization:

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

O exemplo a seguir utiliza a autorização baseada em políticas:

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

Permita o acesso de usuários não autenticados a um ponto de extremidade

O [AllowAnonymous] permite o acesso de usuários não autenticados a pontos de extremidade:

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


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

CORS

Rotas podem ser habilitadas para CORS com as políticas CORS. O CORS pode ser declarado por meio do atributo [EnableCors] ou utilizando o método RequireCors. As seguintes amostras habilitam o 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();

Para obter mais informações, consulte Habilitar solicitações entre origens (CORS) no ASP.NET Core

ValidateScopes e ValidateOnBuild

ValidateScopes e ValidateOnBuild são habilitados por padrão no ambiente de Desenvolvimento, mas desabilitados em outros ambientes.

Quando ValidateOnBuild é true, o contêiner de DI valida a configuração do serviço no momento do build. Se a configuração do serviço for inválida, o build falhará na inicialização do aplicativo, em vez de em runtime, quando o serviço for solicitado.

Quando ValidateScopes é true, o contêiner de DI valida que um serviço com escopo não está resolvido no escopo raiz. Resolver um serviço com escopo no escopo raiz pode resultar em perda de memória porque o serviço é mantido na memória por mais tempo do que o escopo da solicitação.

ValidateScopes e ValidateOnBuild são falsos por padrão nos modos que não são de desenvolvimento por questão de desempenho.

O código a seguir mostra que ValidateScopes está habilitada por padrão no modo de desenvolvimento, mas desabilitada no modo de versão:

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

O código a seguir mostra que ValidateOnBuild está habilitada por padrão no modo de desenvolvimento, mas desabilitada no modo de versão:

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

O código a seguir desabilita ValidateScopes e ValidateOnBuild em 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;
    });
}

Consulte também

• Consulta rápida sobre as APIs mínimas
• Gerar documentos OpenAPI
• Crie respostas em aplicativos de API Mínimas
• Filtros em aplicativos de API mínima
• Manipular erros nas APIs principais do ASP.NET
• Autenticação e autorização em APIs mínimas
• Teste aplicativos de APIs Mínimas
• Roteamento de curto-circuito
• Pontos de extremidade de API do Identity
• Suporte a contêiner de injeção de dependência de serviço com chave
• Uma olhada nos bastidores de pontos de extremidade mínimos da API
• Organização de APIs mínimas do ASP.NET Core
• Discussão sobre validação fluente no GitHub