Достаточно часто приходиться писать приложения, которые взаимодействуют с внешними (REST) API по протоколу HTTP. В среде .NET есть разные способы реализации этого, в этой статье я расскажу, как я предпочитаю это делать.

Раньше в .NET framework вызывать HTTP-запросы и обрабатывать ответы было несколько сложнее, чем сейчас. Популярным решением было использование библиотеки RestSharp, которая скрывала многие сложности.

В dotnet (Core) использование веб-интерфейсов стало намного проще, и необходимость в использовании сторонних библиотек отпала. Хоть это и здорово, но все же есть несколько проблем, о которых необходимо знать.

Особенности использования HttpClient

Сейчас, если вы создаете dotnet-приложение, взаимодействующее с API, вы, скорее всего, используете класс HttpClient для выполнения HTTP-запросов.

В силу его простоты им очень легко злоупотреблять. Часто встречающаяся ошибка заключается в том, что разработчики напрямую создают новый экземпляр HttpClient для запуска запроса. Это потенциально может привести к проблемам, которые на первый взгляд могут быть неочевидны и трудно отлаживаемы. К примеру, в один прекрасный момент у вас могут закончиться порты, и вы не сможете совершить Http запрос.

В этой статье мы будем использовать публичный API Star Wars в качестве примера для демонстрации различных способов работы с HttpClient. Начнем с исходного кода, в котором непосредственно в эндпоинте создаются экземпляры HttpClient.

var builder = WebApplication.CreateBuilder(args);
 
var app = builder.Build();
 
var starwarsGroup = app.MapGroup("starwars");
starwarsGroup.MapGet("people/{peopleId}", async (string peopleId) =>
{
    var httpClient = new HttpClient(); // Создали один HttpClient
    var people = await httpClient.GetFromJsonAsync<StarWarsPeople>($"https://swapi.dev/api/people/{peopleId}");
    return Results.Ok(people);
});
 
starwarsGroup.MapGet("species/{speciesId}", async (string speciesId) =>
{
    var httpClient = new HttpClient(); // Создали ещё один HttpClient
    var species = await httpClient.GetFromJsonAsync<StarWarsSpecies>($"https://swapi.dev/api/species/{speciesId}");
    return Results.Ok(species);
});
 
starwarsGroup.MapGet("planets/{planetId}", async (string planetId) =>
{
    var httpClient = new HttpClient(); // И ещё один HttpClient
    var planet = await httpClient.GetFromJsonAsync<StarWarsPlanet>($"https://swapi.dev/api/planets/{planetId}");
    return Results.Ok(planet);
});
 
app.Run();

Итак, мы узнали о возможных проблемах, которые кроются в таком подходе использования HttpClient, давайте посмотрим, как мы можем улучшить наш код.

Почему использование Singleton не панацея?

Первое решение, которое приходит в голову, - не создавать экземпляр HttpClient, а использовать один экземпляр (singleton) на все время работы приложения.

Это может показаться хорошим решением, но оно не лучшее, поскольку вам все равно придется самостоятельно управлять временем жизни клиента. В противном случае вы можете столкнуться с проблемами DNS, о которых говорится в документации по ссылке выше.

Singleton также не является оптимальным вариантом, если вашему приложению требуется несколько клиентов, например, для взаимодействия с различными API. В этом случае трудно настроить клиентов по-разному.

IHttpClientFactory

Более эффективным решением является использование фабрики IHttpClientFactory. IHttpClientFactory — это фабрика, которая создает и управляет экземплярами HttpClient. Таким образом, dotnet обрабатывает все детали за вас, и вы можете сосредоточиться на написании кода, не отвлекаясь на детали HttpClient. Но тут мы столкнёмся с выбором, какой из трёх вариантов создания HttpClient применить. Пройдемся по всем от хорошего к самому лучшему!

Рефракторим до IHttpClientFactory

Самый простой способ - использовать IHttpClientFactory непосредственно для создания HTTP-клиента, когда он нам нужен.

Для этого сначала зарегистрируем фабрику IHttpClientFactory в контейнере инъекции зависимостей с помощью метода AddHttpClient. Затем инжектируем фабрику туда, где нужен клиент, создаем клиента с помощью CreateClient и используем его для выполнения HTTP-запроса.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient(); //Регистрируем фабрику
 
var app = builder.Build();
 
var starwarsGroup = app.MapGroup("starwars");
starwarsGroup.MapGet("people/{peopleId}", async (string peopleId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient(); //Создаем клиента
    var people = await httpClient.GetFromJsonAsync<StarWarsPeople>($"https://swapi.dev/api/people/{peopleId}");
    return Results.Ok(people);
});
 
starwarsGroup.MapGet("species/{speciesId}",  async (string speciesId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient(); //Создаем клиента
    var species = await httpClient.GetFromJsonAsync<StarWarsSpecies>($"https://swapi.dev/api/species/{speciesId}");
    return Results.Ok(species);
});
 
starwarsGroup.MapGet("planets/{planetId}",  async (string planetId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient(); //Создаем клиента
    var planet = await httpClient.GetFromJsonAsync<StarWarsPlanet>($"https://swapi.dev/api/planets/{planetId}");
    return Results.Ok(planet);
});
 
app.Run();

Это решение работает, и мы избавились от нескольких проблем, которые у нас были , но оно не идеально.

Основная проблема решена - нам больше не нужно думать об управлении временем жизни HttpClient. Но, взглянув на код, можно что он требует доработок.

На первый взгляд, здесь сразу видно дублирование с (пере)объявлением домена API в разных запросах (https://swapi.dev/).

Второе, что мне не нравится, это то, что у нас нет возможности настроить клиента. Более того, если приложению необходимо взаимодействовать с несколькими HTTP API, мы все равно используем один и тот же HTTP-клиент.

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

Именованные HttpClient`ы

Более удачным решением является так называемый именованный HTTP-клиент. Данное решение отличается от предыдущего только тем, что мы передаём в метод AddHttpClient строку с именем клиента. Далее, чтобы создать клиента, передайте то же имя в метод CreateClient.

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

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient("starwars");
 
var app = builder.Build();
 
var starwarsGroup = app.MapGroup("starwars");
starwarsGroup.MapGet("people/{peopleId}", async (string peopleId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient("starwars");
    var people = await httpClient.GetFromJsonAsync<StarWarsPeople>($"https://swapi.dev/api/people/{peopleId}");
    return Results.Ok(people);
});
 
starwarsGroup.MapGet("species/{speciesId}",  async (string speciesId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient("starwars");
    var species = await httpClient.GetFromJsonAsync<StarWarsSpecies>($"https://swapi.dev/api/species/{speciesId}");
    return Results.Ok(species);
});
 
starwarsGroup.MapGet("planets/{planetId}",  async (string planetId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient("starwars");
    var planet = await httpClient.GetFromJsonAsync<StarWarsPlanet>($"https://swapi.dev/api/planets/{planetId}");
    return Results.Ok(planet);
});
 
app.Run();

Просто, не правда ли? :)

Настраиваем HttpClient

Чтобы сделать код еще лучше, мы можем сконфигурировать клиента в обратном вызове метода AddHttpClient, что даст нам доступ к экземпляру HttpClient. Преимущество заключается в том, что мы можем сконфигурировать клиента один раз и использовать его везде в нашем приложении.

Создание клиентов с помощью AddHttpClient также позволяет создавать несколько HTTP-клиентов с различной конфигурацией, каждый из которых предназначен для своих целей.

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

В результате мы можем удалить повторные указания домена внутри потребителей.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient("starwars", (client) => {
        // Задаём базовый адрес в одном месте
        client.BaseAddress = new Uri("https://swapi.dev/api/");
    });
 
var app = builder.Build();
 
var starwarsGroup = app.MapGroup("starwars");
starwarsGroup.MapGet("people/{peopleId}", async (string peopleId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient("starwars");
    var people = await httpClient.GetFromJsonAsync<StarWarsPeople>($"people/{peopleId}");
    return Results.Ok(people);
});
 
starwarsGroup.MapGet("species/{speciesId}", async (string speciesId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient("starwars");
    var species = await httpClient.GetFromJsonAsync<StarWarsSpecies>($"species/{speciesId}");
    return Results.Ok(species);
});
 
starwarsGroup.MapGet("planets/{planetId}", async (string planetId, IHttpClientFactory httpClientFactory) =>
{
    var httpClient = httpClientFactory.CreateClient("starwars");
    var planet = await httpClient.GetFromJsonAsync<StarWarsPlanet>($"planets/{planetId}");
    return Results.Ok(planet);
});
 
app.Run();

Мы можем не ограничиваться этим, можно добавить HttpMessageHandlers для настройки поведения HTTP-клиента с помощью DelegatingHandler.

Некоторые реализации таких обработчиков — это обработчики повторных запросов, добавляющие ограничитель скорости запросов (rate limiter), добавляющие слой кэширования или автоматический выключатель в HTTP-клиент. К счастью, нам не нужно писать все это вручную, а можно воспользоваться популярным пакетом Polly. Используя Polly, мы можем легко создавать отказоустойчивые HTTP-клиенты.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient("starwars", (client) => {
        client.BaseAddress = new Uri("https://swapi.dev/api/");
    })
    .AddHttpMessageHandler<MyCustomHttpMessageHandler>() // Используем дополнительный обработчик
    .AddPolicyHandler(GetRetryPolicy()); // используем Polly обработчик

Мы также можем использовать DelegatingHandler для добавления данных к исходящим запросам, например, для добавления заголовков. Более подробную информацию об этом, включая практический пример включения заголовков аутентификации, можно найти в статье Джимми Богард (Securing Web APIs with Azure AD: Connecting External Clients).

Распределение заголовков.

Вместо того чтобы вручную добавлять заголовки в исходящие HTTP-запросы, мы можем автоматически передавать заголовки с помощью пакета Microsoft.AspNetCore.HeaderPropagation.

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

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient("starwars", (client) => {
        client.BaseAddress = new Uri("https://swapi.dev/api/");
    })
    .AddHeaderPropagation();

Более подробно можно ознакомиться в документации.

Типизированные HttpClient`ы

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

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

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

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

Чтобы использовать типизированный клиент, сначала оберните HTTP-клиент в класс. В конструкторе класс получает экземпляр HttpClient, который внедряется из DI-контейнера. Внутри конструктора мы можем сконфигурировать клиента.

В приведенном ниже примере StarWarsHttpClient выступает в качестве обертки для API "Звездных войн".

public class StarWarsHttpClient : IStarWarsService
{
    private readonly HttpClient _httpClient;
 
    public StarWarsHttpClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
        _httpClient.BaseAddress = new Uri("https://swapi.dev/api/");
    }
 
    public async ValueTask<StarWarsPeople> GetPeople(string peopleId)
    {
        return await _httpClient.GetFromJsonAsync<StarWarsPeople>($"people/{peopleId}");
    }
 
    public async ValueTask<StarWarsPlanet> GetPlanet(string planetId)
    {
        return await _httpClient.GetFromJsonAsync<StarWarsPlanet>($"planets/{planetId}");
    }
 
    public async ValueTask<StarWarsSpecies> GetSpecies(string speciesId)
    {
        return await _httpClient.GetFromJsonAsync<StarWarsSpecies>($"species/{speciesId}");
    }
}
 
public interface IStarWarsService
{
    ValueTask<StarWarsPeople> GetPeople(string peopleId);
    ValueTask<StarWarsPlanet> GetPlanet(string planetId);
    ValueTask<StarWarsSpecies> GetSpecies(string speciesId);
}

Затем обновите метод AddHttpClient для использования типизированного клиента. Наконец, внедрите клиента в потребителя вместо использования IHttpClientFactory. Потребителю больше не нужно знать о конечных точках, и он может просто использовать методы типизированного клиента.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient<IStarWarsService, StarWarsHttpClient>();
 
var app = builder.Build();
 
var starwarsGroup = app.MapGroup("starwars");
starwarsGroup.MapGet("people/{peopleId}", async (string peopleId, IStarWarsService starwarsService) =>
{
    var people = await starwarsService.GetPeople(peopleId);
    return Results.Ok(people);
});
 
starwarsGroup.MapGet("species/{speciesId}", async (string speciesId, IStarWarsService starwarsService) =>
{
    var species = await starwarsService.GetSpecies(speciesId);
    return Results.Ok(species);
});
 
starwarsGroup.MapGet("planets/{planetId}", async (string planetId, IStarWarsService starwarsService) =>
{
    var planet = await starwarsService.GetPlanet(planetId);
    return Results.Ok(planet);
});
 
app.Run();

Заключение.

Мы рассмотрели несколько примеров, давайте сравним исходное решение с окончательно переработанным.

var builder = WebApplication.CreateBuilder(args);
 
var app = builder.Build();
 
var starwarsGroup = app.MapGroup("starwars");
starwarsGroup.MapGet("people/{peopleId}", async (string peopleId) =>
{
    var httpClient = new HttpClient();
    var people = await httpClient.GetFromJsonAsync<StarWarsPeople>($"https://swapi.dev/api/people/{peopleId}");
    return Results.Ok(people);
});
 
starwarsGroup.MapGet("species/{speciesId}", async (string speciesId) =>
{
    var httpClient = new HttpClient();
    var species = await httpClient.GetFromJsonAsync<StarWarsSpecies>($"https://swapi.dev/api/species/{speciesId}");
    return Results.Ok(species);
});
 
starwarsGroup.MapGet("planets/{planetId}", async (string planetId) =>
{
    var httpClient = new HttpClient();
    var planet = await httpClient.GetFromJsonAsync<StarWarsPlanet>($"https://swapi.dev/api/planets/{planetId}");
    return Results.Ok(planet);
});
 
app.Run();

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient<IStarWarsService, StarWarsHttpClient>()
    .AddHttpMessageHandler<MyCustomHttpMessageHandler>() 
    .AddPolicyHandler(GetRetryPolicy());
 
var app = builder.Build();
 
var starwarsGroup = app.MapGroup("starwars");
starwarsGroup.MapGet("people/{peopleId}", async (string peopleId, IStarWarsService starwarsService) =>
{
    var people = await starwarsService.GetPeople(peopleId);
    return Results.Ok(people);
});
 
starwarsGroup.MapGet("species/{speciesId}", async (string speciesId, IStarWarsService starwarsService) =>
{
    var species = await starwarsService.GetSpecies(speciesId);
    return Results.Ok(species);
});
 
starwarsGroup.MapGet("planets/{planetId}", async (string planetId, IStarWarsService starwarsService) =>
{
    var planet = await starwarsService.GetPlanet(planetId);
    return Results.Ok(planet);
});
 
app.Run();

Сравнивая эти два решения, мы видим, что окончательное решение гораздо более читабельно и удобно для сопровождения.

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

Наконец, поведение клиента можно настраивать, добавляя собственные обработчики или используя сторонние инструменты, такие как Polly.

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

Что еще почитать по теме?

• Use IHttpClientFactory to implement resilient HTTP requests
• Make HTTP requests using IHttpClientFactory in ASP.NET Core

Ключевое слово record в C# существует со времен C# 9, и вы либо любите его, либо ненавидите. Независимо от вашего мнения, при работе с ключевым словом with вы, скорее всего, допустите не совсем очевидную ошибку. Эта ошибка может привести к странному поведению системы и трудно диагностируемым ошибкам. А ошибки никому не нужны, верно?!

В этой статье мы рассмотрим проблему и способы ее решения.

Описание проблемы with с records

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

var one = new Simple(1);
var copy = one with { Number = one.Number + 1 };

Console.WriteLine(copy);

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

Simple { Number = 2 }

Попытка изменить Number напрямую приводит к возникновению исключения компиляции с сообщением.

Init-only property 'Simple.Number' can only be assigned in an object initializer, or on 'this' or 'base' in an instance constructor or an 'init' accessor

Теперь начинается настоящее веселье. Мы рассматривали типы значений, которые копировались во время выполнения. А как насчет ссылочных типов? Давайте добавим коллекцию в запись.

var item = new Item();

var newItem = item with { };
item.State.Add(1);
newItem.State.Add(2);

Console.WriteLine(item);
Console.WriteLine(newItem);

public record Item(List<int> State)
{
    public Item() : this(new List<int>())
    {
    }

    public override string ToString()
    {
        return $"Item {{ State = {string.Join(", ", State)} }}";
    }
}

Что вы ожидаете от State (не подглядывайте)? Вы были бы правы, если бы предположили, что в обоих случаях это будет 1, 2.

Item { State = 1, 2 }
Item { State = 1, 2 }

Как вы, наверное, знаете, ссылочные типы указывают на место в памяти. При использовании ключевого слова with для record со ссылочными типами среда выполнения будет копировать ссылку в новый экземпляр record. Такое поведение отлично сказывается на эффективности использования памяти, поскольку среда выполнения не выделяет дополнительную память под информацию, доступную только для чтения. Такое поведение не очень хорошо, если вы изменяете данные перед передачей их другим потребителям.

Как же решить эту проблему? Есть два пути.

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

Первый подход заключается в том, чтобы знать обо всех ссылочных типах в записи и изменять их значения на ранних этапах создания.

var item = new Item();

var newItem = item with { State = item.State.Append(2).ToList() };
item.State.Add(1);

Console.WriteLine(item);
Console.WriteLine(newItem);

В результате мы получили две разные коллекции.

Item { State = 1 }
Item { State = 2 }

Такой подход допустим, но требует усилий при использовании ключевого слова with.

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

var item = new Item();

var newItem = item with { };
item.State.Add(1);
newItem.State.Add(2);
Console.WriteLine(item);
Console.WriteLine(newItem);

public record Item(List<int> State)
{
    public Item() : this(new List<int>())
    {
    }

    // конструктор копирования
    protected Item(Item oldItem)
    {
        State = new List<int>(oldItem.State);
    }

    public override string ToString()
    {
        return $"Item {{ State = {string.Join(", ", State)} }}";
    }
}

При выполнении предыдущего кода результат показывает две отдельные коллекции для двух экземпляров записей.

Item { State = 1 }
Item { State = 2 }

У вас есть два приемлемых подхода для работы со ссылочными типами в record.

Другой вариант, который следует рассмотреть, — это использование неизменяемых ссылочных типов с самого начала. В данном примере можно использовать IReadOnlyList вместо List прямо в конструкторе записи.

Вывод

Хотя тип record имеет синтаксическое значение в C#, под капотом он представляет собой просто специализированную реализацию класса. Концепции типов значений и ссылочных типов по-прежнему применимы. Помнить о том, какие значения вы добавляете в свои реализации, очень важно, поскольку неправильное копирование записей может привести к странным ошибкам. Я рекомендую большинству пользователей, использующих record типы, как можно раньше реализовать конструктор копирования, чтобы не забывать о том, что процесс копирования должен быть преднамеренным.

Я надеюсь, что эта статья была вам полезна, и благодарю вас за то, что вы поделились ею с друзьями и коллегами. Будьте здоровы :)

Оригинал статьи вы можете прочитать по ссылке.

На ASP.NET Core сильно повлиял старый .NET Framework System.Web, основанный на ASP.NET Framework, но Net Core принципиально быстрее и современнее. Тем не менее, одна функция попала в ASP.NET Core практически без изменений: валидация на стороне клиента.

В этой статье я рассматриваю альтернативу стандартной (поддерживаемой) клиентской валидации на основе jQuery. В этом альтернативном подходе мы полагаемся на небольшую библиотеку JavaScript под названием aspnet-client-validation.

Валидация на стороне клиента в ASP.NET Core.

Net меняется из года в год, но есть в нём и неизменные вещи, одна из которых — это способ выполнения валидации на стороне клиента в ASP.NET Core. Рекомендуемый/поддерживаемый подход основан на jQuery. В этой главе я покажу, как он работает. Если вы хорошо знаете этот подход, то можете пропустить главу!

Чтобы у нас был конкретный пример для работы, я создам очень простую страницу Razor Page, всё так же будет работать и в "традиционном" MVC. Следующая PageModel содержит простую модель Person, которую мы привяжем к форме.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using System.ComponentModel.DataAnnotations;

namespace MvcClientValidation.Pages;

public class TestModel : PageModel
{
    [BindProperty]
    public Person Input { get; set; }

    public ActionResult OnPost()
    {
        if (!ModelState.IsValid)
        {
            return Page();
        }

        TempData["Message"] = $"Hello {Input.Name} ({Input.Email})!";
        return RedirectToPage("Index");
    }

    public class Person
    {
        [Required]
        public string Name { get; set; }

        [Required]
        [EmailAddress]
        public string Email { get; set; }
    }
}

После отправки обработчик OnPost() проверяет, успешно ли прошла валидация модели Person. Если да, то в данном примере мы устанавливаем некоторые TempData с сообщением и перенаправляем на другую страницу (используя паттерн Post-Redirect-Get).

Если модель не была валидной, мы повторно отображаем форму (которая показывает сообщения об ошибках валидации).

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

@page
@model MvcClientValidation.Pages.TestModel

<div class="col-md-6 offset-md-3">
  <form method="post">
    <div class="form-floating mb-3">
      <input class="form-control" asp-for="Input.Name">
      <label asp-for="Input.Name"></label>
      <span class="text-danger field-validation-valid" asp-validation-for="Input.Name"></span>
    </div>
    <div class="form-floating mb-3">
      <input class="form-control" asp-for="Input.Email">
      <label asp-for="Input.Email"></label>
      <span class="text-danger field-validation-valid" asp-validation-for="Input.Email"></span>
    </div>
    <button type="submit" class="w-100 btn btn-lg btn-primary">Отправить</button>
  </form>
</div>

Одна вещь, которую следует отметить в приведенной выше странице, заключается в том, что в настоящее время она не использует валидацию на стороне клиента. После заполнения полей клиент нажимает кнопку "Отправить", и только после проверки формы на сервере и отправки ответа получает сообщение о том, что что-то пошло не так.

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

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

Все шаблоны Razor Pages по умолчанию включают общий частичный файл _ValidationScriptsPartial.cshtml. Эта часть содержит два тега script:

<script src="~/lib/jquery/dist/jquery.min.js"></script>
<script src="~/lib/jquery-validation/dist/jquery.validate.min.js"></script>
<script src="~/lib/jquery-validation-unobtrusive/jquery.validate.unobtrusive.min.js"></script>

Они работают в сочетании со скриптом jQuery (обычно добавляемым на все страницы в _Layout.cshtml, я добавил тег в примере выше для демонстрации) для добавления client-side валидации. Вы так же можете добавить тег в секцию "Scripts", разместив следующее в нижней части вашей страницы Razor:

@section Scripts{
    <partial name="_ValidationScriptsPartial" />
}

Теперь у вас есть валидация на стороне клиента! Если пользователь не сможет правильно заполнить форму, он получит мгновенное предупреждение. Если пользователь все равно нажмет кнопку "Отправить", форма не будет отправлена на сервер, пока он не исправит ошибки.

Под капотом это работает потому, что ASP.NET Core передает целый ряд метаданных элементам формы, которые он генерирует. Например, форма, показанная выше, выглядит следующим образом:

<div class="col-md-6 offset-md-3">
  <form method="post">
    <div class="form-floating mb-3">
      <input class="form-control" type="text" data-val="true" 
        data-val-required="The Name field is required." id="Input_Name" 
        name="Input.Name" value="">
      <label for="Input_Name">Name</label>
      <span class="text-danger field-validation-valid field-validation-valid"
        data-valmsg-for="Input.Name" data-valmsg-replace="true"></span>
    </div>
    <div class="form-floating mb-3">
      <input class="form-control" type="email" data-val="true" 
        data-val-email="The Email field is not a valid e-mail address." 
        data-val-required="The Email field is required." id="Input_Email" 
        name="Input.Email" value="">
      <label for="Input_Email">Email</label>
      <span class="text-danger field-validation-valid field-validation-valid" 
        data-valmsg-for="Input.Email" data-valmsg-replace="true"></span>
    </div>
    <button type="submit" class="w-100 btn btn-lg btn-primary">Submit</button>
    <input name="__RequestVerificationToken" type="hidden" value="CfDJ8FJx1R5_kANFmBjoULQ...">
  </form>
</div>

В HTML коде выше вы можете увидеть все атрибуты data-*, добавленные ASP.NET Core. Библиотека jQuery для валидации ищет HTML-элементы с этими атрибутами и прикрепляет обработчики событий. Эти обработчики проверяют вводимые значения и используют данные атрибутов для создания соответствующих предупреждений и сообщений. Таким образом, на стороне клиента вы получаете ту же валидацию, что и на стороне сервера.

Все это работает со встроенными атрибутами [DataAnnotations]. Если вы используете FluentValidation или другой фреймворк валидации, то вам могут понадобиться дополнительные действия для включения валидации на стороне клиента. Например, для FluentValidation необходимо установить FluentValidation.AspNetCore.

Итак, если все это работает, в чем проблема? Имеет ли значение то, что в этом решении используется jQuery?

Что не так с jQuery?

В ASP.NET Core по умолчанию для валидации на стороне клиента используется скрипт от Microsoft под названием jQuery Unobtrusive Validation, который, в свою очередь, использует плагин валидации jQuery. Все это (очевидно) требует jQuery.

Если сложить все это, то получится более 100 КБ (после GZIP сжатия) JavaScript. Это... довольно много. Он не обязательно загружается в браузер каждый раз благодаря кэшированию, но, тем не менее, это весь JavaScript, который браузеру нужно разобрать и запустить для каждой отдельной страницы.

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

Итак, если jQuery не так необходим в наши дни и занимает много трафика, разве не было бы здорово, если бы вы могли его удалить?

Вы справедливо можете возразить: "Разве Bootstrap не требует jQuery?". Ну, это зависит от обстоятельств. Текущие шаблоны ASP.NET Core используют Bootstrap 5, который явно разработан для того, чтобы не использовать jQuery. Если вы все еще используете Bootstrap 4, то jQuery вам понадобится в любом случае, но если вы используете Bootstrap 5 или Tailwind (например), то jQuery — это просто ненужные лишние байты.

Но, тем не менее, стандартная клиентская валидация ASP.NET Core требует jQuery. Так что мы с ним застряли, верно?

Но какова же альтернатива?

Как ни странно, стандартные способы для выполнения клиентской валидации в браузерах существуют уже много лет. В HTML 5 появился "Constraints Validation API". Он добавляет проверку элементов формы на основе типа элемента, а также других стандартных свойств. Например, вы могли видеть следующее стандартное всплывающее окно "Недействительный email" при повседневном просмотре веб-страниц:

Это сообщение о проверке было сгенерировано API Constraints Validation. В данном случае оно было вызвано тем, что элемент ввода имеет атрибут type="email".

Если вам интересно, почему в приложениях Razor Pages, использующих jQuery, не видно скрытой валидации, то это потому, что этот плагин добавляет атрибут novalidate к тегу.

В отличие от некоторых API браузеров, API проверки ограничений имеет отличную поддержку. За исключением Opera Mini, ограничения поддерживаются практически во всех браузерах. Даже IE 10 имеет (частичную) поддержку! 😮 Если отбросить IE и Opera Mini, то если вы используете браузер, который обновлялся в течение последних 5 лет, то все будет в порядке:

