Краткий справочник по минимальным API

Этот документ:

• Предоставляет краткий справочник по минимальным API.
• Предназначен для опытных разработчиков. Общие сведения см. в руководстве по созданию минимального API с помощью ASP.NET Core.

Минимальные API состоят из следующих:

• WebApplication и WebApplicationBuilder.
• Обработчики маршрутов

WebApplication

Шаблон ASP.NET Core создает следующий код:

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

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

app.Run();

Приведенный выше код можно создать, набрав dotnet new web в командной строке или выбрав в Visual Studio шаблон пустого веб-проекта.

Следующий код создает WebApplication (app) без явного создания WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create инициализирует новый экземпляр класса WebApplication с предварительно настроенными значениями по умолчанию.

Использование портов

Если вы создаете веб-приложение с помощью Visual Studio или dotnet new, автоматически создается файл Properties/launchSettings.json с указанием портов, на которых отвечает это приложение. Запуск приложения из Visual Studio с параметрами портов, представленными в следующих примерах, возвращает диалоговое окно с сообщением об ошибке Unable to connect to web server 'AppName'. Visual Studio возвращает ошибку, так как ожидается порт, указанный в Properties/launchSettings.json, но приложение использует порт, указанный в app.Run("http://localhost:3000"). Выполните в командной строке следующий пример кода для изменения портов.

В следующих разделах задается порт, на котором отвечает приложение.

var app = WebApplication.Create(args);

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

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

В приведенном выше коде приложение использует порт 3000.

Несколько портов

В следующем коде приложение использует порты 3000 и 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Настройка порта из командной строки

Следующая команда настраивает для приложения работу с портом 7777:

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

Если в файле Kestrel настроена еще и конечная точка appsettings.json, то используется файл с URL-адресом, указанным в appsettings.json. Дополнительные сведения см. в разделе Конфигурация конечной точки Kestrel.

Получение порта из среды

Следующий код считывает значение порта из среды:

var app = WebApplication.Create(args);

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

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

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

Для настройки порта из среды лучше всего использовать переменную среды ASPNETCORE_URLS, как показано в следующем разделе.

Настройка портов через переменную среды ASPNETCORE_URLS

Для настройки порта существует переменная среды ASPNETCORE_URLS:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS поддерживает несколько URL-адресов:

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

Ожидание передачи данных на всех интерфейсах

В следующих примерах демонстрируется ожидание передачи данных на всех интерфейсах

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

Ожидание передачи данных на всех интерфейсах с помощью ASPNETCORE_URLS

В предыдущих примерах можно использовать ASPNETCORE_URLS

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

Прослушивание всех интерфейсов с помощью ASPNETCORE_HTTPS_PORTS

Приведенные выше примеры могут использовать ASPNETCORE_HTTPS_PORTS и ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Дополнительные сведения см. в разделе "Настройка конечных точек" для веб-сервера ASP.NET Core Kestrel

Выбор протокола HTTPS с сертификатом разработки

var app = WebApplication.Create(args);

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

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

app.Run();

Дополнительные сведения о сертификате разработки см. в разделе Доверие к сертификату разработки HTTPS в среде ASP.NET Core на ОС Windows и macOS.

Указание протокола HTTPS с пользовательским сертификатом

В следующих разделах показано, как указать пользовательский сертификат с помощью appsettings.json файла и конфигурации.

Настройка пользовательского сертификата в appsettings.json

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

Настройка пользовательского сертификата в конфигурации

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

Использование API сертификатов

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

Чтение данных из среды

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

Дополнительные сведения об использовании среды см. в средах выполнения ASP.NET Core

Configuration

Следующий код считывает данные из системы конфигурации:

var app = WebApplication.Create(args);

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

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

app.Run();

Дополнительные сведения см. в статье Конфигурация в ASP.NET Core.

Logging

Следующий код записывает сообщение в журнал при запуске приложения:

var app = WebApplication.Create(args);

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

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

app.Run();

Дополнительные сведения см. в разделе "Ведение журнала" в .NET и ASP.NET Core

Доступ к контейнеру внедрения зависимостей (DI)

В следующем коде показано, как получить службы из контейнера DI во время запуска приложения.

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

