Минимальные API — это тип API в ASP.NET Core, который включает минимум файлов, функций и зависимостей. Минимальные API позволяют создавать полнофункциональные конечные точки REST с минимальным кодированием и настройкой. Одним из многих новых улучшений в ASP.NET Core 7 является поддержка привязки параметров в минимальных API.
Цель этого поста — дать вам преимущество в работе с привязкой параметров в минимальных API. Чтобы использовать примеры кода, представленные в этой статье, в вашей системе должна быть установлена Visual Studio 2022. Если у вас еще нет копии, вы можете скачать Visual Studio 2022 здесь.
Создайте минимальный проект веб-API в Visual Studio 2022.
Прежде всего, давайте создадим проект ASP.NET Core в Visual Studio 2022. Выполните следующие действия:
- Запустите интегрированную среду разработки Visual Studio 2022.
- Нажмите «Создать новый проект».
- В окне «Создать новый проект» выберите «ASP.NET Core Web API» из списка отображаемых шаблонов.
- Нажмите “Далее.
- В окне «Настроить новый проект» укажите имя и расположение нового проекта.
- При желании установите флажок «Поместить решение и проект в один каталог», в зависимости от ваших предпочтений.
- Нажмите “Далее.
- В показанном ниже окне «Дополнительная информация» снимите флажок «Использовать контроллеры…», поскольку в этом примере мы будем использовать минимальное количество API. Оставьте для параметра «Тип аутентификации» значение «Нет» (по умолчанию). Также снимите флажки «Настроить для HTTPS» и «Включить поддержку Open API». Наконец, убедитесь, что флажок «Включить Docker» не установлен, так как мы не будем использовать Docker здесь.
- Щелкните Создать.
Мы будем использовать этот проект веб-API ASP.NET Core для работы с привязкой параметров в следующих разделах.
Что такое привязка параметров?
Привязка параметров включает сопоставление входящих данных HTTP-запроса с параметрами метода действия, что позволяет разработчикам обрабатывать запросы и отвечать структурированным и эффективным образом.
Привязка параметров упрощает процесс обработки HTTP-запросов и позволяет разработчикам сосредоточиться на построении логики своих конечных точек API. Минимальные API-интерфейсы в ASP.NET Core 7 предлагают несколько типов привязки параметров, включая FromQuery, FromRoute, FromHeader и FromBody.
Зачем использовать привязку параметров?
Вот несколько причин, по которым вам следует использовать привязку параметров в минимальных API.
- Чтобы упростить код: Используя привязку параметров, разработчики могут сократить шаблонный код, необходимый для обработки входящих HTTP-запросов. Вместо того, чтобы вручную анализировать параметры строки запроса, данные маршрута и тело запроса, привязка параметров позволяет разработчикам определять параметры метода действия, а платформа автоматически обрабатывает процесс привязки.
- Чтобы улучшить ремонтопригодность кода: Используя привязку параметров в минимальных API-интерфейсах, разработчики могут создавать более удобный для сопровождения код, который легче понять и модифицировать с течением времени. Процесс связывания стандартизирован и предсказуем, что упрощает для разработчиков понимание того, как данные передаются между клиентом и сервером.
- Чтобы повысить производительность приложения: Привязка параметров также может помочь повысить производительность за счет сокращения ненужной обработки данных в приложении. Например, привязывая тело запроса к определенному типу параметра, платформа может избежать накладных расходов на синтаксический анализ и десериализацию всего тела запроса, вместо этого сосредоточившись только на релевантных данных, необходимых приложению.
- Для обработки сложных типов данных: Привязку параметров можно использовать для обработки сложных типов данных, таких как вложенные объекты, массивы и коллекции. Используя встроенные механизмы для привязки сложных типов данных, разработчики могут создавать API-интерфейсы, которые работают с широким спектром форматов данных, без необходимости написания дополнительного кода.
Как работает привязка параметров?
Привязка параметров в минимальных API-интерфейсах в ASP.NET Core 7 работает так же, как и в традиционных приложениях ASP.NET Core. Когда клиент делает HTTP-запрос к минимальному API, данные запроса автоматически сопоставляются с параметрами метода действия на основе имен и типов параметров. По умолчанию платформа использует основанный на соглашении подход для автоматического сопоставления данных запроса с параметрами метода действия, но разработчики также могут использовать явную привязку параметров, чтобы получить больший контроль над этим процессом.
Привязка параметров к строкам запроса
Чтобы использовать привязку параметров в минимальных API-интерфейсах в ASP.NET Core 7, разработчикам необходимо определить методы действий, которые принимают параметры. Например, следующий фрагмент кода определяет минимальную конечную точку API, которая принимает параметр из строки запроса.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/hello", ([FromQuery] string name) =>
{
return $"Hello {name}";
});
app.Run();
В этом примере [FromQuery] Атрибут указывает платформе связать параметр имени со значением параметра строки запроса имени в HTTP-запросе.
Привязка параметров с внедрением зависимостей
В ASP.NET Core 7 вы можете воспользоваться внедрением зависимостей для привязки параметров в методах действий ваших контроллеров API. Если тип настроен как служба, вам больше не нужно добавлять [FromServices] атрибут к параметрам вашего метода. Рассмотрим следующий фрагмент кода.
[Route("[controller]")]
[ApiController]
public class MyDemoController : ControllerBase
{
public ActionResult Get(IDateTime dateTime) => Ok(dateTime.Now);
}
Если тип настроен как служба, вам не нужно использовать [FromServices] атрибут для привязки параметров. Вместо этого вы можете использовать следующий фрагмент кода для привязки параметров с помощью внедрения зависимостей.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IDateTime, SystemDateTime>();
var app = builder.Build();
app.MapGet("https://www.infoworld.com/", (IDateTime dateTime) => dateTime.Now);
app.MapGet("/demo", ([FromServices] IDateTime dateTime) => dateTime.Now);
app.Run();
Явная привязка параметров в минимальных API
Явная привязка параметров в минимальных API-интерфейсах в ASP.NET Core 7 — это метод, который позволяет разработчикам лучше контролировать процесс привязки, явно указывая источник данных для данного параметра.
Это полезно в ситуациях, когда поведение привязки нельзя вывести только из имени или типа параметра. В минимальных API-интерфейсах ASP.NET Core 7 разработчики могут использовать следующие атрибуты, чтобы явно указать источник данных для параметра:
- [FromQuery] указывает, что значение параметра должно быть получено из строки запроса HTTP.
- [FromRoute] указывает, что значение параметра должно быть получено из данных маршрута HTTP-запроса.
- [FromHeader] указывает, что значение параметра должно быть взято из заголовка HTTP-запроса.
- [FromBody] указывает, что значение параметра должно исходить из тела HTTP-запроса.
Например, рассмотрим следующую минимальную конечную точку API, которая принимает экземпляр типа Author в тексте запроса.
app.MapPost("/demo", ([FromBody] Author author) =>
{
// Write your code here to process the author object
});
В этом случае [FromBody] Атрибут указывает платформе привязать параметр к данным в теле запроса. Если этот атрибут не указан, платформа попытается связать параметр с использованием других доступных источников, таких как строка запроса или данные маршрута, что, вероятно, не то, что нам нужно в этом сценарии.
Обратите внимание, что вы также можете использовать [AsParameters] для сопоставления параметров запроса непосредственно с объектом без использования методов BindAsync или TryParse.
app.MapGet("/display", ([AsParameters] Author author) =>
{
return $"First Name: {author.FirstName}, Last Name: {author.LastName}";
});
Пользовательская привязка модели в минимальных API
Привязка пользовательской модели позволяет разработчикам определять собственную логику привязки для сложных типов данных или сценариев, которые не могут быть обработаны механизмами привязки по умолчанию. Пользовательская привязка особенно полезна при работе с API, которые требуют преобразования или нормализации данных, прежде чем данные смогут использоваться приложением.
В минимальных API-интерфейсах ASP.NET Core 7 пользовательская привязка модели достигается путем реализации интерфейса IModelBinder или использования интерфейса IModelBinderProvider для предоставления пользовательской реализации интерфейса IModelBinder для определенного типа данных.
Чтобы создать настраиваемую привязку модели, необходимо реализовать интерфейс IModelBinder и переопределить метод BindModelAsync. Этот метод принимает параметр BindingContext, который содержит информацию о запросе и привязываемой модели.
В методе BindModelAsync можно выполнить любое необходимое преобразование данных или проверку перед возвратом связанной модели. Ниже приведен пример пользовательского связывателя модели, который связывает входящие полезные данные JSON с объектом Customer.
public class CustomerModelBinder : IModelBinder
{
public async Task BindModelAsync(ModelBindingContext bindingContext)
{
var json = await new
StreamReader(bindingContext.HttpContext.Request.Body).
ReadToEndAsync();
var customer = JsonConvert.DeserializeObject<Customer>(json);
bindingContext.Result = ModelBindingResult.Success(customer);
}
}
В этом примере класс CustomerModelBinder реализует интерфейс IModelBinder и предоставляет пользовательскую реализацию метода BindModelAsync. Метод считывает полезные данные JSON из тела HTTP-запроса и десериализует их в объект Customer с помощью библиотеки Newtonsoft.Json. Результирующий объект Customer затем возвращается как успешный ModelBindingResult.
Чтобы использовать это пользовательское связывание модели в минимальной конечной точке API, вы можете использовать [ModelBinder] атрибут параметра.
app.MapPost("/demo", ([ModelBinder(typeof(CustomerModelBinder))] Customer customer) =>
{
// Write your code here to process the Customer object
});
В предыдущем примере кода [ModelBinder] указывает, что параметр Customer должен быть связан с использованием класса CustomerModelBinder.
Привязка параметров упрощает написание кода для обработки HTTP-запросов. Это позволяет разработчикам легче обрабатывать сложные типы данных, упрощая код и улучшая его ремонтопригодность, а также выстраивая логику своих конечных точек API. Используя привязку параметров в минимальных API-интерфейсах, разработчики могут создавать эффективные, удобные в сопровождении и масштабируемые API-интерфейсы, отвечающие потребностям их приложений и пользователей.