Итак, если браузер уже имеет встроенную поддержку валидации, можем ли мы использовать ее в ASP.NET Core и избавиться от jQuery?

К сожалению, ответ: не так просто. Проверка ограничений зависит от наличия определенных атрибутов, а не атрибутов data-*, которые ASP.NET Core добавляет по умолчанию. Также, как правило, невозможно стилизовать ошибки, выдаваемые браузером. Поэтому использование Constraints API, к сожалению, не является простым вариантом.

Но не все потеряно. Что если бы мы могли обойтись без API Constraints, а вместо этого просто заменить код незаметной валидации jQuery.

Совершенно другой подход к клиентской валидации использует AJAX для выполнения всех правил на стороне сервера, используя библиотеку, такую как FormHelper. Это позволяет избежать необходимости написания пользовательских правил на JavaScript и в некоторых случаях может обеспечить более последовательный опыт для пользователей.

Представляем aspnet-client-validation.

Эта статья была написана под впечатлением от твита легендарного Фила Хаака:

If you use aspnetcore or aspnetmvc without jquery, you should check out https://t.co/EMB8LZZWgg for client validation.

Библиотека aspnet-client-validation, на которую он указывает, представляет собой крошечную (4 кБ GZIP) библиотеку, которая по сути является простой реализацией скрипта unobtrusive validation от jQuery, упрощенной и без каких-либо зависимостей.

Обратите внимание, что aspnet-client-validation не поддерживает IE.

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

• ~/lib/jquery/dist/jquery.min.js (в _Layout.cshtml)
• ~/lib/jquery-validation/dist/jquery.validate.min.js (в _ValidationScriptsPartial.cshtml)
• ~/lib/jquery-validation-unobtrusive/jquery.validate.unobtrusive.min.js (в _ValidationScriptsPartial.cshtml)

Помните, что jQuery необходим, если вы используете Bootstrap 4 (или более раннюю версию), но если вы используете Bootstrap 5 (как в стандартных шаблонах .NET 7 ASP.NET Core), то jQuery совершенно необязателен и требуется только для добавления клиентской валидации.

После удаления этих файлов вы можете добавить ссылку на aspnet-validation.min.js в файл _ValidationScriptsPartial.cshtml. Приведенный ниже пример также включает необходимый вызов метода bootstrap().

<script src="https://www.unpkg.com/aspnet-client-validation/dist/aspnet-validation.min.js" crossorigin="anonymous" integrity="sha384-4E0R5+D480pDlcgfpDw2NZDUAX0YsK6J4Zk6o4raasSXMaAlatx9tyNxkFBESu6C"></script>
<script>
    const v  = new aspnetValidation.ValidationService()
    v.bootstrap()
</script>

Приведенный выше пример ссылается на файл JavaScript непосредственно из CDN, но вы можете сослаться на файл локально в теге <script> или включить его в свои пакеты с помощью ES Modules или Common JS, в зависимости от того, какой подход вы предпочитаете.

В приведенном примере загружается скрипт aspnet-client-validation, а затем запускается код bootstrap. ValidationService.bootstrap() загружает провайдеры проверки по умолчанию и устанавливает DOM-слушатель, который сканирует HTML-источник в поисках атрибутов проверки.

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

Таким образом, простым изменением _ValidationScriptsPartial.cshtml вы можете отказаться от jQuery и значительно уменьшить размер полезной нагрузки вашего приложения. В следующем разделе мы расширим библиотеку aspnet-client-validation, чтобы показать, что она так же гибка, как и jQuery-эквивалент.

Создание пользовательского провайдера валидации с помощью aspnet-client-validation.

ASP.NET Core поставляется с поддержкой встроенных по умолчанию атрибутов валидации в библиотеке .NET DataAnnotations, которая обеспечивает поддержку таких вещей, как Email, обязательные поля, минимальная длина, диапазоны и Regex. Эти атрибуты охватывают множество распространенных случаев, но часто возникает необходимость в написании дополнительных пользовательских правил валидации. Существует несколько способов сделать это, один из них - создать собственный атрибут валидации.

Создание собственного атрибута ValidationAttribute

Чтобы рассмотреть конкретный пример, представим, что вы хотите ограничить список разрешенных электронных адресов только теми, которые заканчиваются на @mycompany.com. Встроенного атрибута проверки "endswith" не существует, однако мы можем его сделать. Упрощенная реализация может выглядеть следующим образом:

public class EndsWithValidationAttribute : ValidationAttribute
{
    private readonly string _endsWith;
    public EndsWithValidationAttribute(string endsWith)
    {
        _endsWith = endsWith;
    }

    public override string FormatErrorMessage(string name)
        => $"The field {name} must end with '{_endsWith}'";

    public override bool IsValid(object? value)
    {
        if(value is null)
        {
            return true; // Допускает нулевые значения, поэтому работает с атрибутом Required
        }

        return value is string s&& s.EndsWith(_endsWith);
    }
}

И будет добавлен в модель как

public class Person
{
    [Required]
    public string Name { get; set; }

    [Required]
    [EmailAddress]
    [EndsWithValidation("@mycompany.com")] // 👈 Добавить
    public string Email { get; set; }
}

Когда вы отправляете форму, проверка выполняется на сервере и отмечает неправильные адреса электронной почты:

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

1. Передавать атрибуты data-*, к которым может подключаться библиотека на стороне клиента.
2. Добавить пользовательский провайдер в библиотеку на стороне клиента.

Шаг 1. одинаков независимо от того, используете ли вы стандартную jQuery unobtrusive validation или библиотеку aspnet-client-validation. Есть несколько способов сделать это, но для целей этой статьи я буду реализовывать IClientModelValidator на атрибуте валидации.

Добавление данных-атрибутов с помощью IClientModelValidator

Реализация IClientModelValidator требует реализации единственного метода AddValidation(), который отвечает за добавление необходимых атрибутов data-*. Для нашего атрибута валидации нам нужно добавить три атрибута:

• data-val="true". Библиотеки на стороне клиента используют этот атрибут, чтобы понять, что поле имеет требования к валидации.
• data-val-endswith. Этот атрибут содержит сообщение об ошибке, которое должно отображаться при неудачной проверке.
• data-val-endswith-value. Этот атрибут содержит строку, которую должна искать библиотека на стороне клиента.

Часть -endswith уникальна для нашей конкретной реализации валидатора, но, по идее, она может быть любой. Это просто должно быть известное значение, к которому может подключиться библиотека на стороне клиента. Вы можете создать пользовательскую библиотеку для библиотеки jQuery unobtrusive validation, как описано в документации. Мы создадим аналогичный хук для библиотеки aspnet-client-validation.

public class EndsWithValidationAttribute : ValidationAttribute, IClientModelValidator
{
    private readonly string _endsWith;
    public EndsWithValidationAttribute(string endsWith)
    {
        _endsWith = endsWith;
    }

    // 👇 Добавьте этот метод для добавления атрибутов
    public void AddValidation(ClientModelValidationContext context)
    {
        var errorMessage = FormatErrorMessage(context.ModelMetadata.DisplayName ?? context.ModelMetadata.Name);
        context.Attributes.TryAdd("data-val", "true");
        context.Attributes.TryAdd("data-val-endswith", errorMessage);
        context.Attributes.TryAdd("data-val-endswith-value", _endsWith);
    }

    public override string FormatErrorMessage(string name)
        => $"The field {name} must end with '{_endsWith}'";

    public override bool IsValid(object? value)
    {
        if(value is null)
        {
            return true;
        }

        return value is string s&& s.EndsWith(_endsWith);
    }
}

Вы можете увидеть результат вызова AddValidation в сгенерированном HTML, содержащем два дополнительных атрибута data-val-endswith*:

<input class="form-control input-validation-error" type="email" 
    id="Input_Email" name="Input.Email" value="test@Test.com"
    data-val="true" data-val-required="The Email field is required." 
    data-val-email="The Email field is not a valid e-mail address." 
    data-val-endswith="The field Email must end with '@mycompany.com'" 
    data-val-endswith-value="@mycompany.com">

Теперь у нас есть атрибуты, нам нужно подключить провайдер aspnet-client-validation для их использования.

Создание собственного провайдера для aspnet-client-validation.

В aspnet-client-validation можно обрабатывать пользовательские требования к валидации, создав новый провайдер. Чтобы добавить нового провайдера, вызовите ValidationService.addProvider(), передав имя провайдера (в нашем случае endswith) и передав функцию обратного вызова, которая выполняет проверку. Этот обратный вызов имеет три параметра:

• value: значение элемента ввода
• elemet: проверяемый элемент DOM
• params: дополнительные значения, передаваемые через дополнительные атрибуты data-*. Таким образом, вы можете получить доступ к data-val-endswith-value, вызвав params.value. В качестве альтернативы вы можете получить доступ к data-val-endswith-somethingelse, вызвав params.somethingelse.

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

<script src="https://www.unpkg.com/aspnet-client-validation/dist/aspnet-validation.min.js"></script>
<script>
  const v  = new aspnetValidation.ValidationService()
  // 👇 Вызвать addProvider() _перед_ вызовом bootstrap()
  v.addProvider('endswith', (value, element, params) => {
    if (!value) {
        // Пусть [Required] обрабатывает ошибку валидации для пустого ввода...
        return true;
    }

    return value.endsWith(params.value);
  });
  v.bootstrap();
</script>

И вот, у нас есть пользовательская валидация на стороне клиента без jQuery!🎉

Будущее валидации в ASP.NET Core.

Я не использовал aspnet-client-validation в реальном проекте, но исходя из того, что я видел, я не вижу причин придерживаться jQuery unobtrusive validation scripts. Подход aspnet-client-validation, кажется, заполняет ту же самую дыру, но с меньшей сложностью и с гораздо меньшим размером загрузки.

У меня возник вопрос: почему это не используется по умолчанию? Если убрать зависимость от jQuery, то не будет веских причин держать его в шаблонах по умолчанию. Кажется, что aspnet-client-validation был бы более простой и легкой рекомендацией для пользователей.

Хорошая новость заключается в том, что в репозитории ASP.NET Core есть выпуск, посвященный именно этому. Плохая новость в том, что он был создан 4 года назад и, похоже, застрял в неопределенности 😢.

Так в чем же дело? Почему ничего не происходит?

В комментарии от 2021 года вы можете найти то, что, по-видимому, является корнем проблемы:

Первоначальная мысль была в том, что мы можем сделать что-то тактическое, опираясь либо на возможности браузера, такие как валидация ограничений, либо на ручное создание имитации jQuery.validation. Но при дальнейшем рассмотрении мы поняли, что альтернатива, которая просто убирает jquery, не достаточно эффективна для нас.

В комментарии есть еще много деталей, но суть проблемы заключается в том, что они просто не хотят поставлять новую библиотеку JavaScript. То, что начиналось как простой запрос "удалить jQuery", переросло в более грандиозный "переделать работу валидации в MVC" и впоследствии заглохло.

Помните, в настоящее время де-факто, "благословенный" способ сделать валидацию на стороне клиента — это полагаться на jQuery. В 2023 году. ASP.NET Core — это быстрый, современный веб-фреймворк. Ожидаете ли вы, что он будет требовать jQuery? 😳 Неловко, правда?

Конечно, я понимаю. Blazor сейчас в центре внимания команды, и у него нет тех же проблем. Но MVC/Razor Pages все еще очень поддерживаемые способы создания приложений.

Так что мы можем, наконец, просто заменить jQuery на aspnet-client-validation и покончить с этим😅.

Подводя итог.

В этой статье я описал, как в настоящее время работает клиентская валидация в ASP.NET Core, используя jQuery и плагин unobtrusive validation. Затем я описал альтернативную библиотеку Фила Хаака, которая выполняет ту же функцию, под названием aspnet-client-validation. Эта библиотека занимает всего 4 кБ в GZipped и не имеет зависимостей.

После демонстрации использования библиотеки я показал ее совместимость с существующей библиотекой unobtrusive validation, создав пользовательский атрибут валидации, и показал, как его можно подключить к библиотеке aspnet-client-validation. Наконец, я описал свой взгляд на будущее клиентской валидации в ASP.NET Core.

С оригиналом статьи вы можете ознакомиться по ссылке.

В этой серии статей мы рассмотрели генерацию кода для простых эндпоинтов минимального API. В рамках этого процесса я игнорировал функцию "filters", добавленную в .NET 7, поскольку она добавляет определенную сложность. Что ж, в этой статье мы столкнемся с этой сложностью лицом к лицу и посмотрим, как добавление фильтра изменяет конечный сгенерированный RequestDelegate.

RequestDelegate для минимального API без фильтров.

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

app.MapGet("/{name}", (string name) => $"Hello {name}!");

Если вы следили за этой серией статей, вы сможете понять, что сгенерированный делегат выглядит примерно так:

Task (HttpContext httpContext) => TargetableRequestDelegate(Program.<>c, httpContext);

где TargetableRequestDelegate выглядит примерно так:

Task TargetableRequestDelegate(object? target, HttpContext httpContext)
{
    string name_local;
    bool wasParamCheckFailure;

    name_local = httpContext.Request.RouteValues["name"]
    if (name_local == null)
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "string", "name", "route");
    }

    if(wasParamCheckFailure)
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    return ExecuteWriteStringResponseAsync(
        httpContext,
        handler(name_local));
}

Я не показал здесь метод ExecuteWriteStringResponseAsync(), но, по существу, он выглядит следующим образом, как было показано в предыдущей статье:

Task ExecuteWriteStringResponseAsync(HttpContext httpContext, string text)
{
    httpContext.Response.ContentType ??= "text/plain; charset=utf-8";
    return httpContext.Response.WriteAsync(text);
}

Итак, это наша начальная точка. Теперь добавим простой фильтр к эндпоинту и посмотрим, как все изменится.

Минимальный API с фильтрами и фабриками фильтров.

В данной статье мы создадим очень простой фильтр, который выполняет некоторую "проверку" аргумента и возвращает 400 Bad Request в случае неудачи, а в противном случае вызывает обработчик:

app.MapGet("/{name}", (string name) => $"Hello {name}!")
    .AddEndpointFilter(async (context, next) =>
    {
        var name = context.GetArgument<string>(0);
        if (name is not "Sock")
        {
            return Results.ValidationProblem(
                new Dictionary<string, string[]>
                {
                    {"name", new[]{"Invalid name"}}
                });
        }
        
        return await next(context); 
    });

Обратите внимание, что это очень "endpoint-specific" фильтр, поскольку он делает значительные предположения о методе обработчика. Этот фильтр также может быть написан с использованием шаблона "фабрика фильтров":

Тип EndpointFilterDelegate определяется следующим образом:

public delegate ValueTask<object?> EndpointFilterDelegate(EndpointFilterInvocationContext context);

так что это фактически Func<EndpointFilterInvocationContext, ValueTask<object?>> .

Как следует из названий "filter" и "filter factory":

• Когда вы добавляете фильтр, вы добавляете код, который выполняется как часть RequestDelegate. Значение, которое вы возвращаете из фильтра, сериализуется в ответ.
• Когда вы добавляете фабрику фильтров, вы добавляете код, который выполняется во время создания RequestDelegate. Значение, возвращаемое из фабрики фильтров, является кодом, который выполняется в конвейере. Вы также можете вернуть "next" параметр, чтобы не добавлять дополнительный фильтр в конвейер.

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

На самом деле, метод AddEndpointFilter() делегирует непосредственно AddEndpointFilterFactory():

public static TBuilder AddEndpointFilter<TBuilder>(
    this TBuilder builder,
    Func<EndpointFilterInvocationContext, EndpointFilterDelegate, ValueTask<object?>> routeHandlerFilter)
    where TBuilder : IEndpointConventionBuilder
{
    return builder.AddEndpointFilterFactory(
        (routeHandlerContext, next) => 
            (context) => routeHandlerFilter(context, next));
}

Вложенные лямбды здесь довольно запутаны, но в конечном итоге вы получаете фабрику фильтров, как показано в примере выше. Итак, давайте посмотрим, как это изменит RequestDelegate.

RequestDelegate для минимального API с фильтром.

После добавления фильтра в RequestDelegate все становится намного сложнее. Приведенный ниже код показывает, как сгенерированный TargetableRequestDelegate() изменяется с фильтром. Есть три основных отличия:

• RequestDelegate создает общий экземпляр EndpointFilterInvocationContext, который содержит ссылку на HttpContext и исходные аргументы, привязанные к модели.
• Вместо прямого вызова лямбды обработчика вызывается EndpointFilterDelegate filterPipeline. Он содержит вложенный "конвейер фильтрации", который завершается обработчиком эндпоинта.
• Код записи ответа" должен обрабатывать тип ValueTask<object?> вместо ответа обработчика эндпоинта (который в нашем примере является строкой).

Если собрать все это вместе, получится TargetableRequestDelegate(), который будет выглядеть следующим образом. В приведенном ниже коде я выделил отличия от оригинального RequestDelegate :

Task TargetableRequestDelegate(object? target, HttpContext httpContext)
{
    string name_local;
    bool wasParamCheckFailure;

    name_local = httpContext.Request.RouteValues["name"]
    if (name_local == null)
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "string", "name", "route");
    }

    if(wasParamCheckFailure)
    {
        httpContext.Response.StatusCode = 400;
    }

    // 👇 Создаем общий EndpointFilterInvocationContext<> и используем его
    // для вызова конвейера фильтрации
    var filterContext = new EndpointFilterInvocationContext<string>(httpContext, name_local)
    ValueTask<object?> result = filterPipeline.Invoke(filterContext); 

   // 👇 Обрабатываем результат конвейера фильтрации, который всегда является
    // ValueTask<object?>, но который может быть обернут во множество различных 
// типов в зависимости от конкретного пути ошибки
    return ExecuteValueTaskOfObject(result, httpContext);

    // 👇 "Полный" конвейер фильтрации. Поскольку у нас только один
    // фильтр в нашем примере, здесь только один уровень "вложенности".
    ValueTask<object?> filterPipeline(EndpointFilterInvocationContext context)
    {
        // 👇 Наш фильтр
        var name = ctx.GetArgument<string>(0);
        if (name is not "Sock")
        {
            return Results.ValidationProblem(
                new Dictionary<string, string[]>
                {
                    { "name", new[] { "Invalid name" } }
                });
        }

        // 👇Вызов "внутреннего" обработчика
        return await filteredInvocation(ctx);
    }

    // 👇 Внутренний фильтр в конвейере, который вызывает метод обработчика
    ValueTask<object?> filteredInvocation(EndpointFilterInvocationContext context)
    {
        if(context.HttpContext.Response.StatusCode >= 400)
        {
            // Already errored, don't run the handler method
            return ValueTask.CompletedTask;  
        }
        else
        {
            // Create the "instance" of the target (if any)
            var target = targetFactory(context.HttpContext); 
            // Execute the handler using the arguments from the filter context
            // and wrap the result in in a ValueTask
            return ValueTask.FromResult<object?>( 
                target.handler.Invoke(context.GetArgument<string>(0)) // the actual handler execution
            );
        }
    }
}

Как и было обещано, здесь происходит довольно много событий. В оставшейся части статьи мы рассмотрим, как меняется построение RequestDelegate, когда эндпоинт имеет фильтры.

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

Изменения в CreateArguments().

Первые изменения в генерации RequestDelegate происходят в функции CreateArguments(). После генерации выражения для привязки аргументов к модели, как обсуждалось в предыдущих постах, генерируется дополнительное выражение для каждого аргумента обработчика. Это выражение служит для получения каждого аргумента из EndpointFilterInvocationContext, как показано ниже:

context.GetArgument<string>(0);

Когда динамический код не поддерживается, сгенерированное выражение извлекает объект из IList<object?> (что является операцией boxing для типов значений), используя context. Arguments[0].

Этот дополнительный Expression хранится в factoryContext.ContextArgAccess и используется для вызова метода обработчика на последнем этапе конвейера фильтрации.

Построение конвейера фильтрации в CreateFilterPipeline().

Следующее большое изменение происходит в CreateTargetableRequestDelegate(), где мы вызываем CreateFilterPipeline() для создания EndpointFilterDelegate:

EndpointFilterDelegate? filterPipeline = null

if (factoryContext.EndpointBuilder.FilterFactories.Count > 0)
{
    filterPipeline = CreateFilterPipeline(methodInfo, targetExpression, factoryContext, targetFactory);

    // ... больше деталей, показано ниже
}

CreateFilterPipeline() отвечает за создание конвейера и имеет следующую сигнатуру:

private static EndpointFilterDelegate? CreateFilterPipeline(
    MethodInfo methodInfo, // оригинальный метод обработчика endpoint
    Expression? targetExpression, // приведение параметра 'target' к правильному типу, например, (Program)target
    RequestDelegateFactoryContext factoryContext, // контекст фабрики для создания RequestDelegate
    Expression<Func<HttpContext, object?>>? targetFactory) // _ => handler.Target; 

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

Создание последнего вызова обработчика.

Подобно построению конвейера middleware и других конструкций "матрешки", CreateFilterPipeline() начинает с "самого внутреннего" обработчика и последовательно оборачивает вокруг него дополнительные обработчики. Сначала создается вызов внутреннего обработчика с помощью:

targetExpression is null
    ? Expression.Call(methodInfo, factoryContext.ContextArgAccess)
    : Expression.Call(targetExpression, methodInfo, factoryContext.ContextArgAccess)

Это выражение вызывает исходный метод обработчика эндпоинта, используя выражения context.GetArgument(0):

target.handler.Invoke(context.GetArgument<string>(0));

Это выражение передается в качестве аргумента в метод MapHandlerReturnTypeToValueTask() вместе с типом возврата исходного обработчика (в нашем случае - строка):

Expression handlerReturnMapping = MapHandlerReturnTypeToValueTask(
    targetExpression is null        // target.handler.Invoke(context.GetArgument<string>(0));
        ? Expression.Call(methodInfo, factoryContext.ContextArgAccess)
        : Expression.Call(targetExpression, methodInfo, factoryContext.ContextArgAccess),
    methodInfo.ReturnType);         // string

MapHandlerReturnTypeToValueTask() отвечает за изменение типа возврата метода обработчика endpoint в ValueTask. Обратите внимание, что речь идет не о записи ответа, а исключительно о превращении его в ValueTask<object?>, чтобы он мог вписаться в конвейер фильтрации как EndpointFilterDelegate.

Для нашего примера минимального API (возвращение строки) MapHandlerReturnTypeToValueTask() вызывает метод WrapObjectAsValueTask, который просто заворачивает результат вызова обработчика в ValueTask<object?>, выдавая код, похожий на:

return ValueTask.FromResult<object?>(
    target.handler.Invoke(context.GetArgument<string>(0))
);

Создание целевого экземпляра.

Далее CreateFilterPipeline() создает целевой экземпляр с помощью targetFactory. В предыдущей статье я вкратце рассказал о них: target — это экземпляр, на котором вызывается метод обработчика. Для лямбда-метода это содержащийся класс, но он может быть и null, если вы используете, например, статический метод.

BlockExpression handlerInvocation = Expression.Block(
    new[] { TargetExpr },
    targetFactory == null
        ? Expression.Empty()
        : Expression.Assign(TargetExpr, Expression.Invoke(targetFactory, FilterContextHttpContextExpr)),
    handlerReturnMapping
);

Это создает выражение, которое выглядит примерно так, где targetFactory определяется как _ => handler.Target для нашего примера минимального API:

target = targetFactory(context.HttpContext);
return ValueTask.FromResult<object?>(                     // from handlerReturnMapping
    target.handler.Invoke(context.GetArgument<string>(0)) // 
);

Для статических методов targetFactory будет равно null, поэтому весь handlerInvocation будет выглядеть примерно так:

return ValueTask.FromResult<object?>(              // from handlerReturnMapping
    handler.Invoke(context.GetArgument<string>(0)) // 
);

Теперь нам нужно превратить вызов этого обработчика в EndpointFilterDelegate.

Создание финального внутреннего обработчика.

Следующий вызов CreateFilterPipeline() создает внутренний обработчик, определяя Expression следующим образом:

EndpointFilterDelegate filteredInvocation = Expression.Lambda<EndpointFilterDelegate>(
    Expression.Condition(
        Expression.GreaterThanOrEqual(FilterContextHttpContextStatusCodeExpr, Expression.Constant(400)),
        CompletedValueTaskExpr,
        handlerInvocation),
    FilterContextExpr).Compile();

Этот код Expression для нашего минимального API выглядит примерно так:

if(context.HttpContext.Response.StatusCode >= 400)
{
    return ValueTask.CompletedTask;
}
else
{
    target = targetFactory(context.HttpContext);              // 
    return ValueTask.FromResult<object?>(                     // from handlerInvocation
        target.handler.Invoke(context.GetArgument<string>(0)) // 
    );
}

Затем это компилируется в EndpointFilterDelegate, так что фактически это становится Func<EndpointFilterInvocationContext, ValueTask<object?>>, который выглядит следующим образом:

ValueTask<object?> filteredInvocation(EndpointFilterInvocationContext context)
{
    if(context.HttpContext.Response.StatusCode >= 400)
    {
        return ValueTask.CompletedTask;
    }
    else
    {
        var target = targetFactory(context.HttpContext);          // 
        return ValueTask.FromResult<object?>(                     // from handlerInvocation
            target.handler.Invoke(context.GetArgument<string>(0)) // 
        );
    }
}

Как вы видите, этот конечный обработчик обходит вызов обработчика, если какой-либо из фильтров устанавливает код ответа ошибки. Ответ метода обработчика оборачивается в ValueTask и возвращается из обработчика. Это позволяет обработчику подключиться к остальной части конвейера фильтров.

Создание линии фильтрации.

Теперь у нас готово большинство частей, и мы можем вызывать фабрики фильтров. Помните, что фабрики фильтров содержат код, который выполняется сейчас и возвращает EndpointFilterDelegate. CreateFilterPipeline() проходит по каждой фабрике (от последней к первой), передавая в качестве следующего параметра EndpointFilterFactoryContext и "остаток" конвейера фильтров:

var routeHandlerContext = new EndpointFilterFactoryContext
{
    MethodInfo = methodInfo,           // это оригинальный обработчик
    ApplicationServices = factoryContext.EndpointBuilder.ApplicationServices,
};

var initialFilteredInvocation = filteredInvocation;

// 👇Перебор всех зарегистрированных фабрик, начиная с последнего добавленного фильтра.
// "Последний" добавленный фильтр будет "самым внутренним" фильтром, который выполняется _после_
// "внешних" фильтров, отсюда и обратная зависимость
for (var i = factoryContext.EndpointBuilder.FilterFactories.Count - 1; i >= 0; i--)
{
    var currentFilterFactory = factoryContext.EndpointBuilder.FilterFactories[i];
    
    // вызываем фабрику, передавая контекст и уже отфильтрованный pipeline
    filteredInvocation = currentFilterFactory(routeHandlerContext, filteredInvocation);
}

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