В следующем коде показано, как получить доступ к ключам из контейнера DI с помощью атрибута [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.";
}

Дополнительные сведения о внедрении зависимостей см. в разделе ASP.NET Core.

WebApplicationBuilder

Пример кода в этом разделе использует WebApplicationBuilder.

Изменение корневой папки содержимого, имени приложения и среды

Следующий код задает корневую папку для содержимого, имя приложения и среду:

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 инициализирует новый экземпляр класса WebApplicationBuilder с предварительно настроенными значениями по умолчанию.

Дополнительные сведения см. в статье Обзор основных понятий ASP.NET Core.

Изменение корневого каталога содержимого, имени приложения и среды с помощью переменных среды или командной строки

В следующей таблице представлены переменные среды и аргументы командной строки, которые позволяют изменить корневую папку содержимого, имя приложения и среду:

feature	Переменная среды	Аргумент командной строки
Имя приложения	ASPNETCORE_APPLICATIONNAME	--applicationName
Имя среды	ASPNETCORE_ENVIRONMENT	--environment
Корневой каталог содержимого	ASPNETCORE_CONTENTROOT	--contentRoot

Все поставщики конфигурации

Следующий пример добавляет поставщик конфигурации INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Дополнительные сведения см. в разделе Поставщики конфигурации файлов в статье Конфигурация в ASP.NET Core.

Конфигурация чтения

По умолчанию WebApplicationBuilder считывает конфигурацию из нескольких источников, в том числе:

• appSettings.json и appSettings.{environment}.json.
• Переменные среды
• Командная строка

Полный список источников конфигурации см. в разделе "Конфигурация по умолчанию" в ASP.NET Core.

Следующий код считывает из конфигурации значение HelloKey и отображает его в конечной точке /. Если это значение конфигурации равно NULL, в message сохраняется значение "Hello":

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Чтение данных из среды

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Добавление поставщиков ведения журнала

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

Добавление служб

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

Настройка IHostBuilder

К существующим методам расширения IHostBuilder можно обращаться через свойство 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();

Настройка IWebHostBuilder

К существующим методам расширения IWebHostBuilder можно обращаться через свойство 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();

Изменение корневой папки веб-сайта

Корневая папка веб-сайта задается относительно корневой папки содержимого. По умолчанию это wwwroot. Веб-корень — это место, где Промежуточное ПО для статических файлов ищет статические файлы. Корневой веб-сайт можно изменить с помощью WebHostOptions, командной строки или метода UseWebRoot:

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

var app = builder.Build();

app.Run();

Пользовательский контейнер внедрения зависимостей (DI)

В следующем примере используется 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();

Добавление ПО промежуточного слоя

Любое существующее ПО промежуточного слоя для ASP.NET Core можно настроить в WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Дополнительные сведения см. в статье ПО промежуточного слоя ASP.NET Core.

Страница со сведениями об исключении для разработчика

WebApplication.CreateBuilder инициализирует новый экземпляр класса WebApplicationBuilder с предварительно настроенными значениями по умолчанию. Страница исключений для разработчиков включена в предварительно настроенных параметрах по умолчанию. При выполнении следующего кода в среде разработки переход к адресу / отображает страницу с удобным представлением информации об исключении.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

ПО промежуточного слоя ASP.NET Core

В следующей таблице перечислены некоторые из по промежуточного слоя, часто используемого с минимальными API.