(EndpointFilterFactoryContext context, EndpointFilterDelegate next) =>
{
    return async ctx =>
    {
        var name = ctx.GetArgument<string>(0);
        if (name is not "Sock")
        {
            return Results.ValidationProblem(
                new Dictionary<string, string[]>
                {
                    { "name", new[] { "Invalid name" } }
                });
        }

        return await next(ctx);
    };
}

Параметром контекста является routeHandlerContext, определенный в предыдущем блоке кода, а filteredInvocation передается как следующий. Это повторяется для каждой фабрики фильтров, таким образом, вы последовательно вкладываете фильтры.

После выполнения всех фабрик фильтров функция CreateFilterPipeline() возвращает окончательно отфильтрованный pipeline или null, если фабрики фильтров не изменили pipeline вообще.

Помните, что, если вы используете добавление фильтров с помощью AddEndpointFilter(), фильтр будет выполняться всегда. Если вы добавляете фильтры с помощью AddEndpointFilterFactory(), вы можете не добавлять фильтр к endpoint, и это не повлияет на время выполнения.

// Фабрики фильтров были запущены без изменения поведения каждого запроса, 
// поэтому мы можем пропустить запуск конвейера.
if (ReferenceEquals(initialFilteredInvocation, filteredInvocation))
{
    return null;
}

return filteredInvocation;

Здесь мы рассмотрели метод CreateFilterPipeline(), теперь давайте вернемся к рассмотрению того, где он был вызван в CreateTargetableRequestDelegate().

Вызов фильтрующего конвейера в CreateTargetableRequestDelegate.

Мы вызвали CreateFilterPipeline() из CreateTargetableRequestDelegate при создании окончательного RequestDelegate. Теперь мы можем посмотреть на остальные изменения:

EndpointFilterDelegate? filterPipeline = null;
var returnType = methodInfo.ReturnType;

if (factoryContext.EndpointBuilder.FilterFactories.Count > 0)
{
    // Построение конвейера фильтрации в CreateFilterPipeline()
    filterPipeline = CreateFilterPipeline(methodInfo, targetExpression, factoryContext, targetFactory);

    // Если бы мы действительно добавили какие-либо фильтры
    if (filterPipeline is not null)
    {
        // Создание выражения, вызывающего конвейер фильтрации
        Expression<Func<EndpointFilterInvocationContext, ValueTask<object?>>> invokePipeline = 
            (context) => filterPipeline(context);

        // Тип возврата конвейера всегда ValueTask<object?>,
        // независимо от того, каким был исходный тип возврата обработчика.
        returnType = typeof(ValueTask<object?>);
        
        // Изменение метода "handler" на вызов конвейера вместо этого
        factoryContext.MethodCall = Expression.Block(
            new[] { InvokedFilterContextExpr },
            Expression.Assign(
                InvokedFilterContextExpr,
                CreateEndpointFilterInvocationContextBase(factoryContext, factoryContext.ArgumentExpressions)),
            Expression.Invoke(invokePipeline, InvokedFilterContextExpr)
        );
    }
}

Этот код делает две вещи:

• Изменяет конечный returnType на ValueTask<object?>, независимо от того, что возвращает метод обработчика.
• Преобразует factoryContext.MethodCall в вызов, который создает новый экземпляр filterContext и запускает конвейер фильтрации. Он использует общий тип EndpointFilterInvocationContext<T> для эффективного " приведения" в вызовах GetArgument<T>.

Последний пункт интересен: EndpointFilterInvocationContext является негенеративным базовым типом, но существуют генеративные производные классы EndpointFilterInvocationContext, EndpointFilterInvocationContext<T1, T2> и т. д. (до 10 генеративных аргументов)! Эти общие типы гарантируют, что аргументы struct не будут уупакованы при вызове GetArgument<T>.

Все это дает код, который для нашего примера выглядит примерно так:

EndpointFilterInvocationContext filterContext = 
    new EndpointFilterInvocationContext<string>(httpContext, name_local)
invokePipeline.Invoke(filterContext);

Это вызывает конвейер фильтрации, но нам все еще нужно обработать результат фильтрации.

Обработка результата конвейера фильтрации.

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

• Конвейер фильтрации всегда возвращает ValueTask<object?>, вместо результата обработчика, поэтому нам нужно изменить способ сериализации результата в ответ.
• Без фильтров Task.CompletedTask возвращается, когда wasParamCheckFailure == true, до вызова обработчика. Мы не можем сделать это с конвейером фильтров, потому что нам всегда нужно вызывать фильтры, независимо от того, была ли привязка модели успешной.

Последнее достигается просто: в CreateParamCheckingResponseWritingMethodCall() мы изменяем условие проверки, чтобы установить код статуса 400, но не возвращать Task.CompletedTask. Поэтому вместо этого:

if(wasParamCheckFailure)
{
    httpContext.Response.StatusCode = 400;
    return Task.CompletedTask;
}

мы создаем это:

if(wasParamCheckFailure)
{
    httpContext.Response.StatusCode = 400;
}

Как вы видели ранее, самый внутренний фильтр (который вызывает обработчик endpointа) обходит обработчик, если после выполнения фильтров код состояния является кодом ошибки.

Наконец, AddResponseWritingToMethodCall() добавляет код для обработки ValueTask<object?>, ожидая его и генерируя соответствующий метод написания ответа, как описано в предыдущей статье. Здесь нет ничего специфичного для filter-pipeline, кроме того, что нам всегда нужна одна и та же обработка ответа, поскольку filter pipeline всегда возвращает ValueTask<object?>.

И на этом мы закончили!

Обзор конвейера фильтрации RequestDelegate.

В завершение мы еще раз рассмотрим окончательный "эффективный" RequestDelegate для нашего ""фильтрованного" минимального API":

Task TargetableRequestDelegate(object? target, HttpContext httpContext)
{
    string name_local;
    bool wasParamCheckFailure;

    name_local = httpContext.Request.RouteValues["name"]
    if (name_local == null)
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "string", "name", "route");
    }

    if(wasParamCheckFailure)
    {
        httpContext.Response.StatusCode = 400;
        // Обратите внимание, что здесь мы _не_ возвращаем Task.CompletedTask
    }

    var filterContext = new EndpointFilterInvocationContext<string>(httpContext, name_local)
    // Запуск конвейера фильтрации
    ValueTask<object?> result = filterPipeline.Invoke(filterContext); 

    // Обработка результата конвейера фильтрации и сериализация
    return ExecuteValueTaskOfObject(result, httpContext);

    // Конвейер фильтров для нашего обработчика (один уровень вложенности)
    ValueTask<object?> filterPipeline(EndpointFilterInvocationContext context)
    {
        var name = ctx.GetArgument<string>(0);
        if (name is not "Sock")
        {
            return Results.ValidationProblem(
                new Dictionary<string, string[]>
                {
                    { "name", new[] { "Invalid name" } }
                });
        }

        // Вызов "внутреннего" обработчика
        return await filteredInvocation(ctx);
    }

    // Самый "внутренний" фильтр в конвейере, который вызывает метод обработчика
    ValueTask<object?> filteredInvocation(EndpointFilterInvocationContext context)
    {
        if(context.HttpContext.Response.StatusCode >= 400)
        {
            // Уже произошла ошибка, не запускайте метод обработчика
            return ValueTask.CompletedTask;  
        }
        else
        {
            // Создайте "экземпляр" цели (если таковой имеется)
            var target = targetFactory(context.HttpContext); 
            // Выполняем обработчик, используя аргументы из контекста фильтра
// и оборачиваем результат в ValueTask
            return ValueTask.FromResult<object?>( 
                target.handler.Invoke(context.GetArgument<string>(0)) // фактическое выполнение обработчика
            );
        }
    }
}

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

Подведение итогов.

В этой статье мы рассмотрели, как фильтры минимального API и фабрики фильтров изменяют конечный RequestDelegate, созданный для endpoint. Мы начали с рассмотрения конечного RequestDelegate, созданного для обработчика отфильтрованной endpoint. Есть несколько важных отличий по сравнению с нефильтрованным RequestDelegate:

• Когда связывание аргументов не удается, мы не выполняем немедленное замыкание, как в нефильтрованном случае. Вместо этого фильтры продолжают выполняться, а ошибка связывания обрабатывается в самом "внутреннем" обработчике.
• Результат обработчика конечной точки всегда обернут в ValueTask<object?>.
• Объект контекста EndpointFilterInvocationContext<> создается для каждого обработчика endpoint в соответствии с количеством и типом аргументов обработчика endpoint.
• Если фабрика фильтров не настраивает EndpointFilterDelegate, она вообще не добавляется в конвейер.

Главный вывод заключается в том, что фильтры в минимальных API реализованы самым эффективным способом. Они добавляют накладные расходы только для конкретных endpoints, к которым они применяются, и они компилируются в конечный RequestDelegate очень эффективным образом.

Это подводит нас к концу этого подробного обзора минимальных API. Лично я впечатлен тем, как RequestDelegateFactory работает над тем, чтобы сделать минимальные API настолько эффективными, насколько это вообще возможно!

С оригиналом статьи вы можете ознакомиться по ссылке.

Это седьмая статья из серии: "За кулисами минимальных API".

В этой серии статей мы рассмотрели различные элементы, необходимые для превращения эндпоинта minimal API в RequestDelegate, который может вызывать ASP.NET Core. Мы рассмотрели различные классы, извлечение метаданных из обработчика minimal API, а также то, как работает привязка в minimal API. Далее мы рассмотрели, как RequestDelegateFactory создает части выражения, которые объединяются в RequestDelegate, как для выражений аргументов (части 1 и 2), так и для ответа.

В этой статье мы соберем все эти компоненты вместе, чтобы увидеть, как строится RequestDelegate. В предыдущих статьях я пропустил и упростил некоторые сложные моменты, но в этой статье я стараюсь максимально приблизиться к реальности. Мы рассмотрим метод RequestDelegateFactory.Create(), увидим порядок построения различных выражений, которые входят в RequestDelegate, и посмотрим, как они комбинируются. Я постараюсь не затрагивать слишком много функций, которые я рассматривал в предыдущих статьях, поэтому эту статью лучше читать после прочтения прошлых статей.

В этой заметке я пока пропущу фильтры и фабрики фильтров. Мы вернемся к ним в следующей статье, чтобы посмотреть, как они изменяют ситуацию по сравнению с "простым" случаем, показанным в этой статье.

Создание RequestDelegate: RequestDelegateFactory.Create()

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

app.MapGet("/{name}", (string name) => $"Hello {name}!");

Основное внимание в этой статье уделено методу RequestDelegateFactory.Create(). Существует несколько перегрузок, но в итоге они вызывают перегрузку, которая принимает:

• Delegate handler - обработчик эндпоинта минимального API (string name) => $"Hello {name}"
• RequestDelegateFactoryOptions? options - содержит различные контекстные значения и настройки эндпоинта, как обсуждалось ранее.
• RequestDelegateMetadataResult? metadataResult - содержит результат вызова RequestDelegateFactory.InferMetadata(), включая выведенные метаданные и кэшированный RequestDelegateFactoryContext.

Последние два параметра являются необязательными и служат в основном для оптимизации; если они не указаны, метод Create() создаст их сам. Для целей этой статьи я буду считать, что эти значения не указаны, так как это немного упрощает следование последовательности в Create().

На практике, в минимальных API, эти значения всегда предоставляются, поскольку они создаются в RequestDelegateFactory.InferMetadata(), который вызывается перед Create().

В этой статье я буду отслеживать содержимое важных переменных по мере выполнения метода Create(), чтобы мы могли видеть, как все сочетается.

Создание targetExpression.

Давайте начнем рассматривать функцию RequestDelegateFactory.Create(), рассматривая по одному утверждению за раз.

public static RequestDelegateResult Create(
    Delegate handler, 
    RequestDelegateFactoryOptions? options = null,
    RequestDelegateMetadataResult? metadataResult = null)
{
    if (handler is null)
    {
        throw new ArgumentNullException(nameof(handler));
    }

    UnaryExpression targetExpression = handler.Target switch
    {
        object => Expression.Convert(TargetExpr, handler.Target.GetType()),
        null => null,
    };

    // ...
}

Функция начинается с проверки обработчика на null, а затем создает выражение Expression под названием targetExpression, которое имеет одно из двух значений:

• Если handler.Target имеет значение null, значит null
• В противном случае, выражение, которое преобразует "целевой параметр" к требуемому типу.

Если вы используете статический метод обработчика, handler.Target будет равен null, в противном случае он возвращает экземпляр типа, для которого был вызван обработчик. В нашем случае, поскольку мы используем метод лямбды, экземпляром является класс закрытия (вложенный внутрь класса Program), в котором мы определили лямбду. Этот класс закрытия обычно имеет "неправильное" имя в C#, например <>, поэтому в дальнейшем мы будем использовать его.

Вам может показаться удивительным, что метод лямбда является "экземпляром", а не статическим типом. Причина в том, что компилятор создает класс закрытия для захвата контекста лямбды (даже если вы определяете лямбду с помощью ключевого слова static). Вы можете увидеть это в действии, используя опцию sharplab.io "C#", чтобы посмотреть результат эффективного сокращения Func<>.

На данном этапе у нас есть две переменные, представляющие интерес: handler и targetExpression:

Перейдем к следующим нескольким строкам Create().

Создание RequestDelegateFactoryContext и targetFactory

Следующие несколько строк относительно просты:

// ...
RequestDelegateFactoryContext factoryContext = 
    CreateFactoryContext(options, metadataResult, handler);

Expression<Func<HttpContext, object?>> targetFactory = (httpContext) => handler.Target;
// ...

Первая строка создает тип RequestDelegateFactoryContext. Этот тип отслеживает все важные данные о создании RequestDelegate и в основном представляет собой пакет свойств. Вы можете посмотреть полное определение класса здесь, но он содержит такие свойства, как:

• AllowEmptyRequestBody—допускаются ли пустые тела запросов, или обработчик должен отбрасываться.
• UsingTempSourceString—использует ли код разбора аргументов переменную tempSourceString.
• ExtraLocals—выражения, определяющие дополнительные переменные, которые необходимы при связывании аргументов.
• ParamCheckExpressions—выражения, определяющие "проверку аргументов", которая происходит после связывания.

У контекста есть еще много свойств, некоторые из которых копируются прямо из объекта options. Мы уже рассмотрели метод CreateFactoryContext() в предыдущей статье, поэтому пока оставим его в покое, но мы будем отслеживать некоторые важные свойства RequestDelegateFactoryContext в последующих шагах.

Следующая строка Create() создает выражение, определяющее функцию-фабрику, которая создает необходимый экземпляр цели метода, учитывая окружающую переменную HttpContext: httpContext => handler.Target. Это также можно было бы определить как _ => handler.Target, так как параметр не используется; насколько я могу судить, параметр HttpContext используется для облегчения композиции позже (когда вы используете фильтры). Я добавлю дополнительные переменные в нашу таблицу отслеживания:

Теперь мы переходим к функции CreateTargetableRequestDelegate(), которую мы рассматривали в предыдущей статье.

Вводим CreateTargetableRequestDelegate и создаем выражения аргументов.

Следующей строкой RequestDelegateFactory.Create() является:

// ...
Func<object?, HttpContext, Task>? targetableRequestDelegate = 
    CreateTargetableRequestDelegate(
        handler.Method, targetExpression, factoryContext, targetFactory);
// ...

Мы рассмотрели CreateTargetableRequestDelegate в предыдущей статье, где мы рассмотрели, как создается выражение ответа. В этой статье мы рассмотрим этот метод, чтобы увидеть, как и где создаются выражения аргумента и ответа. Каждое выражение хранится в переменной factoryContext, поэтому мы продолжим отслеживать их в нашей таблице переменных.

Как видно из приведенного выше вызова метода, мы передаем в метод практически весь текущий контекст:

private static Func<object?, HttpContext, Task>? CreateTargetableRequestDelegate(
    MethodInfo methodInfo,
    Expression? targetExpression,
    RequestDelegateFactoryContext factoryContext,
    Expression<Func<HttpContext, object?>>? targetFactory = null)
{
    factoryContext.ArgumentExpressions ??= 
        CreateArgumentsAndInferMetadata(methodInfo, factoryContext);

    // ...
}

Первая строка этого метода - CreateArgumentsAndInferMetadata(). Мы уже подробно рассмотрели этот метод и метод CreateArgument(), на который он опирается для построения выражений связывания аргументов, поэтому в этой статье мы рассмотрим только выходные выражения этого метода, которых несколько!

Для нашего примера обработчика

(string name) => $"Hello {name}!"`

CreateArgumentsAndInferMetadata() создает три основных выражения:

• Expression который передается в аргумент обработчика - выражение, состоящее из переменной: name_local. Оно добавляется в factoryContext.ArgumentExpressions.
• Expression определение дополнительных локальных переменных, необходимых для привязки, в данном случае это аналогично локальной переменной name_local. Она добавляется в factoryContext.ExtraLocals.
• Выражение проверки параметров, для проверки правильности привязки строкового аргумента - добавляется в factoryContext.ParamCheckExpressions. В предыдущей статье вы видели, что оно генерирует выражение, подобное следующему:

name_local = httpContext.Request.RouteValues["name"]
if (name_local == null)
{
     wasParamCheckFailure = true;
     Log.RequiredParameterNotProvided(httpContext, "string", "name", "route");
}

Вызов функции Log ссылается на "реальный" метод в RequestDelegateFactory, который вызывается в выражении с помощью Expression.Call().

CreateArgumentsAndInferMetadata() устанавливает различные другие вспомогательные значения и метаданные, но это основные значения, создаваемые в случае простой привязки строки к значению маршрута. Для других типов привязки вы должны установить дополнительные значения на factoryContext, как описано в моих предыдущих статьях. Например:

• factoryContext.UsingTempSourceString—устанавливается в true при разборе типа TryParse(), например, при связывании параметра int.
• factoryContext.ParameterBinders—выражение для привязки параметров BindAsync().
• factoryContext.JsonRequestBodyParameter—Ссылка на ParameterInfo (если есть), который требует привязки к телу запроса в формате JSON.
• factoryContext.FirstFormRequestBodyParameter—Ссылка на первый ParameterInfo (если есть) который требует привязки к телу запроса в виде формы. Обратите внимание, что несколько параметров тела запроса формы приводят к ошибке.

Если сложить все это вместе, то после вызова CreateArgumentsAndInferMetadata() мы получим следующие переменные и кэшированные значения:

Продолжим работу над CreateTargetableRequestDelegate().

Создание вызова метода Expression

Следующим шагом в CreateTargetableRequestDelegate является CreateMethodCall(), который создает выражение для фактического вызова обработчика минимального API:

private static Func<object?, HttpContext, Task>? CreateTargetableRequestDelegate(
    MethodInfo methodInfo,
    Expression? targetExpression,
    RequestDelegateFactoryContext factoryContext,
    Expression<Func<HttpContext, object?>>? targetFactory = null)
{
    // ...

    factoryContext.MethodCall = 
        CreateMethodCall(methodInfo, targetExpression, factoryContext.ArgumentExpressions);
    
    // ...
}

CreateMethodCall() — это небольшой метод, который принимает метод обработчика, выражение targetExpression и выражения аргументов и объединяет их в одно выражение:

private static Expression CreateMethodCall(
    MethodInfo methodInfo, Expression? target, Expression[] arguments) =>
    target is null ?
        Expression.Call(methodInfo, arguments) :
        Expression.Call(target, methodInfo, arguments);

Возвращаемый Expression хранится в factoryContext.MethodCall. Если вы проанализируете это, то увидите, что результирующий код выглядит примерно так; это просто вызов обработчика минимального API и передача аргумента name_local:

((Program.<>c) target).Handler.Invoke(name_local)

По сути, это вызов вашего обработчика минимального API и передача выражений аргументов.

В качестве альтернативы, если вы думаете об обработчике как о лямбде Func<string, string>, определенной на Program:

public class Program
{
    Func<string, string> handler = (string name) => $"Hello {name}!";
}

Тогда factoryContext.MethodCall выглядит просто как:

target.handler(name_local)

Для простоты я буду использовать эту нотацию до конца статьи. Добавим это в наши переменные. Мы больше не будем использовать ArgumentExpressions, поэтому я удалил их из таблицы:

В следующей части CreateTargetableRequestDelegate рассматриваются фильтры, поэтому мы пока пропустим её и перейдём к вызову метода CreateParamCheckingResponseWritingMethodCall .

Построение делегата запроса в CreateParamCheckingResponseWritingMethodCall

В следующем разделе CreateTargetableRequestDelegate() все действительно начинает быстро сходиться:

private static Func<object?, HttpContext, Task>? CreateTargetableRequestDelegate(
    MethodInfo methodInfo,
    Expression? targetExpression,
    RequestDelegateFactoryContext factoryContext,
    Expression<Func<HttpContext, object?>>? targetFactory = null)
{
    // ...

    Type returnType = methodInfo.ReturnType;
    
    // ...Filter magic
    
    Expression responseWritingMethodCall = factoryContext.ParamCheckExpressions.Count > 0 
        ? CreateParamCheckingResponseWritingMethodCall(returnType, factoryContext) 
        : AddResponseWritingToMethodCall(factoryContext.MethodCall, returnType);
    
    // ...
}

В этом разделе мы вызываем один из двух методов, в зависимости от того, есть ли какие-либо ParamCheckExpressions:

• CreateParamCheckingResponseWritingMethodCall—вызывается для добавления любых ParamCheckExpression в RequestDelegate, затем вызывается AddResponseWritingToMethodCall
• AddResponseWritingToMethodCall—Занимается сериализацией возвращаемого значения обработчика и записью ответа.

Я подробно описал оба этих метода в предыдущей статье, поэтому вы можете обратиться к ней для получения подробной информации о том, как строятся выражения. В нашем примере у нас есть выражение ParamCheckExpression, поэтому мы вызываем CreateParamCheckingResponseWritingMethodCall и сохраняем результат в переменной responseWritingMethodCall. Для нашего примера это выглядит следующим образом:

string name_local; // factoryContext.ExtraLocals
bool wasParamCheckFailure;

name_local = httpContext.Request.RouteValues["name"]  //
if (name_local == null)                               //
{                                                     //
     wasParamCheckFailure = true;                     // factoryContext.ParamCheckExpressions
     Log.RequiredParameterNotProvided(                //
        httpContext, "string", "name", "route");      //
}                                                     //

if(wasParamCheckFailure)
{
    httpContext.Response.StatusCode = 400;
    return Task.CompletedTask;
}

ExecuteWriteStringResponseAsync(
    httpContext,
    target.handler(name_local)); // factoryContext.MethodCall

Приведенное выше Expression состоит как из значений Expression, которые мы создали ранее, так и из нового кода, добавленного CreateParamCheckingResponseWritingMethodCall.

Последний вызов в Expression вызывает обработчик и передает результат в функцию ExecuteWriteStringResponseAsync вместе с параметром httpContext (который еще не определен). ExecuteWriteStringResponseAsync — это частная функция в RequestDelegateFactory, показанная ниже:

private static Task ExecuteWriteStringResponseAsync(
    HttpContext httpContext, string text)
{
    SetPlaintextContentType(httpContext);
    return httpContext.Response.WriteAsync(text);
}

private static void SetPlaintextContentType(HttpContext httpContext)
    => httpContext.Response.ContentType ??= "text/plain; charset=utf-8";

Теперь у нас действительно что-то получается. Выражение выше хранится в responseWritingMethodCall, поэтому мы можем не беспокоиться об отслеживании других переменных в нашей таблице; это единственное выражение, которое сейчас имеет значение. Конец близок!

Компиляция выражения в Func<object?, HttpCotnext, Task>

Заключительные строки в CreateTargetableRequestDelegate выглядят следующим образом:

private static Func<object?, HttpContext, Task>? CreateTargetableRequestDelegate(
    MethodInfo methodInfo,
    Expression? targetExpression,
    RequestDelegateFactoryContext factoryContext,
    Expression<Func<HttpContext, object?>>? targetFactory = null)
{
    // ...

    if (factoryContext.UsingTempSourceString)
    {
        responseWritingMethodCall = Expression.Block(
            new[] { TempSourceStringExpr }, responseWritingMethodCall);
    }

    return HandleRequestBodyAndCompileRequestDelegate(
        responseWritingMethodCall, factoryContext);
}

В if условно добавляется строка tempSourceString в верхнюю часть RequestDelegate, если это необходимо для целей разбора. В нашем случае она не нужна, но, если бы у нас был, например, параметр int, ее нужно было бы добавить.

Последний вызов метода - HandleRequestBodyAndCompileRequestDelegate(). Название намекает на обязанности этого метода; он отвечает за три вещи:

• Добавление необходимого Expression для чтения из тела запроса/формы, если это требуется.
• Добавление необходимого Expression для любых аргументов BindAsync.
• Компиляция Expression в функцию.

В нашем примере API не читает из тела запроса (это GET-запрос), поэтому я остановлюсь на этой части.

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

private static Func<object?, HttpContext, Task> HandleRequestBodyAndCompileRequestDelegate(
    Expression responseWritingMethodCall, 
    RequestDelegateFactoryContext factoryContext)
{
    // Do we need to bind to the body/form?
    if (factoryContext.JsonRequestBodyParameter is null && !factoryContext.ReadForm)
    {
        // No - Do we have any BindAsync() parameters?
        if (factoryContext.ParameterBinders.Count > 0)
        {
            // Yes, so we need to generate the code for reading from the custom binders calling into the delegate
            var continuation = Expression.Lambda<Func<object?, HttpContext, object?[], Task>>(
                responseWritingMethodCall, TargetExpr, HttpContextExpr, BoundValuesArrayExpr).Compile();

            var binders = factoryContext.ParameterBinders.ToArray();
            var count = binders.Length;

            return async (target, httpContext) =>
            {
                var boundValues = new object?[count];

                for (var i = 0; i < count; i++)
                {
                    boundValues[i] = await binders[i](httpContext);
                }

                await continuation(target, httpContext, boundValues);
            };
        }

        // No - we don't have any BindAsync methods
        return Expression.Lambda<Func<object?, HttpContext, Task>>(
            responseWritingMethodCall, TargetExpr, HttpContextExpr).Compile();
    }

    // Bind to the form/body
    return factoryContext.ReadForm
        ? HandleRequestBodyAndCompileRequestDelegateForForm(responseWritingMethodCall, factoryContext)
        : HandleRequestBodyAndCompileRequestDelegateForJson(responseWritingMethodCall, factoryContext);
}

Если вы проследите за ветвями, то увидите, что для нашего примера этот метод ничего не добавляет к существующему Expression. Этот метод просто компилирует имеющееся у нас Expression в Func<object?, HttpContext, Task>, который выглядит примерно следующим образом:

Task TargetableRequestDelegate(object? target, HttpContext httpContext)
{
    string name_local;
    bool wasParamCheckFailure;

    name_local = httpContext.Request.RouteValues["name"]
    if (name_local == null)
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "string", "name", "route");
    }

    if(wasParamCheckFailure)
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    return ExecuteWriteStringResponseAsync(
        httpContext,
        handler(name_local));
}

Обратите внимание, что теперь это Func<>, который может быть вызван, но это не RequestDelegate, поскольку в сигнатуре метода есть дополнительный параметр target. Чтобы создать окончательный RequestDelegate, нам нужно пройти по стеку до самого метода Create(), чтобы вызвать CreateTargetableRequestDelegate().

Построение окончательного RequestDelegate

Теперь мы почти на финишной прямой. Оставшиеся части Create() в основном занимаются наведением порядка и обработкой периферийных случаев, на которых мы не фокусируемся. Важным моментом является преобразование Func<>, хранящегося в targetableRequestDelegate, в настоящий RequestDelegate:

public static RequestDelegateResult Create(
    Delegate handler, 
    RequestDelegateFactoryOptions? options = null,
    RequestDelegateMetadataResult? metadataResult = null)
{
    RequestDelegate finalRequestDelegate = targetableRequestDelegate switch
    {
        // если targetableRequestDelegate равен null, то мы попали в крайний случай, на котором мы сейчас не фокусируемся!
        null => (RequestDelegate)handler,

        // В противном случае создаем RequestDelegate
        _ => httpContext => targetableRequestDelegate(handler.Target, httpContext),
    };

    // сохранить finalRequestDelegate в RequestDelegateResult
    return CreateRequestDelegateResult(finalRequestDelegate, factoryContext.EndpointBuilder);
}

Итак, для нашего примера finalRequestDelegate, который является экземпляром RequestDelegate (Func<HttpContext, Task>), выглядит примерно так:

(HttpContext httpContext) => TargetableRequestDelegate(Program.<>c, httpContext)

Где

• Program.<>c это кэшированный экземпляр лямбды
• TargetableRequestDelegate скомпилированный Expression который мы сохранили в предыдущей секции ( Func<HttpContext, object?, Task>).

Это RequestDelegate, который вызывается, когда ваш эндпоинт минимального API обрабатывает запрос.

Это (наконец-то) подводит нас к концу этой статьи о том, как создается RequestDelegate. Это запутанный и сложный процесс, но конечным результатом является простой Func<HttpContext, Task>, который может быть выполнен в ответ на запрос, что в итоге элегантно!

Конечно, мы еще не закончили. Я все обещаю, что мы рассмотрим фильтры, так что в следующем посте мы это сделаем. Надеюсь, со всей этой предысторией понять их назначение и влияние на RequestDelegate будет немного проще!

Подведение итогов

В этом посте мы рассмотрели метод RequestDelegateFactory.Create(), чтобы понять, как все выражения, которые мы рассматривали в этой серии, объединяются в конечный RequestDelegate.

Мы начали с рассмотрения targetExpression и targetFactory и выяснили, что даже статические лямбда-методы имеют "целевой" экземпляр. Затем мы перешли к CreateArgumentsAndInferMetadata() и помощнику CreateArgument(), в котором мы определяем основную часть различных компонентов Expression. Здесь определены все выражения, связанные с привязкой аргументов к HttpContext.

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

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

В HandleRequestBodyAndCompileRequestDelegate мы наконец-то вызываем Compile() и превращаем выражение в Func<object, HttpContext, Task>. Это еще не совсем RequestDelegate, но RequestDelegateFactory.Create() "обертывает" его для создания требуемой сигнатуры, передавая целевой экземпляр, что дает окончательную, требуемую, Func<HttpContext, Task> сигнатуру RequestDelegate.

С оригиналом статьи вы можете ознакомиться по ссылке.

В предыдущих двух статьях я подробно рассмотрел, как метод RequestDelegateFactory.CreateArgument() создает выражение, используемое для привязки различных типов параметров в обработчике эндпоинта. Точное выражение, необходимое для этого, различается в зависимости от типа параметра, который вы связываете, и части HttpRequest, к которой вы его привязываете.

Точно так же, в зависимости от типа возврата вашего обработчика, вам нужно генерировать разные выражения для обработки типа возврата обработчика и записи HTTP-ответа. В этой статье мы начнем рассматривать, как RequestDelegateFactory.Create() создает конечный RequestDelegate, сосредоточившись на различных выражениях, которые генерируются в зависимости от сигнатуры вашего обработчика.

Генерация ответа с помощью CreateTargetableRequestDelegate.

В этой статье мы не будем рассматривать весь метод RequestDelegateFactory.Create(). Вместо этого мы рассмотрим один из вызываемых им частных методов: CreateTargetableRequestDelegate(). Этот метод принимает эндпоинт обработчика, использует выражения аргументов, созданные CreateArguments(), и генерирует выражение, которое записывает ответ.

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

• Постройте выражения связывания аргументов, если это еще не сделано.
• Создайте выражение MethodCall — это выражение, которое фактически вызывает метод обработчика, используя выражения аргументов.
• Если выражения привязки аргументов включают проверку, вызывается CreateParamCheckingResponseWritingMethodCall, который в случае неудачи генерирует запрос 400 Bad Request.
• Если валидация не требуется, вызывается AddResponseWritingToMethodCall.
• Если в выражении аргумента используется переменная tempSourceString, добавляет ее в начало выражения.
• Добавляет выражение для чтения из тела запроса, как показано в предыдущем сообщении, и компилирует это выражение в Func<>, который используется для создания окончательного RequestDelegate.

private static Func<object?, HttpContext, Task>? CreateTargetableRequestDelegate(
    MethodInfo methodInfo, // лямбда функция хэндлера
    Expression? targetExpression,
    RequestDelegateFactoryContext factoryContext,
    Expression<Func<HttpContext, object?>>? targetFactory = null)
{
    // Строит выражения аргументов, если они по какой-то причине не были построены ранее
    factoryContext.ArgumentExpressions ??= CreateArgumentsAndInferMetadata(methodInfo, factoryContext);

    // Создает выражение, которое фактически вызывает обработчик, передавая аргументы
    factoryContext.MethodCall = CreateMethodCall(
        methodInfo, targetExpression, factoryContext.ArgumentExpressions);

    var returnType = methodInfo.ReturnType;

    // Если какой-либо из параметров имеет валидацию (например, проверка на null), то.
    // генерируем валидацию Expression. Генерирует окончательный "write response"
    // Выражение в обоих случаях и присваивает его переменной.
    var responseWritingMethodCall = factoryContext.ParamCheckExpressions.Count > 0 ?
        CreateParamCheckingResponseWritingMethodCall(returnType, factoryContext) :
        AddResponseWritingToMethodCall(factoryContext.MethodCall, returnType);

    // Если какой-либо из параметров использует для разбора переменную tempSourceString.
    // то добавляет определение переменной в начало 
    if (factoryContext.UsingTempSourceString)
    {
        responseWritingMethodCall = Expression.Block(
            new[] { TempSourceStringExpr }, 
            responseWritingMethodCall);
    }

    // Добавляет чтение тела запроса и компилирует выражение в Func<>
    return HandleRequestBodyAndCompileRequestDelegate(responseWritingMethodCall, factoryContext);
}

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

string tempSourceString;

используя следующее определение:

internal static readonly ParameterExpression TempSourceStringExpr =
    Expression.Variable(typeof(string), "tempSourceString");

Функция CreateMethodCall() принимает ссылку на метод-обработчик, "target" вызова метода и выражения аргументов. "Target" — это объект (если таковой имеется), на который вызывается метод обработчика. Для minimal API, использующих статические методы, цель равна null, но если вы используете метод экземпляра или лямбду, она содержит ссылку на объект:

private static Expression CreateMethodCall(
    MethodInfo methodInfo, Expression? target, Expression[] arguments) =>
    target is null ?
        Expression.Call(methodInfo, arguments) :
        Expression.Call(target, methodInfo, arguments);

После компиляции это означает либо вызов handler(arg1, arg2), либо target.handler(arg1, arg2) в зависимости от того, является ли target null.

В следующем разделе мы рассмотрим метод CreateParamCheckingResponseWritingMethodCall(), который вызывается выше, когда привязка параметров к запросам может оказаться неудачной.

Добавление проверок валидности параметров в выражение.

Легче всего понять поведение CreateParamCheckingResponseWritingMethodCall(), думая о выражениях, которые добавляет CreateArgument(). Например, если мы возьмем следующий простой эндпоинт minimal API:

app.MapGet("/". (string q) => {});

Из предыдущих статей мы увидели, что начальный RequestDelegate выглядит следующим образом:

Task Invoke(HttpContext httpContext)
{
    bool wasParamCheckFailure = false;
    string q_local;
    
    q_local = httpContext.Request.Query["q"];
    if (q_local == null)
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "string", "q", "query");
    }

    if(wasParamCheckFailure)
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    handler.Invoke(q_local);
}

Метод CreateArgument() создает не все из перечисленного выше. CreateArgument() создает три части RequestDelegate как выражения, и хранит каждое выражение в отдельной коллекции в RequestDelegateFactoryContext factoryContext:

• Определение любых локальных переменных (q_local) хранится в factoryContext.ExtraLocals.
• Ссылка на аргумент, переданный в функцию-обработчик (q_local), в итоге хранится в factoryContext.ArgumentTypes.
• Выражение проверки параметров хранится в factoryContext.ParamCheckExpressions.

Выражение проверки параметров в данном случае состоит из присвоения q_local проверки на null и записи того, что данная проверка не пройдена:

q_local = httpContext.Request.Query["q"];
if (q_local == null)
{
    wasParamCheckFailure = true;
    Log.RequiredParameterNotProvided(httpContext, "string", "q", "query");
}

Учитывая это, давайте посмотрим, как CreateParamCheckingResponseWritingMethodCall() использует коллекции Expression для создания RequestDelegate. Я добавил комментарии к методу ниже, чтобы сделать его более понятным.

private static Expression CreateParamCheckingResponseWritingMethodCall(
    Type returnType, // тип возврата нашего обработчика эндпоинта, который в данном примере равен void
    RequestDelegateFactoryContext factoryContext)
{
    // Создает массив для хранения всех необходимых нам локальных переменных (например, q_local)
    // и копирует переменную Expressions. +1 переменная добавляется для 
    // дополнительной переменной wasParamCheckFailure, которая нам нужна
    var localVariables = new ParameterExpression[factoryContext.ExtraLocals.Count + 1];
    for (var i = 0; i < factoryContext.ExtraLocals.Count; i++)
    {
        localVariables[i] = factoryContext.ExtraLocals[i];
    }

    // Добавляет переменную `bool wasParamCheckFailure`.
    localVariables[factoryContext.ExtraLocals.Count] = WasParamCheckFailureExpr;

    // Создает массив для хранения выражений проверки параметров
    // и копирует выражения проверки. +1 добавляется к длине 
    // массива для хранения блока, который проверяет, было ли выражение успешным
    var checkParamAndCallMethod = new Expression[factoryContext.ParamCheckExpressions.Count + 1];
    for (var i = 0; i < factoryContext.ParamCheckExpressions.Count; i++)
    {
        checkParamAndCallMethod[i] = factoryContext.ParamCheckExpressions[i];
    }

    // Если фильтры зарегистрированы, мы должны позволить им работать.
    // даже если произошел сбой привязки. Подробнее об этом в следующей статье
    if (factoryContext.EndpointBuilder.FilterFactories.Count > 0)
    {
        // ... пока игнорируем фабрики фильтров
    }
    else
    {
        // Строим выражение, которое выглядит примерно следующим образом
        // if(wasParamCheckFailure)
        // {
        //     httpContext.Response.StatusCode = 400;
        //     return Task.CompletedTask;
        // }
        // else
        //     return handler(q_local); // Added by AddResponseWritingToMethodCall()
        var checkWasParamCheckFailure = Expression.Condition(
            WasParamCheckFailureExpr,
            Expression.Block(
                Expression.Assign(StatusCodeExpr, Expression.Constant(400)),
                CompletedTaskExpr),
            AddResponseWritingToMethodCall(factoryContext.MethodCall!, returnType));

        // Добавляем выражение в коллекцию
        checkParamAndCallMethod[factoryContext.ParamCheckExpressions.Count] = checkWasParamCheckFailure;
    }

    // Объединяем выражения переменных с проверкой параметров и ответами
// записываем выражения, вызывая каждое по очереди, чтобы построить единое выражение 
    return Expression.Block(localVariables, checkParamAndCallMethod);
}

В финальном выражении, сгенерированном выше, мы вызываем AddResponseWritingToMethodCall(). Он также вызывается непосредственно в CreateTargetableRequestDelegate(), когда у нас нет никаких выражений проверки параметров.

Генерация ответа с помощью функции AddResponseWritingToMethodCall().

Последний метод, который мы рассмотрим в этой статье - AddResponseWritingToMethodCall(). Этот метод отвечает за две вещи:

• Вызов метода обработчика в виде выражения Expression, созданного ранее с помощью CreateMethodCall.
• Обработка возвращаемого значения метода обработчика путем записи ответа в HttpResponse, если требуется.

Тело AddResponseWritingToMethodCall() — это, по сути, гигантский оператор if...else, переключающий тип возврата метода-обработчика и генерирующий соответствующее выражение. Вместо того, чтобы показывать 15 с лишним пунктов if, я кратко описал, как обрабатывается каждый тип возврата, показав примерный эффективный код C#, сгенерированный для каждого случая, с примером метода обработчика с типом возврата.

Возвращаемый тип: void

Для простейших методов обработчика, которые ничего не возвращают, тип возврата - void:

app.MapGet("/", (string q) => {})

Здесь ничего не нужно делать, кроме как вызывать обработчик, поэтому код вызова выглядит примерно так:

handler.Invoke(q_local); // вызвать обработчик
return Task.CompletedTask;

Возвращаемый тип: string

Следующим простейшим обработчиком является строковый ответ:

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

В этом случае делегат устанавливает Content-Type ответа на text/plain и сериализует возвращаемое обработчиком значение в выходной поток:

string text = handler.Invoke(); // эта переменная фактически вставлена, но включена для ясности
httpContext.Response.ContentType ??= "text/plain; charset=utf-8";
return httpContext.Response.WriteAsync(text);

Возвращаемый тип: IResult

string — это один из специальных возвращаемых типов в minimal API, а IResult - другой. Объект IResult отвечает за запись ответа в поток ответа и установку любых необходимых Content-Type или кодов состояния.

Статические помощники Results и TypedResults являются обычным способом возврата IResult:

app.Map("/", () => Results.NoContent());

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

var result = handler.Invoke(); // эта переменная фактически вставлена, но включена для ясности
return ExecuteResultWriteResponse(result, httpContext); // вызов хелпера для запуска ExecuteAsync

private static async Task ExecuteResultWriteResponse(
        IResult? result, HttpContext httpContext)
{
    if (result is null)
    {
        throw new InvalidOperationException("IResult возвращаемый делегатом не может быть null.");
    }

    await result.ExecuteAsync(httpContext);
}

Самое интересное здесь то, что "главный" RequestDelegate не вызывает await напрямую. Вместо этого он возвращает результат асинхронного метода ExecuteResultWriteResponse. В построении выражений много таких "непрямых" действий, поскольку они облегчают некоторую композитивность выражений.

Еще один момент, о котором следует помнить, если вы пишете пользовательские объекты IResult: если ваш обработчик возвращает значение типа (struct) IResult, произойдет боксинг перед передачей в вызов метода. Это, вероятно, устраняет большинство потенциальных преимуществ создания реализаций struct IResult.

Возвращаемый тип: JSON

Если вы возвращаете любой другой тип (не Task), он сериализуется в тело ответа как JSON. Например:

app.Map("/", () => new { Message = "Hello world!"});

RequestDelegate использует метод HttpResponseJsonExtensions.WriteAsJsonAsync() для сериализации типа в HttpResponse. Вы увидите, что он использует негенеративную версию метода WriteAsJsonAsync() вместо генеративной, что позволяет избежать проблем с полиморфизмом генератора исходного кода.

var result = handler.Invoke();
return WriteJsonResponse(httpContext.Response, result); // вызов хелпера для запуска ExecuteAsync

private static Task WriteJsonResponse(HttpResponse response, object? value)
{
    return HttpResponseJsonExtensions.WriteAsJsonAsync(
        response,
        value,
        value is null ? typeof(object) : value.GetType(),
        default);
}

Это охватывает все "встроенные" типы: string, IResult и "другие DTO".

Возвращаемый тип: object

При возврате объекта делегат должен проверить, является ли возвращаемый объект одним из поддерживаемых типов сериализации, таких как IResult или string, и обработать его соответствующим образом. Если это не один из этих типов, он сериализует результат в JSON. В результате происходит то, что вы ожидаете: вызывается один из трех уже показанных методов.

Таким образом, для API, который выглядит следующим образом:

app.Map("/", () => (object) "Hello world!");

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

 // вызываем обработчик и передаем результат в ExecuteAwaitedReturn
return ExecuteAwaitedReturn(handler.Invoke(), httpContext);

private static Task ExecuteAwaitedReturn(object obj, HttpContext httpContext)
{
    // Встроенные терминалы
    if (obj is IResult result)
    {
        return ExecuteResultWriteResponse(result, httpContext);
    }
    else if (obj is string stringValue)
    {
        httpContext.Response.ContentType ??= "text/plain; charset=utf-8";
        return httpContext.Response.WriteAsync(stringValue);
    }
    else
    {
        // В противном случае, мы сериализуем JSON, когда достигаем состояния терминала
        return WriteJsonResponse(httpContext.Response, obj);
    }
}

Это охватывает все основные типы, которые вы можете вернуть для обработчика, и, наконец, мы рассмотрим различные типы Task.

Возвращаемый тип: Task или ValueTask

Самые простые случаи — это когда вы возвращаете Task или ValueTask. Например:

app.Map("/", () => 
{
    return Task.CompletedTask;
});

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

return handler.Invoke();

Версия ValueTask, использующая, например, ValueTask.CompletedTask или new ValueTask(), немного сложнее, поскольку ей необходимо преобразовать ValueTask в Task:

return ExecuteValueTask(handler.Invoke());

static Task ExecuteValueTask(ValueTask task)
{
    // Если задача ValueTask уже завершена (обычный случай синхронизации)
    // Мы можем извлечь значение и вернуть
    if (task.IsCompletedSuccessfully)
    {
        task.GetAwaiter().GetResult();
        return Task.CompletedTask;
    }

    // в противном случае нам нужно ожидать его (асинхронный случай)
    // Выполнение await в отдельном методе означает, что мы не платим за стоимость
    // машины состояния async для обычного случая синхронизации
    return ExecuteAwaited(task);
    
    static async Task ExecuteAwaited(ValueTask task)
    {
        await task;
    }
}

Это касается негенеративных случаев Task , теперь мы рассмотрим генеративные случаи.

Возвращаемый тип: Task<T> или ValueTask<T>

Возврат Task<T> или ValueTask<T> — это, вероятно, одни из самых распространенных типов возврата для minimal API: вы получаете запрос, направляете его на выполнение чего-то асинхронного, например, чтения/записи из базы данных, а затем возвращаете DTO с результатами:

app.MapGet("/", async (IWidgetService service) => 
{
    var widgets = await service.GetAll();
    return widgets.Select(widget => new { widget.Id, widget.Name });
});

Как и следовало ожидать, код обработки для Task<T> и ValueTask<T> вызывает await на результате обработчика, затем вызывает тот же код сериализации, который вы уже видели в этой статье, в зависимости от того, является ли возвращаемый объект string, IResult или чем-то еще.

Я не собираюсь перечислять все эти комбинации, поэтому давайте рассмотрим пример для Task<T> выше:

var result = handler.Invoke(
    httpContext.RequestServices.GetRequiredService<IWidgetService>());

// RequestDelegateFactory считывает параметры общего типа 
// из Task<T> в результате, и вызывает общий ExecuteTaskOfT
return ExecuteTaskOfT<IEnumerable<WidgetDto>>(result, httpContext); 

private static Task ExecuteTaskOfT<T>(Task<T> task, HttpContext httpContext)
{
    // Не возвращаем null как Task, никогда!
    if (task is null)
    {
        throw new InvalidOperationException("The Task returned by the Delegate must not be null.");
    }

    // Если Task уже выполнено, получите результат
    // и немедленно вызовите WriteJsonResponse
    if (task.IsCompletedSuccessfully)
    {
        return WriteJsonResponse(httpContext.Response, task.GetAwaiter().GetResult());
    }

    // Если он еще не завершился, ожидайте вызова
    return ExecuteAwaited(task, httpContext);

    static async Task ExecuteAwaited(Task<T> task, HttpContext httpContext)
    {
        // ожидать выполнения задания, а затем ожидать вызова WriteJsonResponse
        await WriteJsonResponse(httpContext.Response, await task);
    }
}

// Этот метод WriteJsonResponse - тот же самый, который используется, когда вы
// возвращаете объект T напрямую
private static Task WriteJsonResponse(HttpResponse response, object? value)
{
    return HttpResponseJsonExtensions.WriteAsJsonAsync(
        response, value,value is null ? typeof(object) : value.GetType(), default);
}

Здесь больше кода, но нет ничего слишком сложного:

Проверьте результат обработчика, завершилась ли уже задача Task<T>?

• Если да, записываем результат с помощью WriteJsonResponse()
• Если нет, ожидаем Task, а затем записываем результат с помощью WriteJsonResponse().

Метод WriteJsonResponse -— это тот же метод, который вызывается, когда вы возвращаете T (без Task<>). Вызов await обернут в локальную функцию, как и негенерический обработчик Task, чтобы избежать выделения машины состояния async, когда Task завершилась синхронно (я предполагаю).

Для полноты я покажу еще один - возвращающий ValueTask<string>, что-то вроде:

app.MapGet("/", () => new ValueTask("Hello world!"));

Тут всё без сюрпризов:

var result = handler.Invoke();

// RequestDelegateFactory читает параметры обобщенного типа
// из Task<T> в result, и вызывает ExecuteValueTaskOfString
return ExecuteValueTaskOfString(result, httpContext); 

private static Task ExecuteValueTaskOfString(ValueTask<string?> task, HttpContext httpContext)
{
    httpContext.Response.ContentType ??= "text/plain; charset=utf-8";

    // Если ValueTask уже выполнено (общий синхронный случай)
    // получаем result и пишем его прямо в response
    if (task.IsCompletedSuccessfully)
    {
        return httpContext.Response.WriteAsync(task.GetAwaiter().GetResult()!);
    }

    // Если еще не завершилось, то ожидаем
    return ExecuteAwaited(task, httpContext);

    static async Task ExecuteAwaited(ValueTask<string> task, HttpContext httpContext)
    {
        // ждем ValueTask, и затем ждем запись response
        await httpContext.Response.WriteAsync(await task);
    }
}

На этом мы закончили рассмотрение ответов. Фактический код, созданный здесь, довольно прост и интуитивно понятен, он учитывает четыре поддерживаемых типа возврата ( void, string, IResult и T), а также их эквиваленты Task/ Task<T>/ ValueTask<T>. Кроме того, это в основном защитное программирование и оптимизация производительности.

В этой серии мы многое рассмотрели, поэтому в следующей статье мы соберем все это вместе и рассмотрим, как метод RequestDelegateFactory.Create() создает окончательный RequestDelegate для эндпоинта.

Подводя итог.

В этой статье мы рассмотрели делегат CreateTargetableRequestDelegate и сосредоточились на коде, который он производит и который обертывает вызов метода обработчика. В частности, мы рассмотрели два вызова метода:

• CreateParamCheckingResponseWritingMethodCall() обрабатывает случай, когда возникла проблема с привязкой параметров запроса, и генерирует ответ 400 Bad Request.
• AddResponseWritingToMethodCall() обрабатывает генерацию окончательного ответа путем сериализации возвращаемого значения обработчика в ответ (и вызова await на ответе Task, например).

Это были две недостающие части в генерации всего RequestDelegate для эндпоинта, поэтому в следующей статье мы соберем все вместе, рассмотрев RequestDelegateFactory.Create().

С оригиналом статьи вы можете ознакомиться по ссылке.

В предыдущей статье серии я показал, как RequestDelegateFactory.CreateArgument() генерирует деревья выражений для обработчиков minimal API. В данной статье я продолжу разбор, мы рассмотрим больше примеров кода, которые генерируются CreateArgument() для ваших обработчиков.

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

Привязка необязательных массивов строк или StringValues? к строке запроса.

В прошлой статье мы рассмотрели привязку к строке запроса как строковых, так и TryParse типов, например параметров int. Это было значительно проще для строковых типов, где у нас нет требований к преобразованию/разбору.

То же самое происходит и при привязке параметров массива: привязка string[] или StringValues значительно проще, чем привязка массивов TryParse типов, таких как int[].

StringValues — это структура, доступная только для чтения, которая эффективно представляет 0/null, одну или много строк. Она может быть приведена к строке и из строки, и из массива строк.

Например, рассмотрим следующий эндпоинт, который связывает массив q со значениями строк запроса. Например, для запроса типа /?q=Mark&q=John массив будет иметь два значения, "Mark" и "John":

app.MapGet("/", (string[]? q) => {});

По сути, как и в предыдущем сообщении, выражение связывания может просто взять значения из строки запроса/значений маршрута/заголовков и передать их обработчику напрямую. Свойства Query, Headers и т. д. напрямую преобразуются в string[], так что много работы делать не нужно:

Task Invoke(HttpContext httpContext)
{
    handler.Invoke(
        httpContext.Request.Query["q"] != null 
            ? httpContext.Request.Query["q"]
            : (string[]) null); 

    return Task.CompletedTask;
}

Этот сгенерированный код по сути идентичен тому, когда вы связываете строковый параметр; его можно использовать в обоих случаях, поскольку значение StringValues, возвращаемое из Query["q"], напрямую преобразуется как в string, так и в string[]!

Привязка требуемых массивов строк или StringValues.

Следующий логический шаг - сделать параметр обязательным, а не опциональным:

app.MapGet("/", (string[] q) => {});

В этом случае, теоретически, привязка Expression остается простой, но теперь RequestDelegate должен проверить, что в строке запроса точно есть значение, которое совпадает. Если нет, эндпоинт должен вернуть ответ 400 BadRequest.

Task Invoke(HttpContext httpContext)
{
    bool wasParamCheckFailure = false; // Добавлено из RequestDelegateFactory.Create()
    string[] q_local;

    q_local = httpContext.Request.Query["q"]
    if (q_local == null) // если значения нет
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "string[]", "q", "query");
    }

    if(wasParamCheckFailure) // Добавлено из RequestDelegateFactory.Create()
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    handler.Invoke(q_local); 

    return Task.CompletedTask;
}

Кроме того, в поведении параметров string[] и string[]? есть несоответствие по сравнению с другими типами требуемых и обнуляемых параметров. Теоретически, если вы не предоставите значение для строки запроса, вы можете ожидать, что параметр string[]? будет иметь значение null (как было предложено в предыдущем разделе), а параметр string[]? вернет ошибку 400 Bad Request, как показано в приведенном выше коде.

Однако это не так. Если вы вызовете эти API и не предоставите ожидаемую строку запроса, параметр никогда не будет равен null и не вернет ошибку 400 Bad Request - вместо этого вы получите пустой массив. В настоящее время это противоречит документации (и поведению StringValues, которые возвращают 400), поэтому я открыл issue по этому поводу, где описал причины различий. Консенсус по этому вопросу, похоже, таков: "По замыслу, исправлять не будем".

Все это выглядит довольно похоже на код, который вы видели в предыдущем посте для привязки к строке, это не удивительно, учитывая, что StringValues могут быть автоматически приведены как к строке, так и к string[]. Сложнее обстоит дело, если у нас есть массив типов, где необходимо вызвать TryParse.

Привязка int[] к строке запроса.

В следующем примере мы рассмотрим привязку параметра int?[] к строке запроса:

app.MapGet("/", (int?[] q) => {});

В этом случае нам нужно сначала извлечь string[] из строки запроса во временную переменную ( tempStringArray ), проверить, является ли каждое значение null, и, если нет, каждое из значений попытаться спарсить (TryParse) в int. Это значительно усложняет код!

Task Invoke(HttpContext httpContext)
{
    string tempSourceString; // Добавлено из RequestDelegateFactory.Create()
    bool wasParamCheckFailure = false; // Добавлено из RequestDelegateFactory.Create()
    int?[] q_local;
    
    // Прасим запрос во временный string[]
    string[] tempStringArray = httpContext.Request.Query["q"];

    if (tempStringArray != null)
    {
        // Инициализируем переменную, которая зафиксирует финальное значение
        q_local = new int[tempStringArray.Length];

        int index = 0;
        while(true)
        {
            if(index < tempStringArray.Length)
            {
                // Проходимся по каждой строке массива
                tempSourceString = tempStringArray[index];

                // если строка пустая, например в URL /q=&q=
                // значит оставляем в дефолтном значении
                if(!string.IsNullOrEmpty(tempSourceString))
                {
                    // Пробуем распарсить значение
                    if (int.TryParse(tempSourceString, out var parsedValue))
                    {
                        // Успешно распарсили, кастуем к int? и
                        q_local[i] = (int?)parsedValue;
                    }
                    else
                    {
                        // неудачный парсинг
                        wasParamCheckFailure = true;
                        Log.ParameterBindingFailed(httpContext, "Nullable<int>[]", "query", tempSourceString, true);
                    }
                }
            }
            else
            {
                break;
            }
    
            index++
        }
    }
    else
    {
        // 👇 На сколько я могу судить, этот код на самом деле не может быть выполнен из-за 
        // https://github.com/dotnet/aspnetcore/issues/45956
        wasParamCheckFailure = true;
        Log.ParameterBindingFailed(httpContext, "Int32[]", "q", "query", tempSourceString, true);
    }

    if(wasParamCheckFailure) // Получено из RequestDelegateFactory.Create()
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    handler.Invoke(q_local); 

    return Task.CompletedTask;
}

Возможно, вы подумаете, что этот код выглядит немного странно: цикл while со вложенным if - почему бы просто не использовать цикл for или foreach. Мое самое простое предположение: этот код легче писать, когда вы все делаете в виде выражений! В нем также много дублирующихся блоков Expression между различными типами параметров, поэтому я не склонен критиковать его. Если вы хотите действительно понять, посмотрите на 250 строк приседаний с Expression в BindParameterFromValue()!

Привязка обязательных сервисов из DI.

После этой сложности рассмотрим более простые примеры: привязку к сервисам в контейнере DI. Например, возьмем следующий пример программы:

var builder = WebApplication.CreateBuilder();
builder.Services.AddSingleton<MyService>();

var app = builder.Build();
app.MapGet("/", (MyService service) => {});
app.Run()

class MyService {}

Эндпоинт minimal API автоматически определяет, что тип MyService доступен в DI, и привязывает параметр обработчика к сервису с помощью GetRequiredService().

async Task Invoke(HttpContext httpContext)
{
    handler.Invoke(
        httpContext.RequestServices.GetRequiredService<MyService>()); 

    return Task.CompletedTask;
}

Привязка опциональных сервисов из DI.

"Необязательные" сервисы, когда сервис может быть зарегистрирован в DI, а может и не быть, вообще кажутся мне плохим шаблоном, но они поддерживаются непосредственно minimal API. Обычно вам нужно использовать атрибут [FromServices], чтобы minimal API поняли, что это DI-сервис, и пометили параметр как необязательный с помощью ?

var builder = WebApplication.CreateBuilder();
var app = builder.Build();
app.MapGet("/", ([FromServices] MyService? service) => {});
app.Run()

Результирующее выражение очень похоже на случай с "обязательным" сервисом. Единственное отличие - необязательные сервисы используют GetService вместо GetRequiredService.

async Task Invoke(HttpContext httpContext)
{
    handler.Invoke(
        httpContext.RequestServices.GetService<IService>()); 

    return Task.CompletedTask;
}

Привязка к необязательным файлам форм с помощью IFormFileCollection и IFormFile.

Далее мы рассмотрим привязку IFormFile и IFormFileCollection. Возможно, вы помните из предыдущей статьи, что это два "известных" типа, к которым minimal API могут привязываться напрямую. Они примерно одинаковы по способу привязки: IFormFileCollection привязывается ко всем файлам формы, а IFormFile привязывается к одному файлу, названному "file" в следующем примере:

app.MapGet("/", (IFormFile? file) => {});

Файлы формы открываются непосредственно в ASP.NET Core через свойство HttpRequest.Form.Files, поэтому Expression очень похож на тот, когда мы привязывали строку или свойство StringValues к строке запроса:

Task Invoke(HttpContext httpContext)
{
    handler.Invoke(
        httpContext.Request.Form.Files["file"] != null 
            ? httpContext.Request.Form.Files["file"]
            : (IFormFile) null); 

    return Task.CompletedTask;
}

Что не показано в приведенном выше делегате, так это код, который фактически считывает форму из тела, как первый шаг конечного RequestDelegate. Процесс выполнения этого действия немного запутан, но, по сути, он вызывает следующий метод TryReadFormAsync, и если он может выполниться, то сразу же возвращается.

static async Task<(object? FormValue, bool Successful)> TryReadFormAsync(
    HttpContext httpContext,
    string parameterTypeName,
    string parameterName,
    bool throwOnBadRequest)
{
    object? formValue = null;
    var feature = httpContext.Features.Get<IHttpRequestBodyDetectionFeature>();

    if (feature?.CanHaveBody == true)
    {
        if (!httpContext.Request.HasFormContentType)
        {
            Log.UnexpectedNonFormContentType(httpContext, httpContext.Request.ContentType, throwOnBadRequest);
            httpContext.Response.StatusCode = StatusCodes.Status415UnsupportedMediaType;
            return (null, false);
        }

        try
        {
            formValue = await httpContext.Request.ReadFormAsync();
        }
        catch (IOException ex)
        {
            Log.RequestBodyIOException(httpContext, ex);
            return (null, false);
        }
        catch (InvalidDataException ex)
        {
            Log.InvalidFormRequestBody(httpContext, parameterTypeName, parameterName, ex, throwOnBadRequest);
            httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
            return (null, false);
        }
    }

    return (formValue, true);
}

Я не показал, как вызывается этот метод, поскольку все становится немного сложнее с компиляцией Expression и вложенными делегатами, но вы увидите похожий подход, когда мы перейдем к привязке body.

Привязка к обязательному файлу формы с помощью IFormFileCollection и IFormFile.

Для полноты картины мы также рассмотрим привязку к требуемому IFormFile или IFormFileCollection, где нам нужно проверить, что файл(ы) действительно отправлен(ы). В этом примере я использовал IFormFileCollection для разнообразия.

app.MapGet("/", (IFormFileCollection files) => {});

В результате получается шаблон, который вы уже много раз видели: мы привязываем свойство и проверяем его на null. Если оно null, мы возвращаем 400, если нет, то передаем его в качестве аргумента обработчику.

Task Invoke(HttpContext httpContext)
{
    bool wasParamCheckFailure = false;
    IFormFileCollection files;

    files = httpContext.Request.Form.Files
    if (files == null)
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "IFormFileCollection", "files", "body");
    }

    if(wasParamCheckFailure) 
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    handler.Invoke(files); 

    return Task.CompletedTask;
}

TryReadFormAsync() вызывается в начале RequestDelegate, как показано в предыдущем примере.

Ну вот и все, теперь мы закончили с "легкими" выражениями связывания. Вернемся к более сложным вещам...

Привязка BindAsync типов.

До этого момента я показывал примеры "окончательного" RequestDelegate, созданного RequestDelegateFactory.Create(), используя определения параметра Expression, созданные в методе CreateArgument(). Но я несколько лукавил: по техническим причинам RequestDelegate часто не так "чист", как показанные мной примеры.

По большей части это не имеет значения, поэтому я и выбрал такой подход. Но в оставшейся части этой статьи я собираюсь немного приблизиться к реальности.

Мы начнем с типов BindAsync. Как вы, возможно, помните из предыдущей статьи, типы могут полностью контролировать свое связывание, реализуя один из следующих статических методов:

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

Представим, что у нас есть тип MyType, у которого есть метод BindAsync, который мы используем в minimal API.

app.MapGet("/", (MyType t) => {});

Чтобы сгенерировать выражение параметра для параметра t, CreateArgument() вызывает метод BindParameterFromBindAsync(). Это создает Func<HttpContext, ValueTask<object?>>, который вызывает метод BindAsync нашего типа, примерно так:

// Тут всё очень примерно, за большими разъяснениями идите в 
// https://github.com/dotnet/aspnetcore/blob/v7.0.1/src/Shared/ParameterBindingMethodCache.cs#L195
MethodInfo bindAsyncMethod = typeof(MyType).GetMethod("BindAsync");

var bindAsyncDelegate = Expression.Lambda<Func<HttpContext, ValueTask<object?>>>(
    bindAsyncMethod, HttpContextExpr).Compile();

Конечным результатом является Func<>, который при вызове создает экземпляр MyType с параметром HttpContext (или может вызвать исключение).

Метод CreateArgument() добавляет bindAsyncDelegate в коллекцию RequestDelegateFactoryContext.ParameterBinders. RequestDelegateFactory.Create() затем использует этот список для связывания всех BindAsync-овых параметров перед вызовом "тела" RequestDelegate.

Большая часть следующего RequestDelegate создается в методе Create(), а не CreateArgument(), но я включил его целиком, чтобы вы могли увидеть, как все это сочетается. Я, конечно, прокомментировал код, но здесь есть несколько интересных моментов:

• здесь представлена немного запутанная смесь кода, созданного с помощью Expression и компиляции, и простых закрытий Func<>. Код, который я показываю ниже, является лучшей попыткой показать результат после компиляции Expression и комбинирования с различными Func<>, но он не является четким тет-а-тет с реальным кодом.
• Внутренний Func<> (который я назвал generateResult) использует захваченные значения закрытия. В предыдущих случаях я не обращал на это внимания, но в данном случае очевидно, что коллекция ParameterBindings захватывается напрямую.
• целевой параметр во внутреннем продолжении — это экземпляр, на котором определен метод обработчика. Для обработчиков лямбда-эндпоинтов это сгенерированный класс закрытия для делегата, но для статических обработчиков это может быть и null.

Поскольку большая часть этого кода создается RequestDelegateFactory.Create(), я выделил те части, которые создаются CreateArgument специально.

// Они создаются вне метода RequestDelegate и перехватываются 
// закрытием RequeustDelegate Func<>
var binders = factoryContext.ParameterBinders.ToArray();
// Длина равна количеству параметров, реализующих BindAsync
var count = binders.Length;

async Task Invoke(HttpContext httpContext)
{
    // целевой объект, передаваемый здесь, является объектом "обработчика", если таковой имеется
    var Task Invoke(object? target, HttpContext httpContext)
    {
        // В этом массиве хранится массив значений параметров
        // которые привязаны с помощью BindAsync к HttpContext
        var boundValues = new object?[count];
        for (var i = 0; i < count; i++)
        {
            // Вызов Func<> для каждого параметра и запись результата
            // Для этого примера создается один объект MyType
            boundValues[i] = await binders[i](httpContext);
        }

        // определяем продолжение, которое вызывается после связывания
        var generateResult = (object? target, HttpContext httpContext, object?[] boundValues) =>
        {
            bool wasParamCheckFailure = false;

            // Эта проверка выдается только в том случае, если параметр является обязательным
            // и является одной из немногих частей, выдаваемых CreateArgument()
            if(boundValues[0] == null)
            {
                wasParamCheckFailure = true;
                Log.RequiredParameterNotProvided(httpContext, "MyType", "t", "MyType.BindAsync(httpContext)", true);
            }

            if(wasParamCheckFailure)
            {
                httpContext.Response.StatusCode = 400;
                return Task.CompletedTask;
            }

            // CreateArgument() выдает выражение, которое приводит 
            // связанное значение к типу параметра, MyType
            target.handler.Invoke((MyType)boundValues[0]); 

            return Task.CompletedTask;
        };

        // вызываем Func<>, передавая значения из внешней функции
        generateResult(target, httpContext, boundValues);
    }

    // Вызовите внутренний метод, передав экземпляр лямбда-закрытия в качестве цели
    return Invoke(target: Program.<>c, httpContext);
}

Если вы запутались, я вас не виню. В приведенном примере много ненужных "оберток" во внутренних переменных Func, что немного усложняет процесс. В предыдущих примерах я "сгладил" эти вызовы Func<>, но оставил их здесь для полноты картины. Я все еще не решил, жалею ли я об этом выборе 😅.

Обратите внимание, что реальный RequestDelegate, сгенерированный RequestDelegateFactory, не имеет переменных Func<>, таких как generateResult и т.д.. Выражения компилируются в Func<> и вызываются непосредственно при построении секций. Приведенное выше — это моя попытка представить , не зацикливаясь на деталях слишком сильно!

Привязка тела запроса к типу.

В приведенном выше примере я позволил показать все уродства Func<>; в следующей связке я покажу некоторые из уродств, где это необходимо, но замажу все остальное. Вы увидите, что я имею в виду...

Представим, что у нас есть тот же API, но на этот раз тип MyType не реализует BindAsync:

app.MapGet("/", (MyType t) => {});

По умолчанию этот API связывает параметр t с телом запроса. Это первое, что происходит в создаваемом RequestDelegate, который вызывает вспомогательную функцию TryReadBodyAsync. Как и раньше, почти все это создается RequestDelegateFactory.Create(), а не CreateArgument(), но я включил это сюда для полноты.

async Task Invoke(HttpContext httpContext)
{
    // пытаемся прочитать тело запроса
    var (bodyValue, successful) = await TryReadBodyAsync(
        httpContext,
        typeof(MyType),
        "MyType",
        "t",
        false, // factoryContext.AllowEmptyRequestBody
        true); // factoryContext.ThrowOnBadRequest

    // если что то пошло не так, выходим
    if (!successful)
    {
        return;
    }

    // определяем Func<> которая вызывает обработчик
    var generateResponse = (object? target, HttpContext httpContext, object? bodyValue) =>
    {
        bool wasParamCheckFailure = false;
        
        if (bodyValue == null) // это состояние создано в CreateArgument()
        {
            wasParamCheckFailure = true;
            Log.ImplicitBodyNotProvided(httpContext, "MyType", true);
        }

        handler.Invoke((MyType)bodyValue);  // кастуем созданное в CreateArgument()

        return Task.CompletedTask;
    };

    // Вызвать продолжение, передав null в качестве цели
    await generateResponse(target: null, httpContext, bodyValue);
}

// Эта вспомогательная функция считывает тело запроса и создает 
// экземпляр объекта с использованием System.Text.Json
static async Task<(object? FormValue, bool Successful)> TryReadBodyAsync(
    HttpContext httpContext,
    Type bodyType,
    string parameterTypeName,
    string parameterName,
    bool allowEmptyRequestBody,
    bool throwOnBadRequest)
{
    object? defaultBodyValue = null;

    if (allowEmptyRequestBody && bodyType.IsValueType)
    {
        defaultBodyValue = CreateValueType(bodyType);
    }

    var bodyValue = defaultBodyValue;
    var feature = httpContext.Features.Get<IHttpRequestBodyDetectionFeature>();

    if (feature?.CanHaveBody == true)
    {
        if (!httpContext.Request.HasJsonContentType())
        {
            Log.UnexpectedJsonContentType(httpContext, httpContext.Request.ContentType, throwOnBadRequest);
            httpContext.Response.StatusCode = StatusCodes.Status415UnsupportedMediaType;
            return (null, false);
        }
        try
        {
            bodyValue = await httpContext.Request.ReadFromJsonAsync(bodyType);
        }
        catch (IOException ex)
        {
            Log.RequestBodyIOException(httpContext, ex);
            return (null, false);
        }
        catch (JsonException ex)
        {
            Log.InvalidJsonRequestBody(httpContext, parameterTypeName, parameterName, ex, throwOnBadRequest);
            httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
            return (null, false);
        }
    }

    return (bodyValue, true);

Одна вещь, не показанная в приведенном выше коде, заключается в том, что CreateArgument() добавляет дополнительные метаданные [Accepts] в коллекцию метаданных как часть вызова InferMetadata, указывая, что конечная точка ожидает тело запроса JSON MyType.

Этот шаблон вложенных вызовов Func<> является тем, как вызывается метод TryReadFormAsync() при связывании IFormFile. Схема чтения тела идентична, отличается только обработка тела.

Мы закончили. Можно было бы рассмотреть дополнительные варианты: для каждого типа параметров сравнить обязательные и необязательные значения, а также значения по умолчанию, но мы уже рассмотрели репрезентативные примеры, так что пользы от этого немного.

Основные выводы из этой статьи заключаются в том, что CreateArgument() иногда выполняет много работы. Выражение для чтения параметра int[], например, является значительным. В отличие от этого, привязка к DI-сервису — это тривиальное выражение!

В следующей статье мы рассмотрим другую часть генерации выражений RequestDelegate: методы, которые управляют тем, как обрабатывать возвращаемое значение эндпоинта обработчика. До сих пор я ограничивал примеры возвратом void, но вы можете возвращать что угодно из ваших API.

Подводя итог.

Метод RequestDelegateFactory.CreateArgument() отвечает за создание деревьев выражений для привязки аргументов обработчика API к HttpContext. RequestDelegateFactory.Create() использует эти деревья выражений для создания конечного RequestDelegate, который ASP.NET Core выполняет для обработки запроса.

В предыдущей и этой статьях я показал примеры некоторых деревьев выражений, создаваемых для определенных типов параметров. В этом посте я начал с демонстрации привязки массивов к строке запроса, а затем показал привязку DI-сервисов и файлов IFormFile.

Далее мы рассмотрели более сложные примеры привязки параметров с помощью BindAsync, а также параметры, которые привязываются к телу запроса. Результирующий RequestDelegate, созданный в обоих этих случаях, требует много кода, созданного вне CreateArgument(), но я включил его для полноты картины.

Код примера показывает, как генерируется и вызывается несколько вложенных Func<>. Это ближе к "реальному" поведению скомпилированного RequestDelegate, но это делает чтение более запутанным!

В следующем посте мы рассмотрим другой раздел сгенерированного RequestDelegate: обработку типа возврата minimal API и запись ответа.

Оригинал данной статьи вы можете прочитать по ссылке.

Эта четвертая статья из серии "За кулисами Minimal API" Эндрю Лока. В предыдущей статье этой серии мы рассмотрели метод CreateArgument() и увидели, что этот метод отвечает за определение того, как работает привязка модели в minimal API, выбирая источник для привязки и генерируя выражение для неё.

Мы пропустили генерацию Expression в предыдущей статье, в этой мы погрузимся в неё и посмотрим на (эффективный) код, который генерирует CreateArgument().

Краткий обзор RequestDelegateFactory.CreateArgument().

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

• RouteEndpointDataSource - хранит "сырую" информацию о каждом эндпоинте ( delegate обработчика, RoutePattern и т. д.), инициирует их сборку в RequestDelegate и сопоставление метаданных.
• RequestDelegateFactory.InferMetadata()- отвечает за чтение метаданных об аргументах обработчика эндпоинта и возвращаемом значении, а также за построение Expression для каждого аргумента, который впоследствии может быть использован для построения RequestDelegate.
• RequestDelegateFactory.Create()- отвечает за создание RequestDelegate, который ASP.NET Core вызывает путем построения и компиляции Expression из обработчика эндпоинта.

До сих пор мы фокусировались на функции InferMetadata(), а в этой статье мы рассмотрим метод, который она вызывает: CreateArgument(). CreateArgument() создает выражение, которое может создать параметр обработчика, если у вас есть доступ к переменной HttpContext httpContext.

Для примера, давайте представим, что у вас есть метод обработчика, выглядящий таким образом:

app.MapGet("/{id}", (string id, HttpRequest request, ISomeService service) => {});

Чтобы выполнить обработчик, ASP.NET Core в итоге должен сгенерировать выражение, которое выглядит примерно следующим образом: Я выделил код, который  генерирует CreateArgument() с помощью 👈:

Task Invoke(HttpContext httpContext)
{
    // Разбор и привязка к модели параметра `id` из RouteValues
    bool wasParamCheckFailure = false;
    
    string id_local = httpContext.Request.RouteValues["id"];  // 👈
    if (id_local == null)                                     // 👈
    {                                                         // 👈
        wasParamCheckFailure = true;                          // 👈
        Log.RequiredParameterNotProvided(httpContext, "string", "id", "route");  // 👈
    }                                                         // 👈

    if(wasParamCheckFailure)
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }
     
    // handler — это оригинальный метод лямбда-обработчика.
    // Параметр HttpRequest был автоматически создан из аргумента HttpContext.
    // а параметр ISomeService получен из контейнера DI
    string text = handler.Invoke(
        id_local,                                                      // 👈
        httpContext.Request,                                           // 👈
        httpContext.RequestServices.GetRequiredService<ISomeService>() // 👈
    ); 

    // Возвращаемое значение записывается в ответ, как и ожидалось
    httpContext.Response.ContentType ??= "text/plain; charset=utf-8";
    return httpContext.Response.WriteAsync(text);
}

Большая часть этого кода (хотя и не весь) генерируется CreateArgument() как дерево выражений. В частности, он генерирует код, который создает аргументы обработчика на основе окружающей переменной httpContext, и проверяет, что значения являются действительными (не null).

В этой статье мы рассмотрим различные формы, которые может принимать этот генерируемый код, в зависимости от источника привязки (например, строка запроса, тело запроса), а также от типа привязываемого параметра и возможности его обнуления.

Деревья выражений.

Фундаментальная концепция, используемая RequestDelegateFactory, — это деревья выражений и их компиляция в исполняемый делегат.

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

Метод CreateArgument() потенциально создает несколько деревьев выражений для каждого параметра:

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

Все это станет более очевидным, когда мы рассмотрим некоторые примеры, но я хотел выделить их, чтобы указать на то, что nullability является большой частью генерируемых деревьев Expression и вносит свой вклад в то, является ли параметр действительным или нет.

Например эндпоинт :

app.MapGet("/", (string query, int id) => {})

в котором параметры query и id не допускают null в значении. Сгенерированное выражение будет отличаться от выражения для эндпоинта в котором параметры query и id допускают null в значении или имеют значение по умолчанию:

app.MapGet("/", (string? query, int id = -1) => {})

В первом случае сгенерированное выражение должно отслеживать, были ли предоставлены ожидаемые параметры в строке запроса. Парсинг запроса в параметр int id должен быть проверен для обоих обработчиков. Как вы можете себе представить, все это значительно усложняет генерируемые выражения!

Генерация выражений для известных типов.

Как вы видели в предыдущей статье, CreateArgument() сначала проверяет наличие атрибутов [From*], применяемых к параметрам, чтобы определить источник привязки, но я пока пропущу этот раздел, чтобы рассмотреть привязку параметров к известным типам.

Как я описывал ранее, вы можете инжектировать такие типы, как HttpContext и CancellationToken, и они автоматически привязываются к свойствам HttpContext, инжектированного в конечный RequestDelegate. Поскольку эти свойства доступны напрямую, это самые простые выражения для генерации (поэтому мы с них и начинаем)!

CreateArgument() содержит целую кучу статических кэшированных выражений, представляющих эти хорошо известные типы. В качестве примера мы рассмотрим, как определяются эти выражения и как выглядит сгенерированный код для аргумента:

static readonly ParameterExpression HttpContextExpr = 
    Expression.Parameter(typeof(HttpContext), "httpContext");

static readonly MemberExpression HttpRequestExpr = 
    Expression.Property(HttpContextExpr, typeof(HttpContext).GetProperty(nameof(HttpContext.Request))!);

Здесь у нас есть два типа выражений. Первое - ParameterExpression, оно определяет тип и имя параметра, передаваемого в метод. Второе — это MemberExpression, которое описывает доступ к свойству. Поскольку HttpContextExpr передается в вызов Expression.Property, это эквивалентно коду, который выглядит следующим образом:

httpContext.Request

Не очень похоже, правда? 😄 Но это все, что нужно сгенерировать CreateArgument() для встроенных типов; это выражение точно определяет, как создать аргумент, который передается обработчику с параметром HttpRequest. То же самое относится и к большинству других простых "известных" типов. Например, рассмотрим этот обработчик, который использует только встроенные типы:

app.MapGet("/", (HttpContext c, HttpRequest r, CancellationToken c, Stream s) => {})

CreateArgument() генерирует одно простое выражение для каждого аргумента. Окончательный RequestDelegate для этого обработчика будет выглядеть примерно следующим образом (где handler относится к методу лямбда в minimal API):

Task Invoke(HttpContext httpContext)
{
    handler.Invoke(
        httpContext,
        httpContext.Request,
        httpContext.RequestAborted,
        httpContext.Body); 

    return Task.CompletedTask;
}

Довольно аккуратно!

Конечно, не все может быть так просто. Теперь, когда мы рассмотрели простые случаи, давайте рассмотрим кое-что посложнее: генерацию выражений для привязки к значениям маршрута, строке запроса и заголовкам.

Генерация выражений для привязки к значениям маршрута, строке запроса и заголовкам.

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

• Все они открыты для HttpRequest: HttpRequest.RouteValues, HttpRequest.Query и HttpRequest.Headers.
• Все они представлены в виде коллекции элементов, доступ к которым осуществляется с помощью индексатора ( Item), принимающего ключ в string .
• Каждое из индексированных значений может возвращать объект, представляющий несколько значений, например, объект StringValues.

Из-за этого сходства код генерации выражения в CreateArgument() во многом одинаков для каждого из них. По этой причине мы ограничимся рассмотрением кода, сгенерированного только для одного из них - строки запроса. Кроме того, мы не будем рассматривать код, создающий деревья выражений, поскольку, честно говоря, он слишком запутан.

Вместо этого мы применим другой подход: Я покажу пример обработчика, и мы посмотрим на эффективный код, сгенерированный для него. Затем мы немного подправим его (например, сделаем его nullable или изменим тип параметра) и посмотрим, как изменится код. Это позволит нам изучить все различные выражения, не увязая в попытках проследить логику (но вы, конечно, можете прочитать исходный текст, если хотите)!

Привязка необязательного строкового параметра к значению запроса.

Мы начнем с простого обработчика, который по желанию привязывается к значению строки запроса:

app.MapGet("/", (string? q) => {});

Если вы обратитесь к схеме из моей предыдущей статьи, то увидите, что CreateArgument() решит привязать этот аргумент к значению строки запроса (а не к значению маршрута, поскольку таковых не существует). Поскольку параметр является необязательным (поэтому не требует проверки на null) и представляет собой строку (поэтому не требует преобразования), результирующий RequestDelegate выглядит примерно так:

Task Invoke(HttpContext httpContext)
{
    handler.Invoke(
        httpContext.Request.Query["q"] != null 
            ? httpContext.Request.Query["q"]
            : (string) null); 

    return Task.CompletedTask;
}

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

Привязка необязательного строкового параметра со значением по умолчанию.

Для следующего сценария мы обновим параметр обработчика, чтобы он больше не был nullable, и вместо этого дадим ему значение по умолчанию. Лямбды не поддерживают значения по умолчанию в параметрах, поэтому для данного примера мы преобразуем их в локальную функцию, но это не оказывает никакого другого влияния на генерируемое выражение

app.MapGet("/", Handler);
void Handler(string q = "N/A") { }

Как же это влияет на сгенерированный код? Как вы можете видеть ниже, он очень похож! Вместо возврата к null мы возвращаемся к значению по умолчанию, как и следовало ожидать:

Task Invoke(HttpContext httpContext)
{
    handler.Invoke(
        httpContext.Request.Query["q"] != null 
            ? httpContext.Request.Query["q"]
            : (string) "N/A"); // 👈 Использование значения по умолчанию вместо `null`.

    return Task.CompletedTask;
}

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

Привязка обязательного строкового параметра.

Теперь мы вернемся к исходному обработчику, но преобразуем его в параметр string вместо string? :

app.MapGet("/", (string q) => {});

Поскольку параметр теперь является обязательным, мы должны убедиться, что он действительно предоставлен, и если нет, записать ошибку в журнал. Для этого CreateArgument() генерирует три выражения, каждое из которых показано ниже.

Во-первых, мы определяем выражение локальной переменной, которая имеет тип параметра ( string) и названа в соответствии с параметром:

string q_local;

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

q_local = httpContext.Request.RouteValues["q"]
if (q_local == null)
{
     wasParamCheckFailure = true;
     Log.RequiredParameterNotProvided(httpContext, "string", "q", "query");
}

Исключение wasParamCheckFailure создается позже, в методе RequestDelegateFactory.Create(), а Log здесь ссылается на статический вспомогательный метод самой RequestDelegateFactory.

Последнее выражение -— это то, что передается в функцию-обработчик, которая в данном примере просто q_local .

Если собрать все это вместе и объединить с дополнительными деталями, добавленными RequestDelegateFactory.Create(), получится RequestDelegate, который будет выглядеть примерно так:

Task Invoke(HttpContext httpContext)
{
    bool wasParamCheckFailure = false; // Добавлено с помощью RequestDelegateFactory.Create()
    string q_local;

    q_local = httpContext.Request.RouteValues["q"]
    if (q_local == null)
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "string", "q", "query");
    }

    if(wasParamCheckFailure) // Добавлено с помощью RequestDelegateFactory.Create()
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    handler.Invoke(q_local); 

    return Task.CompletedTask;
}

Теперь все определенно становится немного сложнее! Давайте добавим еще один уровень сложности и рассмотрим привязку к чему-либо, кроме строки, где нам нужно вызвать TryParse для создания значения.

Привязка необязательного параметра int к значению запроса.

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

app.MapGet("/", (int? q) => {});

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

• Работа с nullable типами. Nullable типы — странные, поверьте мне 😅
• Парсинг string в int и обработка ошибок
• Временные переменные для хранения промежуточных значений

Если собрать все это вместе и объединить с дополнительной логикой, которую добавляет RequestDelegateFactory.Create(), то в итоге получится RequestDelegate, который выглядит примерно так:

Task Invoke(HttpContext httpContext)
{
    string tempSourceString; // Добавляется из RequestDelegateFactory.Create()
    bool wasParamCheckFailure = false; // Added by RequestDelegateFactory.Create()
    int? q_local;

    tempSourceString = httpContext.Request.RouteValues["q"]
    if (tempSourceString != null)
    {
        if (int.TryParse(tempSourceString, out int parsedValue))
        {
            q_local = (int?)parsedValue;
        }
        else
        {
            wasParamCheckFailure = true;
            Log.ParameterBindingFailed(httpContext, "Int32", "q", tempSourceString)
        }
    }

    if(wasParamCheckFailure) // Добавляется из RequestDelegateFactory.Create()
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    handler.Invoke(q_local); 

    return Task.CompletedTask;
}

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

Привязка необязательного параметра int со значением по умолчанию.

Как и в случае со строкой, мы перейдем к использованию ненулевого параметра со значением по умолчанию, используя локальную функцию:

app.MapGet("/", Handler);
void Handler(int q = 42) { }

Созданный RequestDelegate в этом случае очень похож на предыдущий пример. Есть три основных отличия:

• Как и следовало ожидать, переменные имеют значение int, а не int?
• Мы можем напрямую присвоить q_local в вызове TryParse, потому что теперь это int, а не int?. Это означает, что мы также можем инвертировать условие if, немного упростив ситуацию
• Мы добавляем предложение else для случая, когда tempSourceString равен null, и присваиваем q_local значение по умолчанию.

RequestDelegate выглядит следующим образом:

Task Invoke(HttpContext httpContext)
{
    string tempSourceString; // Добавляется из RequestDelegateFactory.Create()
    bool wasParamCheckFailure = false; // Добавляется из  RequestDelegateFactory.Create()
    int q_local; // 👈 int вместо int?

    tempSourceString = httpContext.Request.RouteValues["q"]
    if (tempSourceString != null)
    {
        // Здесь мы можем напрямую присвоить q_local 👇
        if (!int.TryParse(tempSourceString, out q_local)) // 👈 что означает, что мы можем инвертировать это предложение if
        {
            wasParamCheckFailure = true;
            Log.ParameterBindingFailed(httpContext, "Int32", "q", tempSourceString)
        }
    }
    else
    {
        q_local = 42; // 👈 Присвоить значение по умолчанию, если значение отсутствует
    }

    if(wasParamCheckFailure) // Added by RequestDelegateFactory.Create()
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    handler.Invoke(q_local); 

    return Task.CompletedTask;
}

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

Привязка обязательного параметра int

В нашем примере последнего обработчика у нас есть необходимый параметр int:

app.MapGet("/", (int q) => {});

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

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

В результате RequestDelegate будет выглядеть так:

Task Invoke(HttpContext httpContext)
{
    string tempSourceString; // Добавлено из RequestDelegateFactory.Create()
    bool wasParamCheckFailure = false; // Добавлено из RequestDelegateFactory.Create()
    int q_local;

    tempSourceString = httpContext.Request.RouteValues["q"]
    
    if (tempSourceString == null) // 👈 Дополнительная проверка
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "Int32", "q");
    }
    
    if (tempSourceString != null)
    {
        if (!int.TryParse(tempSourceString, out q_local))
        {
            wasParamCheckFailure = true;
            Log.ParameterBindingFailed(httpContext, "Int32", "q", tempSourceString)
        }
    } // 👈 Тут нет else блока

    if(wasParamCheckFailure) // Добавлено из RequestDelegateFactory.Create()
    {
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }

    handler.Invoke(q_local); 

    return Task.CompletedTask;
}

На данный момент мы рассмотрели сгенерированные выражения для:

• Известных типов, таких как HttpContext и HttpRequest
• Привязки обязательных и необязательных string значений к значениям маршрута, строке запроса и заголовкам.
• Привязки обязательных и необязательных значений TryParse() (на примере, int) к значениям маршрута, строке запроса и заголовкам.

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

Подводя итог.

Метод RequestDelegateFactory.CreateArgument() отвечает за создание деревьев выражений для привязки аргументов обработчика minimal API к HttpContext. RequestDelegateFactory.Create() использует эти деревья выражений для создания конечного RequestDelegate, который ASP.NET Core выполняет для обработки запроса.

В этой заметке я показал примеры деревьев выражений, созданных для определенных типов параметров. Я начал с того, что показал, как известные типы, такие как HttpRequest и CancellationToken, генерируют выражения, связывающие аргументы со свойствами HttpContext. Это самые простые случаи, поскольку они не требуют никакой проверки.

Далее мы рассмотрели привязку строковых параметров к строке запроса, значениям маршрута и заголовка. Выражения для необязательных параметров (string?) и параметров со значениями по умолчанию были относительно простыми, но для обязательных значений (string) мы увидели, что требуется некоторая валидация.

Гораздо больше проверки требуется при использовании типов параметров, которые должны быть разобраны из строки, например значения int. Независимо от того, используете ли вы необязательные или требуемые значения, они требуют определенной степени проверки, что приводит к большему количеству сгенерированного кода в выражении. В следующем посте мы продолжим рассмотрение выражений, генерируемых в CreateArgument() для других типов параметров.

С оригиналом статьи вы можете ознакомиться по ссылке.

Эта третья статья из серии "За кулисами Minimal API" Эндрю Лока. В предыдущей статье этой серии мы подробно рассмотрели метод RequestDelegateFactory.InferMetadata() и то, как он выводит метаданные об обработчике эндпоинтов minimal API. В той статье я пропустил важный шаг — метод RequestDelegateFactory.CreateArgument(). Сегодня мы исследуем код в CreateArgument() и посмотрим, как это фундаментально определяет поведение привязки модели в minimal API.

Краткий обзор RequestDelegateFactory

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

• RouteEndpointDataSource—сохраняет «необработанные» сведения о каждом эндпоинте (делегат обработчика, RoutePattern и т. д.) и инициирует создание эндпоинтов в RequestDelegate и сопоставление их метаданных.
• RequestDelegateFactory.InferMetadata()—отвечает за чтение метаданных об аргументах и возвращаемом значении обработчика эндпоинта, а также за построение выражения (Expression) для каждого аргумента, которое впоследствии можно использовать для построения RequestDelegate.
• RequestDelegateFactory.Create()—отвечает за создание RequestDelegate, который ASP.NET Core вызывает путем построения и компиляции Expression из обработчика эндпоинта.

До сих пор мы фокусировались на функции InferMetadata(), а в этой статье мы рассмотрим метод, который она вызывает: CreateArgument(). Напомню, вот как выглядит InferMetadata():

public static RequestDelegateMetadataResult InferMetadata(
    MethodInfo methodInfo, RequestDelegateFactoryOptions? options = null)
{
    var factoryContext = CreateFactoryContext(options);
    factoryContext.ArgumentExpressions = 
        CreateArgumentsAndInferMetadata(methodInfo, factoryContext);

    return new RequestDelegateMetadataResult
    {
        EndpointMetadata = AsReadOnlyList(factoryContext.EndpointBuilder.Metadata),
    };
}

CreateArgumentsAndInferMetadata(), в свою очередь, вызывает CreateArguments(), передавая подробности о параметрах обработчика эндпоинта как ParameterInfo[]:

private static Expression[] CreateArgumentsAndInferMetadata(
    MethodInfo methodInfo, RequestDelegateFactoryContext factoryContext)
{
    var args = CreateArguments(methodInfo.GetParameters(), factoryContext);
    // ...
    return args;
}

И CreateArguments() в итоге вызывает CreateArgument() для каждого ParameterInfo:

private static Expression[] CreateArguments(
    ParameterInfo[]? parameters, RequestDelegateFactoryContext factoryContext)
{
    // ...
    var args = new Expression[parameters.Length];

    for (var i = 0; i < parameters.Length; i++)
    {
        args[i] = CreateArgument(parameters[i], factoryContext); // 👈
    }
    // ...
    return args;
}

В этой статье мы подробно рассмотрим структуру метода CreateArgument().

Обязанности CreateArgument

Исходя из названия и сигнатуры, можно подумать, что обязанности CreateArgument просты, и в некотором смысле так оно и есть: он создает выражение (Expression), которое может создать параметр обработчика, получив доступ к переменной httpContext HttpContext.

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

app.MapGet("/{id}", (string id, HttpRequest request, ISomeService service) => {});

Чтобы выполнить обработчик, ASP.NET Core в конечном итоге необходимо сгенерировать выражение, которое выглядит примерно так:

Task Invoke(HttpContext httpContext)
{
    // Разбор и привязка к модели параметра `id` из RouteValues
    bool wasParamCheckFailure = false;
    
    string id_local = httpContext.RouteValues["id"];
    if (id_local == null)
    {
        wasParamCheckFailure = true;
        Log.RequiredParameterNotProvided(httpContext, "string", "id", "route");
    }

    if(wasParamCheckFailure)
    {
        // привязка не удалась, возвращаем код 400
        httpContext.Response.StatusCode = 400;
        return Task.CompletedTask;
    }
     
    // handler, это оригинальный метод лямба обработчика.
    // Параметр HttpRequest автоматически создается из аргумента HttpContext
    // и параметра ISomeService полученного из DI контейнера
    string text = handler.Invoke(
        id_local,
        httpContext.Request,
        httpContext.RequestServices.GetRequiredService<ISomeService>());

    // Возвращаемое значение записывается в ответ, как и ожидалось.
    httpContext.Response.ContentType ??= "text/plain; charset=utf-8";
    return httpContext.Response.WriteAsync(text);
}

Как видите, здесь очень много кода! Большая его часть (хотя и не вся) генерируется CreateArgument() в виде дерева Expression. Из этого участка кода видно, что CreateArgument() косвенно отвечает за другие различные функции:

• Он определяет порядок привязки моделей. Тот факт, что параметр id привязывается к параметру маршрута, а не к строке запроса, определяется в CreateArgument().
• Он определяет поведение при неудачном связывании моделей. Здесь рассматривается разное поведение необязательных и обязательных параметров, а также исключения при их разборе.

В этой статье мы сосредоточимся на первой из этих обязанностей, разберем как код в CreateArgument() определяет поведение привязки модели minimal API.

Здесь я не буду рассматривать сгенерированные деревья выражений; мы рассмотрим их в следующей статье. В этой мы рассмотрим, как CreateArgument выбирает, какое дерево выражений генерировать.

Защита от недопустимых значений в CreateArgument().

Как и следовало ожидать, первое, что делает функция CreateArgument(), — это защищает от недопустимых аргументов. Он специально проверяет 2 вещи:

• У параметра есть имя (ParameterInfo.Name is not null). Параметры обычно имеют имя в ваших обработчиках, но имена параметров технически необязательны в IL.
• Параметры не используют модификаторы in, out, или ref. Они не поддерживаются в minimal API.

В обоих этих случаях CreateArgument() генерирует исключение, немедленно останавливая приложение. Фрагмент ниже показывает, как CreateArgument() выполняет проверки:

private static Expression CreateArgument(
    ParameterInfo parameter, RequestDelegateFactoryContext factoryContext)
{
    if (parameter.Name is null)
    {
        throw new InvalidOperationException(
            $"Обнаружен параметр типа '{parameter.ParameterType}' без имени. Параметры должны иметь имя.");
    }

    if (parameter.ParameterType.IsByRef)
    {
        var attribute = "ref";

        if (parameter.Attributes.HasFlag(ParameterAttributes.In))
        {
            attribute = "in";
        }
        else if (parameter.Attributes.HasFlag(ParameterAttributes.Out))
        {
            attribute = "out";
        }

        throw new NotSupportedException(
            $"Параметр по ссылке '{attribute} {TypeNameHelper.GetTypeDisplayName(parameter.ParameterType, fullName: false)} {parameter.Name}' не поддерживается.");
    }
 
    // ..
}

Когда эти простые проверки пройдены, мы остаемся с основной частью метода CreateArgument(), который, по сути, представляет собой гигантский оператор if...else if! Именно он определяет основное поведение приоритета привязки к модели в minimal API.

Понимание приоритета привязки модели в minimal API.

Вместо того чтобы воспроизводить все 150(!) строк if`ов, мы начнем с рассмотрения важных категорий, которые использует CreateArgument(), в порядке приоритета:

1. Имеет ли параметр атрибут [From*]? Если да, привязываем к соответствующему источнику. Например, если параметр имеет атрибут [FromHeader], привязываем его к значению заголовка.
2. Является ли параметр "известным" типом, таким как HttpContext или HttpRequest? Если да, используем соответствующий тип из запроса.
3. Есть ли у параметра метод BindAsync()? Если да, вызываем его, чтобы связать параметр.
4. Является ли метод строкой, или у него есть метод TryParse (например, встроенные типы, такие как int и Guid, а также пользовательские типы). Если да: - Были ли параметры маршрута успешно разобраны из RoutePattern? (Если да, есть ли параметр маршрута, соответствующий имени параметра? Если да, выполняем привязку из значений маршрута. Если нет подходящего параметра маршрута, привязка выполняется из строки запроса.) -Если параметры маршрута не были успешно разобраны из RoutePattern, попробуем привязать к запросу RouteValues, и, если параметр не найден, вернемся к строке запроса вместо него.
5. Если привязка к телу отключена и параметр является массивом типов, реализующих TryParse (или string/`StringValues`), то привязка осуществляется к строке запроса.
6. Является ли параметр сервисом известным DI? Если да, привязываем к службе DI.
7. В противном случае привязка к телу запроса путем десериализации в формате JSON.