Middleware	Description	API
Authentication	Обеспечивает поддержку проверки подлинности.	UseAuthentication
Authorization	Обеспечивает поддержку авторизации.	UseAuthorization
CORS	Настраивает общий доступ к ресурсам независимо от источника.	UseCors
Обработчик исключений	Глобально обрабатывает исключения, создаваемые конвейером ПО промежуточного слоя.	UseExceptionHandler
Переадресация заголовков	Пересылает заголовки, переданные через прокси-сервер, в текущий запрос.	UseForwardedHeaders
Перенаправление HTTPS	Перенаправляет все запросы с HTTP на HTTPS.	UseHttpsRedirection
Строгое обеспечение безопасности транспорта HTTP (HSTS)	ПО промежуточного слоя для повышения безопасности, которое добавляет специальный заголовок ответа.	UseHsts
Ведение журнала запросов	Обеспечивает поддержку ведения журнала для HTTP-запросов и ответов на них.	UseHttpLogging
Время ожидания запроса	Предоставляет поддержку настройки времени ожидания запроса, глобального значения по умолчанию и для каждой конечной точки.	UseRequestTimeouts
Ведение журнала запросов W3C	Обеспечивает поддержку ведения журнала для HTTP-запросов и ответов на них в формате консорциума W3C.	UseW3CLogging
Кэширование ответов	Обеспечивает поддержку для кэширования откликов.	UseResponseCaching
Сжатие ответов	Обеспечивает поддержку для сжатия откликов.	UseResponseCompression
Session	Обеспечивает поддержку для управления пользовательскими сеансами.	UseSession
Статические файлы	Обеспечивает поддержку для обработки статических файлов и просмотра каталогов.	UseStaticFiles, UseFileServer
WebSockets	Обеспечивает поддержку протокола WebSockets.	UseWebSockets

В следующих разделах рассматриваются обработка запросов: маршрутизация, привязка параметров и ответы.

Routing

Настроенный WebApplication метод поддерживает Map{Verb} и MapMethods где {Verb} используется метод HTTP с регистром верблюда, например Get, Post, Putили Delete:

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

Аргументы Delegate , передаваемые этим методам, называются обработчиками маршрутов.

Обработчики маршрутов

Обработчики маршрутов — это методы, которые выполняются при обнаружении соответствия для маршрута. В роли обработчика маршрут может выступать лямбда-выражение, локальная функция, метод экземпляра или статический метод. Обработчики маршрутов могут быть синхронными или асинхронными.

Лямбда-выражение

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

Локальная функция

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

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

app.MapGet("/", LocalFunction);

app.Run();

Метод экземпляра

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

Статический метод

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

Конечная точка, определенная вне Program.cs

Минимальные API не должны находиться в 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" });
        });
    }
}

См. также группы маршрутов далее в этой статье.

Именованные конечные точки и создание ссылок

Конечные точки можно указать имена для создания URL-адресов конечной точки. Использование именованной конечной точки позволяет избежать сложных путей кода в приложении:

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

Приведенный выше код отображает The link to the hello route is /hello из конечной точки /.

ПРИМЕЧАНИЕ. Имена конечных точек чувствительны к регистру.

Имена конечных точек:

• Оно должно быть глобально уникальным.
• используются в качестве идентификатора операции OpenAPI, если включена поддержка OpenAPI. Дополнительные сведения см. в статье OpenAPI.

Параметры маршрута

Параметры маршрута могут быть захвачены в составе определения шаблона маршрута:

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

Приведенный выше код возвращает The user id is 3 and book id is 7 из URI /users/3/books/7.

Обработчик маршрута может объявлять параметры, которые нужно захватывать. Когда запрос выполняется в маршрут с параметрами, объявленными для записи, параметры анализируются и передаются обработчику. Это позволяет легко получать значения в строго типизированном виде. В приведенном выше коде userId и bookId имеют тип int.

В приведенном выше коде создается исключение, если значение маршрута не может быть преобразовано в тип int. Запрос GET по маршруту /users/hello/books/3 выдает следующее исключение:

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

Использование подстановочных знаков и перехват всех маршрутов

Следующая функция перехвата всех маршрутов возвращает значение Routing to hello из конечной точки "/posts/hello":

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

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

app.Run();

Ограничения маршрута

Ограничения маршрута ограничивают возможности сопоставления маршрута.

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

В приведенной ниже таблице перечислены представленные выше примеры шаблонов маршрутов и их поведение.

Шаблон маршрута	Пример соответствующего URI
/todos/{id:int}	/todos/1
/todos/{text}	/todos/something
/posts/{slug:regex(^[a-z0-9_-]+$)}	/posts/mypost

Дополнительные сведения см. в разделе Справочник по ограничениям маршрутов в статье Маршрутизация в ASP.NET Core.

Группы маршрутов

Метод MapGroup расширения помогает упорядочивать группы конечных точек с общим префиксом. Это уменьшает повторяющийся код и позволяет настраивать целые группы конечных точек с одним вызовом методов, таких как RequireAuthorization и WithMetadata которые добавляют метаданные конечной точки.