Хорошо... возможно, это все еще трудно понять. В качестве альтернативы вы можете представить, что "if" реализует следующую блок-схему:

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

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

Привязка параметров [From*]

Наивысший приоритет для связывания — это, когда вы применили атрибут [From*] к параметру, например [FromRoute] или [FromQuery]:

app.MapGet("/{id}", ([FromRoute] int id, [FromQuery]string search) => "Hello world");

CreateArgument проверяет по очереди каждый из поддерживаемых атрибутов [From]; первый найденный атрибут определяет источник привязки параметра. В большинстве случаев CreateArgument "вслепую" использует указанный источник, хотя он проверяет пару недопустимых условий и при их обнаружении немедленно выбрасывает исключение:

• Если у вас есть атрибут [FromRoute], параметры маршрута были разобраны из RoutePattern, но имя параметра (или имя, указанное в атрибуте) не существует в коллекции маршрутов, вы получите InvalidOperationException();
• Если вы примените атрибут [FromFile] к параметру, который не является IFormFile или IFormFileCollection, вы получите NotSupportedException.
• Если указать имя в атрибуте [FromFile], применяемом к коллекции IFormFileCollection, вы получите NotSupportedException (указание имени поддерживается только для IFormFile).
• Если вы попытаетесь использовать "вложенные" атрибуты [AsParameters] (применяя [AsParameters] к свойству), вы получите NotSupportedException.

Эти исключения возникают сразу после вызова CreateArgument, поэтому эндпоинт никогда не будет создан, и ваше приложение не запустится правильно.

CreateArgument() ищет каждый из атрибутов [From*] в порядке, показанном в приведенном ниже фрагменте. Это не правильный C#, это просто псевдокод (так что не кричите на меня), но я думаю, что так легче увидеть порядок атрибутов и некоторые из принятых "под" решений.

switch =>
{
    // If the parameter has a [FromRoute] attribute, bind to route parameter if it exists
    // if the parameter doesn't exist, throw an InvalidOperationException
    [FromRoute] when "param" exists => HttpContext.Request.RouteValues["param"],
    [FromRoute] => throw new InvalidOperationException(),

    // If the parameter has a [FromQuery] attribute, bind to query parameter
    [FromQuery] => HttpContext.Request.Query["param"],

    // If the parameter has a [FromHeader] attribute, bind to header parameter
    [FromHeader] => HttpContext.Request.Headers["param"],

    // If the parameter has a [FromBody] attribute, bind to the request stream or request body
    // depending on the parameter type
    [FromBody] => switch parmeterType
    {
        Stream stream => HttpContext.Request.Body,
        PipeReader reader => HttpContext.Request.BodyReader,
        // If a generic type, add metadata indicating the API accepts 'application/json' with type T 
        T _ => JsonSerializer.Deserialize<T>(HttpContext.Request.Body),
    },

    // If the parameter has a [FromForm] attribute, bind to the request body as a form
    // This also adds metadata indicating the API accepts the 'multipart/form-data' content-type
    [FromForm] => switch parameterType
    {
        IFormFileCollection collection => HttpRequest.Form.Files,
        IFormFile file => HttpRequest.Form.Files["param"],
        _ => throw new NotSupportedException(),
    },

    // If the parameter has a [FromServices] attribute, bind to a service in DI
    [FromServices] => HttpContext.RequestServices.GetRequiredService(parameterType),

    // If the parameter has an [AsParameters] attribute, recursively bind the properties of the parameter
    [AsParameters] => goto start!
}

Обратите внимание, что при привязке к телу запроса CreateArgument также добавляет соответствующие метаданные [Accepts], указывающие на ожидаемую форму тела запроса, выведенную из типа параметра.

Привязка известных типов

Если параметр не имеет атрибута [From*], CreateArgument проверяет, является ли он типом, который может напрямую связываться с частью HttpContext. В частности, проверяются следующие типы в следующем порядке:

• HttpContext (привязывается к httpContext)
• HttpRequest (привязывается к httpContext.Request)
• HttpResponse (связывается с httpContext.Response)
• ClaimsPrincipal (привязывается к httpContext.User)
• CancellationToken (связывается с httpContext.RequestAborted)
• IFormFileCollection (связывается с httpContext.Request.Form.Files и добавляет метаданные [Accepts])
• IFormFile (привязывается к httpContext.Request.Form.Files["param"], и добавляет метаданные [Accepts])
• Stream (привязывается к httpContext.Request.Body)
• PipeReader (привязывается к httpContext.Request.BodyReader)

Большинство из них являются очень простыми привязками, поскольку они буквально представляют собой типы, доступные в HttpContext. Только IFormFile и IFormFileCollection требуют более сложных выражений привязки.

Привязки использующие методы BindAsync

После проверки того, является ли Type известным типом, CreateArgument() проверяет, есть ли у метода метод BindAsync. Если да, то этот метод полностью отвечает за привязку аргумента к запросу.

Вы можете реализовать один из двух методов BindAsync:

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

Они не являются частью интерфейса как такового, ASP.NET Core использует отражение для проверки того, реализует ли тип параметра метод, и кэширует результат.

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

Если вы не укажете атрибут [From*], то большинство встроенных типов (например, int и string) будут связываться с параметрами маршрута или строкой запроса. Это также относится к любым типам, которые реализуют новый интерфейс IParseable (представленный в C#11, с использованием статических абстрактных членов) или имеют один из соответствующих методов TryParse:

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

Аналогично BindAsync, наличие статического метода TryParse определяется с помощью отражения и кэшируется, поэтому каждый тип проверяется только один раз.

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

Существует интересная третья возможность, когда параметры маршрута из шаблона RoutePattern недоступны. Я не уверен, в каких сценариях это может произойти, но, если это так, параметр будет пытаться привязаться и к маршруту, и к запросу. Во время выполнения, если существует значение маршрута с ожидаемым именем, оно будет использовано, в противном случае параметр будет привязан к строке запроса.

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

Следующая привязка является интересной. Она применяется только в том случае, если:

• параметр является string[], StringValues, StringValues?, или T[], где T имеет метод TryParse()
• DisableInferredFromBody равно true (что имеет место, например, для запросов GET и DELETE).

Если оба эти условия истинны, то параметр привязывается к строке запроса.

Помните, что строка запроса URL может содержать несколько экземпляров одного и того же ключа, например  ?q=1&q=2&q=3. Для обработчика типа (int[] q) => {} параметр q будет представлять собой массив с тремя значениями: new [] {1, 2, 3}.

Эта привязка интересна тем, что привязка массива, например int[], действительна для запросов GET и POST, но способ привязки совершенно разный. Это отличается от всех других подходов к привязке, где привязка параметров либо идентична для всех глаголов HTTP (например, атрибуты [From*] или BindAsync), либо вообще действительна только для некоторых глаголов (например, привязка сложных типов к телу запроса, как мы скоро увидим).

Но int[] — это другое. Он привязывается к разной части запроса в зависимости от глагола HTTP: для GET (и подобных) запросов он привязывается к строке запроса, а для POST (и подобных) запросов - к телу запроса, как и любой другой сложный тип.

Привязка сервисов

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

ASP.NET Core определяет, является ли данный запрос службой, которую можно внедрить, с помощью интерфейса (с интересным названием) IServiceProviderIsService. Этот интерфейс был представлен в .NET 6 специально для этой цели. Вы вызываете serviceProviderIsService.IsService(type), и если контейнер DI способен предоставить экземпляр типа, то возвращается true.

Если вы используете DI-контейнер стороннего производителя вместо встроенного, то контейнер должен реализовать IServiceProviderIsService. Это поддерживается в современных контейнерах, таких как Autofac и Lamar, но, если ваш контейнер не реализует этот интерфейс, вы не получите автоматической привязки к сервисам, и вместо этого вы должны использовать [FromService].

Последний вариант: Привязка к телу

Если ни один из других вариантов привязки не подходит, последний вариант - привязка к телу запроса. Обратите внимание, что этот вариант происходит независимо от того, находится ли запрос в GET или DELETE, в котором DisableInferredFromBody является истинным. Это "неправильное" поведение исправляется позже в методе CreateArguments() после привязки всех параметров обработчика, как я описал в предыдущей статье:

// Пытались ли мы сделать вывод о привязке к телу, когда этого делать не следовало?
if (factoryContext.HasInferredBody && factoryContext.DisableInferredFromBody)
{
    var errorMessage = BuildErrorMessageForInferredBodyParameter(factoryContext);
    throw new InvalidOperationException(errorMessage);
}

// Пытались ли мы привязаться как к телу JSON, так и к телу формы?
if (factoryContext.JsonRequestBodyParameter is not null &&
    factoryContext.FirstFormRequestBodyParameter is not null)
{
    var errorMessage = BuildErrorMessageForFormAndJsonBodyParameters(factoryContext);
    throw new InvalidOperationException(errorMessage);
}

// Пытались ли мы привязаться к телу несколько раз? 
if (factoryContext.HasMultipleBodyParameters)
{
    var errorMessage = BuildErrorMessageForMultipleBodyParameters(factoryContext);
    throw new InvalidOperationException(errorMessage);
}

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

Помимо генерации дерева выражений для привязки к телу запроса, финальный этап привязки добавляет метаданные [Accepts] в коллекцию эндпоинта, указывая, что запрос ожидает JSON-запрос, соответствующий типу связанного параметра.

И на этом мы подошли к концу этого длинной статьи о привязке моделей в minimal API! В следующей статье серии мы подробнее рассмотрим каждую из этих привязок, изучив деревья выражений, которые генерирует RequestDelegateFactory!

Подводя итог.

В этой статье я описал, как метод RequestDelegateFactory.CreateArgument() определяет логику привязки модели для minimal API. CreateArgument() отвечает за создание выражения, которое определяет, как создать аргумент для обработчика minimal API, поэтому основополагающим решением является то, какой источник использовать: заголовки, строку запроса, DI-сервис и т. д.

Я показал, что минимальная логика привязки модели API работает через семь различных категорий при определении того, какой источник использовать: [From*] атрибуты, известные типы, методы BindAsync(), методы TryParse(), привязка массива к строке запроса (для GET-запросов), DI-сервисы и, наконец, тело запроса. Используется первый источник, с которым совпадает параметр. Это определяет генерируемое выражение. В следующей статье мы рассмотрим, как на самом деле выглядят сгенерированные деревья Expression!

С оригиналом статьи вы можете ознакомиться по ссылке.

Эта вторая статья из серии "За кулисами Minimal API" Эндрю Лока. В предыдущей статье мы достаточно подробно рассмотрели, как простой minimal API MapGet("/", () => "Hello world", превращается в RequestDelegate, который может вызываться EndpointMiddleware. В этой статье я сосредоточусь на методе RequestDelegateFactory.InferMetadata() и разберу, как он работает.

Получение метаданных от делегата

В предыдущей статье основное внимание уделялось методу CreateRouteEndpointBuilder(). Этот метод вызывается, когда приложение впервые получает запрос, и отвечает за преобразование RouteEntry и RoutePattern, связанных с эндпоинтом, в RouteEndpointBuilder. Затем всё это используется для создания RouteEndpoint, который можно вызывать для обработки данного запроса.

CreateRouteEndpointBuilder() отвечает как за составление списка метаданных для эндпоинта, так и за создание его RequestDelegate. Напомним, что RequestDelegate — это функция, которая фактически вызывается для обработки запроса и выглядит следующим образом:

public delegate Task RequestDelegate(HttpContext context);

Обратите внимание, что эта сигнатура не соответствует лямбда делегату, который мы передали в MapGet, в примере Hello World - () => «Hello world!» имеет сигнатуру, которая выглядит следующим образом:

public string SomeMethod();

CreateRouteEndpointBuilder() в сочетании с классом RequestDelegateFactory отвечает за создание функции, которая соответствует сигнатуре RequestDelegate на основе предоставленного делегата.

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

Рассмотрим немного более сложный пример, который внедряет объект HttpRequest в обработчик: MapGet("/", (HttpRequest request) => "Hello world!"). RequestDelegateFactory должен создать метод с требуемой сигнатурой RequestDelegate, но который создает аргументы, необходимые для вызова метода обработчика. Окончательный результат выглядит примерно так:

Task Invoke(HttpContext httpContext)
{
    // handler — оригинальный метод лямбда-обработчика.
    // Параметр HttpRequest автоматически создается из HttpContext аргумента
    string text = handler.Invoke(httpContext.Request);

    // Возвращаемое значение записывается в ответ, как и ожидалось.
    httpContext.Response.ContentType ??= "text/plain; charset=utf-8";
    return httpContext.Response.WriteAsync(text);
}

Инфраструктура minimal API создает такой метод с использованием Expersion, что является одной из причин высокой скорости minimal API. Это равносильно тому, что вы напишете такой код вручную для каждой из ваших эндпоинтов. Конечно, построение этих выражений не является тривиальным, поэтому эта серия довольно длинная!

Некоторая информация о функции-обработчике и ее параметрах явно добавляется в качестве метаданных в эндпоинт, а также используется для непосредственного построения RequestDelegate. В следующем разделе мы рассмотрим функцию RequestDelegateFactory.InferMetadata(), чтобы увидеть, как выводится эта информация.

Вывод метаданных о методе обработчика

В предыдущей статье я показал метод RouteEndpointDataSource.CreateRDFOptions(), который создает экземпляр RequestDelegateFactoryOptions на основе методов обработчика RouteEntry и RoutePattern. Этот объект представляет собой простой набор опций для управления тем, как создается окончательный RequestDelegate. Большинство свойств объекта говорят сами за себя, но я подписал их назначение ниже:

public sealed class RequestDelegateFactoryOptions
{
    // DI контейннер для приложения
    public IServiceProvider? ServiceProvider { get; init; }

    // Имена любых параметров в маршруте.
    // например для маршрута /view/{organization}/{id}
    // содержит два значения, "organization" и "id"
    public IEnumerable<string>? RouteParameterNames { get; init; }

    // True если RequestDelegate должен прерывать плохие запросы
    public bool ThrowOnBadRequest { get; init; }

    // Должен ли RequestDelegate пытаться связать тело запроса по умолчанию
    // Смотрите предыдущую статью для подробного объяснения
    public bool DisableInferBodyFromParameters { get; init; }

    // Используется для создания RequestDelegate и для применения фильтров к эндпоинтам
    public EndpointBuilder? EndpointBuilder { get; init; }
}

Вы можете прочитать, как метод CreateRouteEndpointBuilder() создает объект, вызвав CreateRDFOptions в предыдущем посте. После создания параметров у нас есть вызов RequestDelegateFactory.InferMetadata, показанный ниже.

public static RequestDelegateMetadataResult InferMetadata(
    MethodInfo methodInfo, // 👈 Информация об отражении метода обработчика
    RequestDelegateFactoryOptions? options = null) // 👈 Опции объекта
{
    // Создает "context" объекь (показан кратко)
    RequestDelegateFactoryContext factoryContext = CreateFactoryContext(options);

    // Читает информацию об аргуметах метода обработчика
    factoryContext.ArgumentExpressions = CreateArgumentsAndInferMetadata(methodInfo, factoryContext);

    // Сохраняет метаданные в объект, который в последствии используется для создания RequestDelegate
    return new RequestDelegateMetadataResult
    {
        EndpointMetadata = AsReadOnlyList(factoryContext.EndpointBuilder.Metadata),
    };
}

Этот метод принимает объект MethodInfo, который содержит всю «отражающую» информацию о методе. Обратите внимание, что в моих примерах эндпоинтов API я показывал обработчик в виде лямбда выражения, но вы получили бы то же самое, если бы использовали статический метод, метод экземпляра или локальную функцию в качестве обработчика.

InferMetadata, показанный выше, состоит из двух основных шагов:

• Создание объекта "context"  RequestDelegateFactoryContext
• Получение информации о параметрах метода обработчика

Метод CreateFactoryContext вызывается как здесь, в InferMetadata(), так и позже, при создании RequestDelegate в RequestDelegateFactory.Create(), поэтому он имеет несколько необязательных параметров. При выводе метаданных предоставляется только первый параметр, поэтому большая часть метода на данный момент не используется. Схема ниже показывает упрощенную версию CreateFactoryContext с учетом этого:

private static RequestDelegateFactoryContext CreateFactoryContext(
    RequestDelegateFactoryOptions? options,
    RequestDelegateMetadataResult? metadataResult = null, // 👈 всегда null в InferMetadata
    Delegate? handler = null) // 👈 всегда null в InferMetadata
{
    if (metadataResult?.CachedFactoryContext is not null)
    {
        // детали скрыты, потомучто  metadataResult ровняется null в InferMetadata и не вызывается
    }

    // ServiceProvider  не null и устанавливается в CreateRDFOptions()
    IServiceProvider serviceProvider = options?.ServiceProvider;
    
    // EndpointBuilder ровняется null в InferMetadata, поэтому всегда создает новый билдер
    var endpointBuilder = options?.EndpointBuilder ?? new RDFEndpointBuilder(serviceProvider);

    var factoryContext = new RequestDelegateFactoryContext
    {
        Handler = handler, // null, поскольку не указан в InferMetadata
        ServiceProvider = options.ServiceProvider,
        ServiceProviderIsService = serviceProvider.GetService<IServiceProviderIsService>(),
        RouteParameters = options?.RouteParameterNames?.ToList(),
        ThrowOnBadRequest = options?.ThrowOnBadRequest ?? false,
        DisableInferredFromBody = options?.DisableInferBodyFromParameters ?? false,
        EndpointBuilder = endpointBuilder
        MetadataAlreadyInferred = metadataResult is not null, // false
    };

    return factoryContext;
}

Как видно из приведенного выше фрагмента, RequestDelegateFactoryContext в основном содержит копии значений из RequestDelegateFactoryOptions. RDFEndpointBuilder — это очень простая реализация EndpointBuilder, которая предотвращает вызов Build().

private sealed class RDFEndpointBuilder : EndpointBuilder
{
    public RDFEndpointBuilder(IServiceProvider applicationServices)
    {
        ApplicationServices = applicationServices;
    }

    public override Endpoint Build() => throw new NotSupportedException();
}

После создания RequestDelegateFactoryContext следующий большой шаг — анализ параметров обработчика, чтобы понять, как их создавать (из параметров запроса, служб и т. д.), и добавление метаданных в коллекцию эндпоинта.

Анализ параметров обработчика

RequestDelegateFactory анализирует параметры MethodInfo обработчика в CreateArgumentsAndInferMetadata(), передавая метод обработчика и новый объект контекста:

private static Expression[] CreateArgumentsAndInferMetadata(
    MethodInfo methodInfo, RequestDelegateFactoryContext factoryContext)
{
    // Добавляет любые принимаемые по умолчанию метаданные.
    // При этом выполняется много рефлекшенов и построения деревьев выражений,
    // поэтому результаты кэшируются в RequestDelegateFactoryOptions.FactoryContext,
    // а затем повторно используются в RequestDelegateFactory.Create().
    var args = CreateArguments(methodInfo.GetParameters(), factoryContext);

    if (!factoryContext.MetadataAlreadyInferred)
    {
        PopulateBuiltInResponseTypeMetadata(methodInfo.ReturnType, factoryContext.EndpointBuilder);

        // Добавляет метаданные, предоставленные типом возвращаемого 
        // делегата и типами параметров, вводит данные
        EndpointMetadataPopulator.PopulateMetadata(
            methodInfo,
            factoryContext.EndpointBuilder,
            factoryContext.Parameters);
    }

    return args;
}

Комментарии и имена методов в этом методе довольно хорошо объясняют, что происходит, но здесь важно понимать, что мы берем MethodInfo и генерируем массив Expression[] (одно выражение для каждого параметра, который принимает метод обработчика).

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

В следующем разделе мы подробно рассмотрим вызов CreateArguments(), где создается выражение для каждого из параметров метода обработчика.

Создание выражений аргументов.

Первым вызовом метода в CreateArgumentsAndInferMetadata() является CreateArguments(), в котором передаются сведения ParameterInfo[] для метода обработчика, а также объект контекста. Этот метод слишком объемный для чтения в одном блоке кода, поэтому я разобью его на разделы и буду обсуждать каждый по ходу дела.

private static Expression[] CreateArguments(
    ParameterInfo[]? parameters, RequestDelegateFactoryContext factoryContext)
{
    if (parameters is null || parameters.Length == 0)
    {
        return Array.Empty<Expression>();
    }

    var args = new Expression[parameters.Length];
    
    factoryContext.ArgumentTypes = new Type[parameters.Length];
    factoryContext.BoxedArgs = new Expression[parameters.Length];
    factoryContext.Parameters = new List<ParameterInfo>(parameters);

    var hasFilters = factoryContext.EndpointBuilder.FilterFactories.Count > 0;

    // ...
}

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

Я подробно рассмотрю, как фильтры применяются в RequestDelegateFactory, в следующем посте этой серии. Кроме того, вы можете прочитать это объяснение Сафии Абдаллы, которая работала над функцией фильтров!

После инициализации всех массивов мы перебираем параметры метода и создаем Expression, используемый для привязки аргумента к запросу:

for (var i = 0; i < parameters.Length; i++)
{
    args[i] = CreateArgument(parameters[i], factoryContext);

    if (hasFilters)
    {
        // Если метод содержит фильтры, создаем expression`ы 
        // для построения EndpointFilterInvocationContext
    }

    factoryContext.ArgumentTypes[i] = parameters[i].ParameterType;
    factoryContext.BoxedArgs[i] = Expression.Convert(args[i], typeof(object));
}

Метод CreateArgument() выполняет много работы. Он принимает ParameterInfo и считывает различные метаданные, чтобы установить, каким образом создать Expression, который можно использовать для «создания» аргумента обработчику. Например, в начале этого поста вы видели, что параметр HttpRequest был создан с использованием выражения httpContext.Request:

Task Invoke(HttpContext httpContext)
{
    string text = handler.Invoke(httpContext.Request);
    // ...
}

В зависимости от источника аргумента (т. е. на основе поведения привязки модели) создается другое выражение. Например, если параметр должен быть привязан к параметру запроса, например, в эндпоинте MapGet("/", (string? search) => search), будет создано выражение, которое считывается из строки запроса:

Task Invoke(HttpContext httpContext)
{
    string text = handler.Invoke(httpContext.Request.Query["search"]);
    // ...
}

Для приведенного выше примера Expression, представляющий

httpContext.Request.Query["search"]

будет возвращен из CreateArgument() и сохранен в массиве args. Дополнительные сведения также будут установлены в RequestDelegateFactoryContext, чтобы уменьшить количество доработок в RequestDelegateFactory.Create(). При необходимости CreateArgument также выводит метаданные [Accepts] об ожидаемом формате тела запроса и добавляет их в коллекцию метаданных.

Точная логика в CreateArgument() управляет логикой привязки модели и приоритетом для minimal API и довольно сложна, поэтому я подробно рассмотрю этот метод в следующей статье.

"Запакованная" версия Expression (где результат выражения приводится к object) также создается для использования в фильтрах эндпоинтов (где это необходимо), а типы параметров сохраняются в factoryContext.

Последним шагом в методе CreateArguments() является выполнение некоторых проверок работоспособности, проверка распространенных неподдерживаемых сценариев перед возвратом сгенерированных аргументов Expression[].

// Пытались ли мы сделать вывод о привязке к телу, когда не должны?
// (подробности о том, как вычисляется DisableInferredFromBody, см. в предыдущем посте)
if (factoryContext.HasInferredBody && factoryContext.DisableInferredFromBody)
{
    var errorMessage = BuildErrorMessageForInferredBodyParameter(factoryContext);
    throw new InvalidOperationException(errorMessage);
}

// Пытались ли мы выполнить привязку как к телу JSON, так и к телу формы?
// Не может быть и того, и другого!
if (factoryContext.JsonRequestBodyParameter is not null &&
    factoryContext.FirstFormRequestBodyParameter is not null)
{
    var errorMessage = BuildErrorMessageForFormAndJsonBodyParameters(factoryContext);
    throw new InvalidOperationException(errorMessage);
}

// Пытались ли мы выполнить привязку к телу несколько раз?
if (factoryContext.HasMultipleBodyParameters)
{
    var errorMessage = BuildErrorMessageForMultipleBodyParameters(factoryContext);
    throw new InvalidOperationException(errorMessage);
}

return args;

Теперь у нас есть выражение для каждого из параметров обработчика, описывающее, как он должен быть создан с учетом доступного параметра HttpContext. Следующим шагом является чтение возвращаемого значения метода обработчика и его использование для вывода HTTP-ответа, генерируемого эндпоинтом.

Вывод типа ответа HTTP из обработчика.

Метод PopulateBuiltInResponseTypeMetadata() отвечает за эффективную попытку вывести атрибут [Produces] для обработчика на основе возвращаемого типа метода и добавить его в коллекцию метаданных. Вы можете прочитать подробную логику метода здесь, но он эффективно использует следующую последовательность.

• Возвращаемый тип Task<T> или ValueTask<T> (или другие поддерживаемые await типы)? (Если да, возвращаемый тип обрабатывается как тип Т и выполнение продолжается.).
• Возвращаемый тип void, Task, ValueTask, или IResult? (Если да, то не можем вывести тип ответа, поэтому выходим).
• Возвращаемый тип string? (Если да, то добавляем [Produces("text/plain")], если нет, то добавляем [Produces(returnType)])

Обратите внимание, что начиная с .NET 7 типы IResult могут реализовывать IEndpointMetadataProvider для предоставления дополнительной [Produces] информации (например, с помощью помощников TypedResults), но IEndpointMetadataProvider не обрабатывается в методе PopulateBuiltInResponseTypeMetadata(). Вместо этого, он обрабатывается в следующем методе.

Заполнение метаданных из параметров с самоописанием.

В .NET 7 добавлены интерфейсы IEndpointMetadataProvider и IEndpointParameterMetadataProvider, чтобы параметры вашего обработчика и возвращаемые типы были «самоописываемыми». Параметры, которые реализуют один (или оба) из этих интерфейсов, могут заполнять метаданные о себе, что обычно означает, что вам нужно меньше атрибутов и гибких методов для описания ваших API для OpenAPI.

Оба интерфейса содержат один статический абстрактный метод, поэтому вы реализуете их, реализуя статический метод в своем классе:

public interface IEndpointMetadataProvider
{
    static abstract void PopulateMetadata(MethodInfo method, EndpointBuilder builder);
}

public interface IEndpointParameterMetadataProvider
{
    static abstract void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder);
}

Статическая часть важна, так как это означает, что RequestDelegateFactory может прочитать детали метаданных один раз, не имея экземпляра вашего параметра. Это происходит в методе RequestDelegateFactory.PopulateBuiltInResponseTypeMetadata(), который вызывает вспомогательный метод EndpointMetadataPopulator.PopulateMetadata(), передавая метод обработчика, EndpointBuilder и параметры обработчика.

Я полностью воспроизвел EndpointMetadataPopulator ниже и добавил несколько пояснительных комментариев. Метод PopulateMetadata() перебирает каждый из параметров метода, проверяет, реализует ли он какой-либо из интерфейсов, и, если да, вызывает реализованную функцию. Однако все это приходится делать с помощью рефлексии, что немного усложняет понимание!

internal static class EndpointMetadataPopulator
{
    public static void PopulateMetadata(
        MethodInfo methodInfo, 
        EndpointBuilder builder,
        IEnumerable<ParameterInfo>? parameters = null)
    {
        // Эта переменная массива создается здесь, чтобы массив
        // можно было переиспользовать для каждого аргумента, уменьшая алокацию
        object?[]? invokeArgs = null;
        parameters ??= methodInfo.GetParameters();

        // Получение метаданных из параметров типа
        foreach (var parameter in parameters)
        {
            if (typeof(IEndpointParameterMetadataProvider)
                .IsAssignableFrom(parameter.ParameterType))
            {
                // Параметры типа реализуют IEndpointParameterMetadataProvider
                invokeArgs ??= new object[2];
                invokeArgs[0] = parameter;
                invokeArgs[1] = builder;

                // Использование рефлексии для вызова PopulateMetadata для типа параметра
                 // Использование универсального метода между ними — хитрый способ для неявного кэширования
                PopulateMetadataForParameterMethod.MakeGenericMethod(parameter.ParameterType).Invoke(null, invokeArgs);
            }

            if (typeof(IEndpointMetadataProvider).IsAssignableFrom(parameter.ParameterType))
            {
                // Parameter type implements IEndpointMetadataProvider
                invokeArgs ??= new object[2];
                invokeArgs[0] = methodInfo;
                invokeArgs[1] = builder;

                // Использование рефлексии для вызова PopulateMetadata для типа параметра
                 // Использование универсального метода между ними — хитрый способ для неявного кэширования
                PopulateMetadataForEndpointMethod.MakeGenericMethod(parameter.ParameterType).Invoke(null, invokeArgs);
            }
        }

        // Получение метаданных из возвращаемого типа
        var returnType = methodInfo.ReturnType;
        if (AwaitableInfo.IsTypeAwaitable(returnType, out var awaitableInfo))
        {
            // If it's a Task<T> or ValueTask<T>, use the T as the returnType
            returnType = awaitableInfo.ResultType;
        }

        if (returnType is not null 
            && typeof(IEndpointMetadataProvider).IsAssignableFrom(returnType))
        {
            // Return type implements IEndpointMetadataProvider
            invokeArgs ??= new object[2];
            invokeArgs[0] = methodInfo;
            invokeArgs[1] = builder;
            
            // Используется рефлексия, чтобы вызвать PopulateMetadata для возвращаемого типа.
            PopulateMetadataForEndpointMethod.MakeGenericMethod(returnType).Invoke(null, invokeArgs);
        }
    }

    // Вспомогательные методы и свойства для эффективного вызова членов интерфейса
    private static readonly MethodInfo PopulateMetadataForParameterMethod = typeof(EndpointMetadataPopulator).GetMethod(nameof(PopulateMetadataForParameter), BindingFlags.NonPublic | BindingFlags.Static)!;
 
    private static readonly MethodInfo PopulateMetadataForEndpointMethod = typeof(EndpointMetadataPopulator).GetMethod(nameof(PopulateMetadataForEndpoint), BindingFlags.NonPublic | BindingFlags.Static)!;

    private static void PopulateMetadataForParameter<T>(ParameterInfo parameter, EndpointBuilder builder)
        where T : IEndpointParameterMetadataProvider
    {
        T.PopulateMetadata(parameter, builder);
    }

    private static void PopulateMetadataForEndpoint<T>(MethodInfo method, EndpointBuilder builder)
        where T : IEndpointMetadataProvider
    {
        T.PopulateMetadata(method, builder);
    }
}

Это подводит нас к последнему методу  RequestDelegateFactory.CreateArgumentsAndInferMetadata(). На данный момент Expression для каждого из параметров обработчика создано, включая определение того, откуда должен быть связан аргумент (на основе минимальных правил привязки модели API — подробнее об этом в следующем посте). Все метаданные, связанные с этим процессом, заполнены и добавлены в список метаданных EndpointBuilder. На этом этапе остается только вернуть RequestDelegateMetadataResult из InferMetadata(), содержащий все метаданные, которые мы получили из функции-обработчика:

public static RequestDelegateMetadataResult InferMetadata(MethodInfo methodInfo, RequestDelegateFactoryOptions? options = null)
{
    var factoryContext = CreateFactoryContext(options);
    factoryContext.ArgumentExpressions = CreateArgumentsAndInferMetadata(methodInfo, factoryContext);

    // возвращает метаданные как  IReadOnlyList<T>
    return new RequestDelegateMetadataResult
    {
        EndpointMetadata = AsReadOnlyList(factoryContext.EndpointBuilder.Metadata),
    };
}

Я был удивлен, увидев, что свойство CachedFactoryContext не установлено для возвращаемого объекта результата. Это приводит к большому количеству перестроений деревьев выражений, поэтому я поднял здесь проблему, которая исправлена для .NET 8 и, надеюсь, будет перенесена в .NET 7!

Наконец, мы добрались до конца нашего первого взгляда на RequestDelegateFactory.InferMetadata(). Один важный метод, который я упустил из виду, — это CreateArgument(), который отвечает за создание деревьев выражений, которые заполняют параметры метода обработчика из аргумента HttpContext, переданного в RequestDelegate.

В следующем посте я рассмотрю алгоритм, который CreateArgument() использует для создания каждого аргумента Expression, и, следовательно, правила привязки модели для minimal API.

Подводя итог.

В этом посте я впервые рассмотрел класс RequestDelegateFactory, который используется для создания экземпляра RequestDelegate из минимального метода обработчика API, чтобы его можно было вызвать в EndpointMiddleware. В этом посте я рассмотрел функцию InferMetadata().

InferMetadata() вызывается как часть конструкции эндпоинта для извлечения метаданных о методе обработчика, таких как типы его аргументов, тип возвращаемого значения, подразумеваемые атрибуты [Produces] и другие сведения. В рамках этого процесса InferMetadata() также строит деревья выражений, которые создают аргументы обработчика из HttpContext в окончательном RequestDelegate.

Оригинал статьи можно прочитать по ссылке.

Выпущен один из самых ожидаемых элементов управления для .NET MAUI - MediaElement. С помощью MediaElement вы можете легко воспроизводить аудио и видео из своего приложения .NET MAUI. В этом посте вы узнаете все, что вам нужно знать о первой версии и о планах на будущее элемента! MediaElement является частью .NET MAUI Community Toolkit, библиотеки, созданной сообществом, которая поддерживается замечательными разработчиками по всему миру как из сообщества, так и из Microsoft.

Что такое MediaElement?

С MediaElement вы получаете мощный контрол, который позволяет воспроизводить мультимедиа внутри вашего приложения .NET MAUI.

Возможно, вы уже знакомы с MediaElement из Xamarin Community Toolkit, куда он был добавлен благодаря замечательной работе члена сообщества Питера Фута. Хоть эта версия уже была довольно хороша, в ней также было место для улучшений, особенно для Android.

Вот почему при переносе MediaElement на .NET MAUI мы перестроили все с нуля. Таким образом, мы могли сохранить все то, что уже хорошо, и улучшить то, что требуется.

Под капотом

Для Android мы решили использовать ExoPlayer в качестве аналога платформы, заменив Android MediaPlayer, который мы использовали для Xamarin. Таким образом, мы автоматически получаем множество дополнительных функций, доступных нам из коробки, таких как воспроизведение видео HTTP Live Streaming (HLS), великолепные транспортные контролы и многое другое.

В iOS и macOS мы используем платформу AVPlayer, как и в случае с Xamarin MediaElement. Также не изменился Tizen, используется Tizen.Multimedia.Player.

Теперь, когда .NET MAUI строится поверх WinUI, а не UWP, мы используем новый MediaPlayerElement. Хотя этот элемент управления достаточно новый в WinUI, он уже достаточно совершенен и выглядит многообещающе.

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

Приступаем к работе

Начать работу с MediaElement очень просто. Сначала вам нужно установить пакет NuGet CommunityToolkit.Maui.MediaElement. Это отдельный пакет от основного пакета Community Toolkit.

После установки nuget пакета, откройте MauiProgram.cs и добавьте следующую строку инициализации в MauiAppBuilder:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        // Инициализируйте .NET MAUI Community Toolkit MediaElement добавив код ниже
        .UseMauiCommunityToolkitMediaElement()
        // После инициализации .NET MAUI Community Toolkit, при желании, добавьте дополнительные шрифты и другие вещи
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        });

    // Продолжаем инициализировать .NET MAUI приложение

    return builder.Build();
}

Теперь вы готовы начать использовать MediaElement в своем приложении! Простой пример на XAML можно найти ниже.

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MediaElementDemos.GettingStarted"
             Title="MediaElement Getting Started">

    <toolkit:MediaElement x:Name="mediaElement"
                      ShouldAutoPlay="True"
                      ShouldShowPlaybackControls="True"
                      Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
                      HeightRequest="300"
                      WidthRequest="400"
                      ... />
</ContentPage>

Это добавит элемент управления MediaElement на страницу, воспроизведение начнется автоматически при загрузке видео, результат работы на iOS и Windows можно увидеть ниже.

В этом посте я не буду вдаваться в подробности о богатых функциях, которые уже есть в первой версии, но важно отметить одну вещь. Вы, как разработчик, несете ответственность за выпуск ресурсов MediaElement. Например, приложение может воспроизводить видео в режиме «картинка в картинке» или воспроизводить звук в фоновом режиме, в этих сценариях невозможно автоматически определить, когда следует очищать ресурсы MediaElement.

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

public partial class FreeResourcesPage : ContentPage
{
    void ContentPage_Unloaded(object? sender, EventArgs e)
    {
        // Stop and cleanup MediaElement when we navigate away
        mediaElement.Handler?.DisconnectHandler();
    }
}