Например, следующий код создает две аналогичные группы конечных точек:

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

В этом сценарии можно использовать относительный адрес заголовка Location201 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);
}

Первая группа конечных точек будет соответствовать только запросам, префиксным и /public/todos доступным без какой-либо проверки подлинности. Вторая группа конечных точек будет соответствовать только запросам, префиксным и /private/todos требующим проверки подлинности.

Фабрика QueryPrivateTodos фильтров конечных точек — это локальная функция, которая изменяет параметры обработчика TodoDb маршрутов, чтобы разрешить доступ к частным данным и хранить данные о частных объектах.

Группы маршрутов также поддерживают вложенные группы и сложные шаблоны префикса с параметрами маршрута и ограничениями. В следующем примере обработчик маршрутов, сопоставленный с user группой, может записывать {org} параметры маршрута, {group} определенные в префиксах внешней группы.

Префикс также может быть пустым. Это может быть полезно для добавления метаданных конечной точки или фильтров в группу конечных точек без изменения шаблона маршрута.

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

Добавление фильтров или метаданных в группу ведет себя так же, как и их отдельно к каждой конечной точке перед добавлением дополнительных фильтров или метаданных, которые могли быть добавлены во внутреннюю группу или определенную конечную точку.

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

В приведенном выше примере внешний фильтр регистрирует входящий запрос до внутреннего фильтра, даже если он был добавлен вторым. Так как фильтры были применены к разным группам, порядок их добавления относительно друг друга не имеет значения. Фильтры заказов добавляются, если они применяются к той же группе или определенной конечной точке.

Запрос, который /outer/inner/ будет регистрировать следующее:

/outer group filter
/inner group filter
MapGet filter

Привязка параметров

Привязка параметров — это процесс преобразования данных запроса в строго типизированные параметры, выраженные обработчиками маршрутов. Источник привязки определяет, откуда будут привязаны параметры. Источники привязки могут быть явными или выведенными на основе метода HTTP и типа параметра.

Поддерживаемые источники привязки:

• Значения маршрута
• Строка запроса
• Header
• текст (в формате JSON);
• Значения формы
• службы, предоставляемые путем внедрения зависимостей;
• Custom

В следующем обработчике маршрутов GET используются некоторые из этих источников привязки параметров:

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

Функции привязки ключевых параметров

• Явная привязка: используйте такие атрибуты, как [FromRoute], [FromQuery], [FromHeader], [FromBody][FromForm]и [FromServices] для явного указания источников привязки.
• Привязка формы: Привязывайте значения формы с помощью [FromForm] атрибута, включая поддержку IFormFile и IFormFileCollection для загрузки файлов.
• Сложные типы: привязка к коллекциям и сложным типам из форм, строк запроса и заголовков.
• Настраиваемая привязка: реализуйте пользовательскую логику привязки с помощью TryParse, BindAsync или интерфейса IBindableFromHttpContext<T>.
• Необязательные параметры: поддержка типов, допускающих значение NULL, и значений по умолчанию для необязательных параметров.
• Внедрение зависимостей: параметры автоматически привязаны к службам, зарегистрированным в контейнере DI.
• Специальные типы: автоматическая привязка для HttpContext, HttpRequest, HttpResponse, CancellationTokenClaimsPrincipalи StreamPipeReader.

---

Подробнее: Подробные сведения о привязке параметров, включая расширенные сценарии, проверку, приоритет привязки и устранение неполадок, см. в разделе "Привязка параметров" в минимальных приложениях API.

Десериализация Json+PipeReader в минимальных API

Начиная с .NET 10, следующие функциональные области ASP.NET Core используют перегрузки JsonSerializer.DeserializeAsync на основе PipeReader вместо Stream:

• Minimal APIs (привязка параметров, чтение тела запроса)
• MVC (входные форматы, модель)
• Методы расширения HttpRequestJsonExtensions для чтения тела запроса как JSON.

Для большинства приложений переход с Stream на PipeReader обеспечивает более высокую производительность, не требуя изменений в коде приложения. Но если в вашем приложении используется пользовательский преобразователь, то преобразователь может неправильно обработать Utf8JsonReader.HasValueSequence. Если это не так, результатом могут быть такие ошибки, как ArgumentOutOfRangeException, или отсутствие данных при десериализации. Чтобы ваш преобразователь работал без ошибок, связанных с PipeReader, у вас есть следующие варианты.