Чтобы узнать больше обо всех текущих функциях MediaElement, ознакомьтесь с подробной информацией на странице документации.

Данная статья, является первой из цикла статей от Эндрю Лока "Behind the scenes of minimal APIs".

Minimal API имеют репутацию быстрых, но как они этого добиваются? В этом и последующих постах я рассмотрю код, стоящий за некоторыми методами minimal API, и посмотрю, как они используются для того, чтобы взять ваш лямбда-метод и превратить его в нечто быстро выполняющееся.

В этом посте я рассматриваю код относительно высокого уровня, стоящий за вызовом MapGet("/", () => "Hello World!"), чтобы узнать основы того, как этот лямбда-метод преобразуется в RequestDelegate, который может быть выполнен ASP.NET Core.

Весь код в этой заметке основан на выпуске .NET 7.0.1.

Minimal Api на минимальном хосте.

Минимальные API были введены в .NET 6 вместе с "минимальным хостом", чтобы обеспечить более простой процесс адаптации к .NET. Вместе они устраняют множество телодвижений, связанных с приложением ASP.NET Core на базе общего хоста с использованием MVC. Базовое приложение hello world в MVC может состоять из 50–100 строк кода, распределенных как минимум по 3 классам. С минимальными API это так же просто, как:

WebApplicationBuilder builder = new WebApplication.CreateBuilder(args);
WebApplication app = builder.Build();

app.MapGet("/", () => "Привет мир!");

app.Run();

Очевидно, что в этих четырех строках происходит многое, от чего вы абстрагировались. У вас все еще есть практически те же возможности, что и у общего хоста, но большая их часть скрыта от вас.

В этой заметке я не буду рассматривать WebApplication, вместо этого мы рассмотрим, как лямбда-метод () => "Hello world!" превращается в RequestDelegate, который можно использовать для обработки HTTP-запросов.

Что такое RequestDelegate?

Прежде чем двигаться дальше, мы должны ответить на вопрос: "Что такое RequestDelegate"? Согласно документации, RequestDelegate — это:

Функция, которая может обрабатывать HTTP-запрос.

Что является довольно обобщенным объяснением. Но если вы посмотрите на определение делегата, то увидите, что оно описывает его довольно хорошо:

public delegate Task RequestDelegate(HttpContext context);

Итак, RequestDelegate — это делегат, который принимает HttpContext и возвращает Task.

Делегат можно рассматривать как "именованный" Func<T>. Они во многом похожи, хотя у них также есть странная семантика коллекций (которую я не буду здесь рассматривать).

Если вы знакомы с ASP.NET Core, вы также можете найти схожесть с сигнатурой метода Invoke для middleware:

public class MyMiddleware
{
    private readonly RequestDelegate _next;
    public MyMiddleware(RequestDelegate next)
        => _next = next;

    public Task Invoke(HttpContext context)
    {
        // Что нибудь делаем...
        return _next(context);
    }
}

Интересным свойством RequestDelegate, которое можно увидеть из приведенного выше примера, является возможность цепочки вызовов. Так, Invoke может быть приведен к RequestDelegate и, в свою очередь, может вызвать RequestDelegate, который сам может вызвать RequestDelegate. Это создает "конвейер middleware" для вашего приложения.

Итак, если мы рассмотрим минимальный endpoint API, такой как

app.MapGet("/", () => "Привет мир!");

нам нужно взять произвольный лямбда-метод, предоставленный в качестве обработчика endpoint`а (который не является RequestDelegate, поскольку не имеет правильной сигнатуры), и создать RequestDelegate. В этом посте мы рассмотрим процесс на высоком уровне, а в следующем начнем разбираться с тонкостями создания RequestDelegate.

От MapGet до RouteEntry

Когда вы вызываете MapGet() в WebApplication (или MapPost(), или MapFallback(), или большинство других расширений Map*()), вы вызываете метод расширения IEndpointRouteBuilder. В конце концов, если вы проследите за перегрузками достаточно далеко вниз, вы достигнете частного метода Map(), который выглядит примерно так:

private static RouteHandlerBuilder Map(
    this IEndpointRouteBuilder endpoints,
    RoutePattern pattern,
    Delegate handler,
    IEnumerable<string>? httpMethods,
    bool isFallback)
{
    RouteEndpointDataSource dataSource = endpoints.GetOrAddRouteEndpointDataSource();
    return dataSource.AddRouteHandler(pattern, handler, httpMethods, isFallback);
}

Аргумент Delegate handler — это лямбда-метод обработчика, который вы передаете при маппинге метода. Обратите внимание, что на данном этапе это очень общий тип Delegate, позже нам нужно будет извлечь параметры из делегата и решить, как их построить, привязав запрос или используя сервисы из DI.

Этот метод сначала извлекает RouteEndpointDataSource из конструктора, который, по сути, содержит список маршрутов (роутов) в приложении. Мы добавляем маршрут в коллекцию, вызывая для него AddRouteHandler(). Это создает объект RouteEntry (по сути, просто пакет свойств) и добавляет его в коллекцию. Он возвращает экземпляр RouteHandlerBuilder, который позволяет вам настроить endpoint, добавив к ней, к примеру, метаданные и фильтры.

Вот, собственно, и все, что происходит при вызове MapGet, он добавляет маршрут в коллекцию endpoint`ов. Все становится интересным, когда вы вызываете app.Run() и обрабатываете запрос.

Создание эндпоинтов

Когда вы делаете свой первый запрос к ASP.NET Core, где запрос попадает в EndpointRoutingMiddleware (добавленный неявно или вызовом UseRouting()), middleware запускает построение всех ваших эндпоинтов (и графа маршрутов, которым они соответствуют).

Для каждого RouteEntry в RouteEndpointDataSource(ах) вашего приложения, оно вызывает CreateRouteEndpointBuilder(), который возвращает экземпляр RouteEndpointBuilder. Он содержит все общие метаданные об эндпоинте, такие как отображаемое имя, а также метаданные OpenAPI, метаданные авторизации и фактический RequestDelegate, который выполняется в ответ на запрос.

Следующий фрагмент показывает, как строится отображаемое имя для эндпоинта, сначала пытаясь получить для нее "разумное" имя, такое как имя конкретного метода или имя локальной функции. Если это не удается (как в нашем простом () => "Hello World!"), вы получите имя, которое описывает только шаблон HTTP:  HTTP: GET /.

var displayName = pattern.RawText ?? pattern.DebuggerToString();

// Не включайте имя метода для немаршрутных обработчиков, потому что при сборке имя будет просто "Invoke".
// ApplicationBuilder.Build(). Это было замечено в MapSignalRTests и не очень полезно. Возможно, если мы придумаем
// лучшую эвристику для определения полезного имени метода, мы сможем использовать его для всего. Inline lambdas - это
// генерируемые компилятором методы, поэтому они отфильтровываются даже для обработчиков маршрутов.
if (isRouteHandler && TypeHelper.TryGetNonCompilerGeneratedMethodName(handler.Method, out var methodName))
{
    displayName = $"{displayName} => {methodName}";
}

if (entry.HttpMethods is not null)
{
    // Добавляет метод HTTP к DisplayName, полученному с помощью шаблона + имя метода
    displayName = $"HTTP: {string.Join(", ", entry.HttpMethods)} {displayName}";
}

if (isFallback)
{
    displayName = $"Fallback {displayName}";
}

Следующий метод создает метаданные для эндпоинта. Я не собираюсь подробно рассматривать этот процесс в этом посте, но "добавление метаданных" включает в себя добавление различных объектов в список

Чтобы создать коллекцию метаданных, CreateRouteEndpointBuilder() добавляет в коллекцию метаданных следующее в таком порядке:

• MethodInfo обработчика для выполнения.
• Объект HttpMethodMetadata, описывающий HTTP-глаголы, на которые отвечает обработчик.
• Для каждой route-group конвенции, применяет соглашение к конструктору, который может добавлять метаданные.
• Читает метод и выводит все его типы параметров и их источники, кэшируя и сохраняя их как RequestDelegateMetadataResult, использует RequestDelegateFactory.
• Это большой шаг, где происходит основная магия. Я собираюсь подробно рассмотреть этот процесс в отдельном посте.
• Добывляет любые атрибуты, примененные к методу, в качестве метаданных (такие как [Authorize] и подобные).
• Для каждой конвенции эндпоинта, применяет соглашение к конструктору, который может добавлять метаданные.
• Использует ранее построенный RequestDelegateMetadataResult для построения RequestDelegate для эндпоинта.
• Для каждой "финальной" route-group конвенции, применяет соглашение к конструктору, который может добавлять метаданные.

Все эти шаги немного расплывчаты, но на двух наиболее важных этапах создаются RequestDelegateMetadataResult и RequestDelegate. Мы рассмотрим эти шаги более подробно позже в этом и последующих постах.

После того, как RouteEndpointBuilder получит RequestDelegate и метаданные будут полностью заполнены, RouteEndpointDataSource вызывает RouteEndpointBuilder.Build(). Это завершает эндпоинт как RouteEndpoint. Как только все конечные точки построены, DfaMatcher может сделать свое дело, чтобы построить полный граф эндпоинтов, используемых в маршрутизации, который может выглядеть примерно так:

После создания DfaMatcher EndpointRoutingMiddleware может правильно выбрать конечную точку для маршрутизации и RequestDelegate, который должен быть выполнен.

Построение RequestDelegateFactoryOptions с помощью ShouldDisableInferredBodyParameters

Ранее я упоминал, что вывод метаданных об эндпоинте и создание RequestDelegate являются важными частями процесса создания эндпоинта. Первым шагом для них является создание объекта RequestDelegateFactoryOptions. Это делается в методе CreateRDFOptions(), показанном ниже.

private RequestDelegateFactoryOptions CreateRDFOptions(
    RouteEntry entry, RoutePattern pattern, RouteEndpointBuilder builder)
{
    var routeParamNames = new List<string>(pattern.Parameters.Count);
    foreach (var parameter in pattern.Parameters)
    {
        routeParamNames.Add(parameter.Name);
    }

    return new()
    {
        ServiceProvider = _applicationServices,
        RouteParameterNames = routeParamNames,
        ThrowOnBadRequest = _throwOnBadRequest,
        DisableInferBodyFromParameters = ShouldDisableInferredBodyParameters(entry.HttpMethods),
        EndpointBuilder = builder,
    };
}

Первым шагом метода является чтение всех имен параметров маршрута из шаблона маршрута для эндпоинта. Таким образом, для маршрута, такого как /users/{id}, это будет список, содержащий только идентификатор строки.

RoutePatternParser отвечает за получение строки типа /users/{id} и преобразование ее в объект RoutePattern со всеми правильно идентифицированными сегментами, параметрами, ограничениями и значениями по умолчанию. Там только 600 строк кода, поэтому я пропустил этот процесс в этом посте!

Помимо хранения имен параметров маршрута, объект options содержит некоторые другие вспомогательные функции и настройки. Поле _applicationServices — это контейнер DI (IServiceProvider) для приложения, а поле _throwOnBadRequest задается свойством RouteHandlerOptions.ThrowOnBadRequest (которое по умолчанию имеет значение true при работе в dev).

Интересная часть объекта CreateRDFOptions — вызов ShouldDisableInferredBodyParameters. Этот метод вычисляет, как следует обрабатывать параметр сложного объекта в вашем эндпоинте. Например, если у вас есть эндпоинт MapPost, который выглядит примерно так:

app.MapPost("/users", (UserModel user) => {});

тогда minimal API попытается связать объект UserModel с телом запроса. Однако, если у вас есть тот же делегат с запросом MapGet:

app.MapGet("/users", (UserModel user) => {});

тогда API попытается рассматривать UserModel как службу в DI, и, если она недоступна (что, по-видимому, не будет!) вызовет исключение InvalidOperationException.

Должна ли сложная модель пытаться выполнить привязку к телу по умолчанию или нет, управляется свойством RequestDelegateFactoryOptions.DisableInferBodyFromParameters, которое задается с помощью метода ShouldDisableInferredBodyParameters(), показанного ниже.

private static bool ShouldDisableInferredBodyParameters(IEnumerable<string>? httpMethods)
{
    static bool ShouldDisableInferredBodyForMethod(string method) =>
        // GET, DELETE, HEAD, CONNECT, TRACE, and OPTIONS normally do not contain bodies
        method.Equals(HttpMethods.Get, StringComparison.Ordinal) ||
        method.Equals(HttpMethods.Delete, StringComparison.Ordinal) ||
        method.Equals(HttpMethods.Head, StringComparison.Ordinal) ||
        method.Equals(HttpMethods.Options, StringComparison.Ordinal) ||
        method.Equals(HttpMethods.Trace, StringComparison.Ordinal) ||
        method.Equals(HttpMethods.Connect, StringComparison.Ordinal);

    // If the endpoint accepts any kind of request, we should still infer parameters can come from the body.
    if (httpMethods is null)
    {
        return false;
    }

    foreach (var method in httpMethods)
    {
        if (ShouldDisableInferredBodyForMethod(method))
        {
            // If the route handler was mapped explicitly to handle an HTTP method that does not normally have a request body,
            // we assume any invocation of the handler will not have a request body no matter what other HTTP methods it may support.
            return true;
        }
    }

    return false;
}

Логику этого метода можно резюмировать следующим образом:

• Принимает ли эндпоинт все глаголы HTTP? Если это так, включает предполагаемую привязку к телу запроса.
• Принимает ли конечная точка какие-либо из следующих команд: GET, DELETE, HEAD, CONNECT, TRACE, OPTIONS. Если это так, отключает предполагаемую привязку к телу запроса.
• В противном случае включает предполагаемую привязку.

В большинстве случаев, например, при использовании MapGet или MapPost, ваши эндпоинты обрабатывают только один HTTP-метод, поэтому достаточно просто отключить привязку к телу.

Обратите внимание, что это определяет только предполагаемую привязку по умолчанию к телу запроса. Вы всегда можете переопределить его с помощью [FromBody] и принудительно выполнить такие действия, как привязка к телу запроса GET.

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

Подводя итог

В этом посте я представил высокоуровневое описание того, как вызов MapGet() в WebApplication приводит к построению RequestDelegate для обработки запроса. Вызов MapGet() добавляет объект RouteEntry в RouteEndpointDataSource, но построение эндпоинта не происходит до тех пор, пока хост не будет запущен и вы не начнете обрабатывать запросы.

Когда middleware маршрутизации получает свой первый запрос, оно вызывает CreateRouteEndpointBuilder() для каждого RouteEntry. Это создает список всех метаданных, добавленных к эндпоинту (или к любой группе маршрутов, частью которой является эндпоинт), создает отображаемое имя для эндпоинта и создает RequestDelegate. Эти данные используются для построения графа DFA для маршрутизации эндпоинтов.

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

Оригинал статьи вы можете прочитать по ссылке.

В приложениях часто используются секреты (пароли, токены от API и так далее) для доступа к базам данных или внешним службам. Секреты обычно предоставляются с помощью переменных окружения, конфигурационного файла или хранилища (Azure Vault, Google Secret Manager и т.д.). Эти секреты часто связаны в виде строки, что облегчает их случайное раскрытие. Например, секрет может быть случайно записан в лог или стать частью сериализации json. Кроме того, сложнее определить, где в коде используются секретные данные, если все имеет тип string.

class MyDbConfiguration
{
    // 1. легко случайно раскрыть значение этого свойства
    // 2. Трудно понять, что эта строка является секретом
    public string ConnectionString { get; set; }
}

В большинстве случаев секретные данные предоставляются в открытом виде (переменные окружения, конфигурационный файл), поэтому нет необходимости защищать его в памяти. Цель состоит в том, чтобы усложнить разработчикам случайное раскрытие секретных данных, а не в том, чтобы защитить их. Решение состоит в том, чтобы создать простую обертку для строкового значения и не раскрывать никаких свойств, чтобы избежать раскрытия важных данных при сериализации . Также обертка не должна реализовывать ToString, чтобы избежать случайного раскрытия. Большинство приложений .NET полагаются на пакет Microsoft.Extensions.Configuration для конфигурации. Он может привязать значение конфигурации к любому типу при условии наличия совместимого TypeConverter`а.

Давайте создадим для наших секретных данных класс Secret и конвертер типа для него:

[TypeConverter(typeof(ConfigurationSecretTypeConverter))]
internal sealed class Secret
{
    // Не используйте System.String, так как некоторые сериализаторы могут сериализовать поля.
    // На данный момент System.Text.Json не поддерживает ReadOnlyMemory<char>, поэтому его нельзя сериализовать.
    private readonly ReadOnlyMemory<char> _data;

    public Secret(string value)
    {
        ArgumentException.ThrowIfNullOrEmpty(value);

        _data = value.ToCharArray();

        // Если вы хотите предотвратить перемещение строки в памяти и, соответственно, ее многократное копирование в память,
        // вы можете использовать Pinned Heap: https://github.com/dotnet/runtime/blob/main/docs/design/features/PinnedHeap.md
        // var data = GC.AllocateUninitializedArray<char>(value.Length, pinned: true);
        // value.AsSpan().CopyTo(data);
        // _data = data;

        // Также, если вы хотите что-то более безопасное, вы можете посмотреть на Microsoft.AspNetCore.DataProtection.Secret. Но это может быть сложнее
        // использовать с пакетом Microsoft.Extensions.Configuration. Действительно, Secret является одноразовым объектом, но использование IOptions<T> позволит // не утилизировать объект.
        // не утилизирует объект, поэтому вам нужно позаботиться о его утилизации самостоятельно.
        // https://github.com/dotnet/aspnetcore/blob/ea683686bfac765690cb6e40f6ba7198cae26e65/src/DataProtection/DataProtection/src/Secret.cs
    }

    public string Reveal() => string.Create(_data.Length, _data, (span, data) => data.Span.CopyTo(span));

    [Obsolete($"Use {nameof(Reveal)} instead")]
    public override string? ToString() => base.ToString();

    /// <summary>
    /// Разрешает Microsoft.Extensions.Configuration инстанцировать  <seealso cref="Secret" />
    /// из строки.
    /// </summary>
    private sealed class ConfigurationSecretTypeConverter : TypeConverter
    {
        public override bool CanConvertFrom(ITypeDescriptorContext? context, Type sourceType)
            => sourceType == typeof(string);

        public override bool CanConvertTo(ITypeDescriptorContext? context, [NotNullWhen(true)] Type? destinationType)
            => false;

        public override object? ConvertTo(ITypeDescriptorContext? context, CultureInfo? culture, object? value, Type destinationType)
            => throw new InvalidOperationException();

        public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
            => value is string { Length: > 0 } str ? new Secret(str) : null;
    }
}

Вот пример класса Secret в действии:

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddInMemoryCollection(new Dictionary<string, string?>
{
    ["UserName"] = "john",
    ["Password"] = "Pa$$w0rd",
});

builder.Services.Configure<SampleOptions>(builder.Configuration);
await using var app = builder.Build();

var configuration = app.Services.GetRequiredService<IOptions<SampleOptions>>().Value;
Console.WriteLine(configuration.UserName);

 // 👇 Используйте метод Reveal для получения фактического пароля
Console.WriteLine(configuration.Password?.Reveal());

class SampleOptions
{
    public string? UserName { get; set; }

     // 👇 Используйте тип Secret
    public Secret? Password { get; set; }
}

Вы также можете добавить несколько тестов, чтобы убедиться, что класс Secret работает так, как ожидается:

public sealed class SecretTests
{
    [Fact]
    public void RevealToString()
    {
        var secret = new Secret("foo");
        Assert.Equal("foo", secret.Reveal());
        Assert.NotEqual("foo", secret.ToString());
    }

    [Fact]
    public void SystemTestJsonDoesNotRevealValue()
    {
        var secret = new Secret("foo");
        var json = JsonSerializer.Serialize(secret);
        Assert.Equal("{}", json);
    }

    [Fact]
    public void SystemTestJsonDoesNotRevealValue_Field()
    {
        var secret = new Secret("foo");
        var options = new JsonSerializerOptions { IncludeFields = true };
        var json = JsonSerializer.Serialize(secret, options);
        Assert.Equal("{}", json);
    }

    [Fact]
    public void NewtonsoftJsonDoesNotRevealValue()
    {
        var secret = new Secret("foo");
        var json = Newtonsoft.Json.JsonConvert.SerializeObject(secret);
        Assert.Equal("{}", json);
    }

    [Fact]
    public void CanConvertFromString()
    {
        var secret = (Secret)TypeDescriptor.GetConverter(typeof(Secret)).ConvertFromString("foo");
        Assert.Equal("foo", secret.Reveal());
    }

    [Fact]
    public void TypeConverterToStringDoesNotRevealValue()
    {
        var secret = new Secret("foo");
        Assert.Throws<InvalidOperationException>(() => TypeDescriptor.GetConverter(typeof(Secret)).ConvertToString(secret));
    }

    [Fact]
    public async Task CanBindConfiguration()
    {
        var builder = WebApplication.CreateBuilder();
        builder.WebHost.UseSetting("Password", "Pa$$w0rd");
        builder.Services.Configure<SampleOptions>(builder.Configuration);
        await using var app = builder.Build();
        var configuration = app.Services.GetRequiredService<IOptions<SampleOptions>>().Value;

        Assert.Equal("Pa$$w0rd", configuration.Password.Reveal());
    }

    private class SampleOptions
    {
        public Secret? Password { get; set; }
    }
}

Оригинальную статью можно прочитать по ссылке.

В C#11 были добавлены шаблоны списков (List patterns). Шаблоны списков расширяют pattern matching для сопоставления последовательностей элементов в списке или массиве. Цель данной заметки не объяснить синтаксис, а разобраться, каким образом создать совместимый тип. Если вы не знакомы с pattern matching и с List patterns в частности, рекомендую прочитать статью в официальной документации Microsoft, где приведено достаточное количество примеров и исчерпывающей информации. Ниже представлены примеры List patterns:

var array = new[] { 1, 2, 3 };
_ = array is [1, 2, 3]; // Сопостовление коллекции содержащей 3 элемента со значениями 1,2,3.
_ = array is [1, _, 3]; // Сопостовление коллекции содержащей 3 элемента со значениями 1, любым числом, 3
_ = array is [var head, .. var tail]; // Сопастовление хотябы с 1 элементом (head).
                                      // хвост содержит элементы ([2, 3])

List patterns прекрасно работает с массивами и списками объектов List<T>, но что, если вы захотите использовать шаблоны списков со своими типами? В данной заметке я расскажу вам как создать тип Net совместимый с синтаксисом list patterns C#11.

Как создать тип, который совместим с list patterns?

Когда вы используете синтаксис list patterns, компилятор разворачивает его в более простой синтаксис. Следующий пример показывает во что разворачивается list patterns синтаксис на более низком уровне:

var array = new[] { 1, 2, 3 };

_ = array is [1, 2, 3];
 // Разворачивается компилятором в:
_ = array != null && array.Length == 3 && array[0] == 1 && array[1] == 2 && array[2] == 3;

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

Компилятор C# использует утиную типизацию, чтобы определить, совместим ли тип с шаблоном. Это означает, что вам не нужно реализовывать какие-либо интерфейсы или атрибуты. Компилятор проверит, есть ли у типа необходимые члены, и использует их. Вот список необходимых членов для поддержки синтаксиса list patterns:

var collection = new MyCollection();
_ = collection is [var head, .. var tail];

public class MyCollection
{
    // Получает количество элементов, содержащихся в коллекции.
    // Выберите одну из следующих сигнатур.
    // примечание: если присутствуют оба свойства, компилятор будет использовать Length
    public int Length { get; }
    public int Count { get; }

    // Индексатор, выберите одну из следующих сигнатур.
    // Возвращаемый тип может быть любым.
    // примечание: если присутствуют оба индексатора, компилятор будет использовать this[Index index]
    public object this[int index] => throw null;
    public object this[System.Index index] => throw null;

    // Выбирает одну из следующих сигнатур для поддержки slice pattern (...)
    // Тип возврата может быть любым.
    // Примечание: Если присутствуют оба метода, компилятор будет использовать this[System.Range index].
    public object this[System.Range index] => throw null;
    public object Slice(int start, int length) => throw null;
}

Вот пример совместимого типа:

var collection = new MyCollection();
collection.Add(1);
collection.Add(2);
collection.Add(3);
_ = collection is [var head, .. var tail];

public class MyCollection
{
    private readonly List<int> _items = new();

    public void Add(int item) => _items.Add(item);

    public int Length => _items.Count;

    public int this[Index index] => _items[index];

    public ReadOnlySpan<int> this[System.Range range]
        => CollectionsMarshal.AsSpan(_items)[range];
}

Официальная документация от Microsoft нам говорит следующее:

Метод Main — это точка входа приложения C#. (Библиотекам и службам точка входа в виде метода Main не требуется.) Когда приложение запускается, первым вызывается именно метод Main.

Официальная Документация

На самом деле метод Main может быть не первым методом сборки, который будет выполняться при запуске приложения. Существуют различные методы, которые могут выполняться перед методом Main. В этом посте я покажу вам различные способы выполнения кода перед методом Main. Я не говорю, что так нужно делать, только то, что это возможно 😃

Статический конструктор

Статический конструктор используется для инициализации любых статических данных или для выполнения определенного действия, которое необходимо выполнить только один раз. Он вызывается автоматически перед созданием первого экземпляра или обращением к любым статическим элементам. Итак, статический конструктор вызывается перед методом Main.

class Program
{
    static Program() => Console.WriteLine("Main еще не написали");
    static void Main() => Console.WriteLine("Привет мир!");
}

Инициализаторы модулей

Инициализаторы модулей позволяют библиотекам выполнять активную однократную инициализацию при загрузке без необходимости явного вызова пользователем чего-либо. Когда среда выполнения загружает модуль (DLL), она вызывает методы инициализации модуля перед выполнением любого кода из этого модуля.

using System.Runtime.CompilerServices;
class Initializer
{
    // Статический конструктор запускается перед инициализатором модуля
    static Initializer() => Console.WriteLine("Статический конструктор.");
    [ModuleInitializer]
    public static void Init1() => Console.WriteLine("Инициализатор модуля 1");
    [ModuleInitializer]
    public static void Init2() => Console.WriteLine("Инициализатор модуля 2");
}
class Program
{
    static void Main() => Console.WriteLine("Привет мир!");
}

Хуки Startup

Переменная среды DOTNET_STARTUP_HOOKS может использоваться для указания списка управляемых сборок, содержащих тип StartupHook с общедоступным методом static void Initialize(). Каждый из этих методов будет вызываться в указанном порядке перед точкой входа Main.

class StartupHook
{
    static StartupHook() => Console.WriteLine("Статический конструктор.");

    // Запустите приложение с переменной окружения
    // DOTNET_STARTUP_HOOKS=myapp.dll (используйте полный путь к сборке)
    public static void Initialize() => Console.WriteLine("Startup хук");
}

class Program
{
    static void Main() => Console.WriteLine("Привет мир!");
}

Данная статья является переводом статьи "Executing code before Main in .NET"