Вариант 1. Временное решение

Краткое решение заключается в том, чтобы вернуться к использованию Stream без поддержки PipeReader. Чтобы реализовать эту опцию, установите переключатель AppContext "Microsoft.AspNetCore.UseStreamBasedJsonParsing" в значение "true". Мы рекомендуем сделать это только в качестве временного обходного решения и обновить преобразователь, чтобы обеспечить поддержку HasValueSequence как можно скорее. Переключатель может быть удален в .NET 11. Его единственной целью было дать разработчикам время обновить их преобразователи.

Вариант 2: Быстрое решение для JsonConverter реализаций

Для этого исправления вы выделяете массив из ReadOnlySequence. В этом примере показано, как выглядит код:

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

Вариант 3. Более сложное, но более эффективное исправление

Это исправление включает настройку отдельного пути кода для 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
    }
}

Дополнительные сведения см. в разделе

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

Поддержка проверки в минимальных API

Включение проверки позволяет среде выполнения ASP.NET Core выполнять проверки, определенные в следующих параметрах:

• Query
• Header
• Основное содержание запроса

Проверки определяются с помощью атрибутов в DataAnnotations пространстве имен.

Атрибуты проверки автоматически применяются, если параметр для конечной точки Minimal API является классом или записью. Рассмотрим пример.

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

Разработчики настраивают поведение системы проверки следующим образом:

• Создание пользовательских [Validation] реализаций атрибутов .
• Реализация интерфейса IValidatableObject для сложной логики проверки.

Если проверка завершается ошибкой, среда выполнения возвращает ответ 400 — недопустимый запрос с подробными сведениями об ошибках проверки.

Включение встроенной поддержки проверки для минимальных API

Включите встроенную поддержку проверки минимальных API, вызвав AddValidation метод расширения, чтобы зарегистрировать необходимые службы в контейнере службы для приложения:

builder.Services.AddValidation();

Реализация автоматически обнаруживает типы, определенные в минимальных обработчиках API или в качестве базовых типов типов, определенных в обработчиках API Min. Фильтр конечной точки выполняет проверку этих типов и добавляется для каждой конечной точки.

Проверка может быть отключена для определенных конечных точек с помощью DisableValidation метода расширения, как показано в следующем примере:

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

Настройка ответов на ошибки проверки с помощью IProblemDetailsService

Настройте ответы на ошибки из минимальной IProblemDetailsService логики проверки API с помощью реализации. Зарегистрируйте эту службу в коллекции служб приложения, чтобы обеспечить более согласованные и пользовательские ответы на ошибки. Поддержка минимальной проверки API появилась в ASP.NET Core в .NET 10.

Чтобы реализовать пользовательские ответы на ошибки проверки, выполните следующее:

• Реализация IProblemDetailsService или использование реализации по умолчанию
• Регистрация службы в контейнере DI
• Система проверки автоматически использует зарегистрированную службу для форматирования ответов на ошибки проверки.

Дополнительные сведения о настройке ответов на ошибки проверки с помощью IProblemDetailsService см. в статье "Создание ответов в приложениях API "Минимальный".

Responses

Обработчики маршрутов поддерживают следующие типы возвращаемых значений:

1. на основе IResult, например Task<IResult> и ValueTask<IResult>;
2. string, например Task<string> и ValueTask<string>;
3. T (любой другой тип), например Task<T> и ValueTask<T>.

Возвращаемое значение	Behavior	Content-Type
IResult	Платформа вызывает IResult.ExecuteAsync	Определяется реализацией IResult
string	Платформа записывает строку непосредственно в ответ	text/plain
T (любой другой тип)	Платформа JSON-сериализует ответ	application/json

Более подробное руководство по возврату возвращаемых значений обработчика маршрутов см. в статье "Создание ответов в приложениях API с минимальным количеством"

Примеры возвращаемых значений

Строковые возвращаемые значения

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

Возвращаемые значения в формате JSON

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

Возврат типизированных результатов

Следующий код возвращает TypedResultsследующий код:

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

TypedResults Возврат предпочтительнее возвращатьResults. Дополнительные сведения см. в разделе TypedResults и Results.

Возвращаемые значения в формате IResult

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

В следующем примере для настройки ответа используются встроенные типы результатов:

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

Пользовательский код состояния

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

Дополнительные примеры см. в статье "Создание ответов в минимальных приложениях API".

Redirect

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

File

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

Встроенные результаты

Распространенные вспомогательные средства результатов существуют в и Results статических TypedResults классах. TypedResults Возврат предпочтительнее возвращатьResults. Дополнительные сведения см. в разделе TypedResults и Results.

Изменение заголовков

Используйте объект HttpResponse для изменения заголовков ответов:

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

Настройка результатов

Приложения могут управлять ответами через пользовательскую реализацию типа IResult. Следующий код является примером результата с типом 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);
    }
}

Мы рекомендуем добавить в Microsoft.AspNetCore.Http.IResultExtensions метод расширения, чтобы эти пользовательские результаты было проще искать.

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

Типизированные результаты

Интерфейс IResult может представлять значения, возвращаемые из минимальных API, которые не используют неявную поддержку сериализации возвращаемого объекта в ответ HTTP. Статический класс Results используется для создания разных объектов IResult, которые представляют разные типы ответов. Например, установка кода статуса ответа или перенаправление на другой URL-адрес.

Реализуемые типы IResult являются общедоступными, что позволяет использовать утверждения типов при тестировании. Рассмотрим пример.

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

Вы можете просмотреть возвращаемые типы соответствующих методов в статическом классе TypedResults , чтобы найти правильный общедоступный IResult тип для приведения.

Дополнительные примеры см. в статье "Создание ответов в минимальных приложениях API".

Filters

Дополнительные сведения см. в статьях "Фильтры" в приложениях API "Минимальный".

Authorization

Для защиты маршрутов можно применять политики авторизации. Они могут быть объявлены через атрибут [Authorize] или с помощью метода 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();

Приведенный выше код можно создать с использованием RequireAuthorization:

app.MapGet("/auth", () => "This endpoint requires authorization")
   .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("/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();

Разрешение доступа к конечной точке пользователям, не прошедшим проверку подлинности

[AllowAnonymous] разрешает доступ к конечным точкам пользователям, не прошедшим проверку подлинности:

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


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

CORS

Для маршрутов можно включить CORS с помощью политик CORS. CORS можно объявить через атрибут [EnableCors] или с помощью метода RequireCors. В следующих примерах включается 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();

Дополнительные сведения см. в статье Включение запросов CORS в ASP.NET Core.

ValidateScopes и ValidateOnBuild

ValidateScopes и ValidateOnBuild включены по умолчанию в среде разработки , но отключены в других средах.

Когда ValidateOnBuild это trueтак, контейнер DI проверяет конфигурацию службы во время сборки. Если конфигурация службы недопустима, сборка завершается ошибкой при запуске приложения, а не во время выполнения при запросе службы.

Когда ValidateScopes это trueтак, контейнер DI проверяет, не разрешена ли служба с областью действия из корневой области. Разрешение ограниченной службы из корневой области может привести к утечке памяти, так как служба хранится в памяти дольше, чем область запроса.

ValidateScopes значение ValidateOnBuild false по умолчанию в режимах, отличных от разработки, по соображениям производительности.

Следующий код по ValidateScopes умолчанию включен в режиме разработки, но отключен в режиме выпуска:

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

Следующий код по ValidateOnBuild умолчанию включен в режиме разработки, но отключен в режиме выпуска:

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

Следующий код отключает ValidateScopes и ValidateOnBuild в 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;
    });
}

См. также

• Краткий справочник по минимальным API
• Создание документов OpenAPI
• Создание ответов в минимальных приложениях API
• Фильтры в минимальных приложениях API
• Обработка ошибок в api ASP.NET Core
• Проверка подлинности и авторизация в минимальных API
• Тестирование минимальных приложений API
• Маршрутизация с коротким каналом
• Identity Конечные точки API
• Поддержка контейнера внедрения зависимостей к ключу службы
• Взгляд за кулисами минимальных конечных точек API
• Организация api-интерфейсов ASP.NET Core
• Обсуждение проверки Fluent на сайте GitHub