Minimal APIs are a type of API in ASP.NET Core that includes a minimum of files, features, and dependencies. Minimal APIs allow you to create fully functional REST endpoints with minimal coding and configuration. One of the many new improvements in ASP.NET Core 7 is its support for parameter binding in minimal APIs.
The goal of this post is to give you a head start on working with parameter binding in minimal APIs. To use the code samples provided in this article, you must have Visual Studio 2022 installed on your system. If you don’t already have a copy, you can download Visual Studio 2022 here.
Create a minimal web API project in Visual Studio 2022
First, let’s create an ASP.NET Core project in Visual Studio 2022. Follow these steps:
- Start the Visual Studio 2022 IDE.
- Click “Create new project”.
- In the “Create New Project” window, select “ASP.NET Core Web API” from the list of templates displayed.
- Click Next.
- In the “Set up your new project” window, specify the name and location of the new project.
- Optionally, check the “Place solution and project in the same directory” checkbox, depending on your preferences.
- Click Next.
- In the “Additional Information” window shown below, uncheck the checkbox that says “Use Controllers…” as we will be using minimal APIs in this example. Leave the “Authentication Type” set to “None” (default). Also uncheck the “Configure for HTTPS” and “Enable open API support” checkboxes. Finally, make sure the “Enable Docker” checkbox is not checked, as we won’t be using Docker here.
- Click Create.
We’ll use this ASP.NET Core Web API project to work with parameter binding in the sections below.
What is parameter binding?
Parameter binding involves mapping data from incoming HTTP requests to action method parameters, allowing developers to process requests and respond in a structured and efficient manner.
Parameter binding simplifies the process of handling HTTP requests and allows developers to focus on building the logic for their API endpoints. The minimal APIs in ASP.NET Core 7 offer several types of parameter binding, including FromQuery, FromRoute, FromHeader, and FromBody.
Why use parameter binding?
Here are some reasons why you should use parameter binding in minimal APIs.
- To simplify the code: Using parameter binding, developers can reduce the boilerplate code needed to handle incoming HTTP requests. Instead of manually parsing query string parameters, route data, and request bodies, parameter binding allows developers to define action method parameters and have the framework handle the binding process. automatically.
- To improve code maintainability: By leveraging parameter binding in minimal APIs, developers can create more maintainable code that is easier to understand and modify over time. The binding process is standardized and predictable, making it easy for developers to reason out how data is transmitted between client and server.
- To improve application performance: Parameter binding can also help improve performance by reducing unnecessary data processing in your application. For example, by binding a request body to a specific parameter type, the framework can avoid the overhead of parsing and deserializing the entire request body, instead focusing only on the relevant data needed by the application.
- To handle complex data types: Parameter binding can be used to handle complex data types such as nested objects, arrays, and collections. By taking advantage of built-in mechanisms for binding complex data types, developers can create APIs that address a wide range of data formats without having to write additional code.
How does parameter binding work?
Parameter binding in minimal APIs in ASP.NET Core 7 works similar to traditional ASP.NET Core apps. When a client makes an HTTP request to a minimal API, the request data is automatically mapped to the action method parameters based on the parameter names and types. By default, the framework uses a convention-based approach to automatically map request data to action method parameters, but developers can also use explicit parameter binding to gain more control over this process.
Parameter binding with query strings
To use parameter binding in minimal APIs in ASP.NET Core 7, developers must define action methods that accept parameters. For example, the following code snippet defines a minimal API endpoint that accepts a query string parameter.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/hello", ([FromQuery] string name) =>
{
return $"Hello {name}";
});
app.Run();
In this example, the [FromQuery] The attribute tells the framework to bind the name parameter to the value of the name query string parameter in the HTTP request.
Parameter binding with dependency injection
With ASP.NET Core 7, you can take advantage of dependency injection to bind parameters in the action methods of your API controllers. If the type is configured as a service, you no longer need to add the [FromServices] attribute to the parameters of your method. Consider the following code snippet.
[Route("[controller]")]
[ApiController]
public class MyDemoController : ControllerBase
{
public ActionResult Get(IDateTime dateTime) => Ok(dateTime.Now);
}
If the type is configured as a service, you don’t need to use the [FromServices] attribute to bind parameters. Instead, you can use the following code snippet to bind parameters using dependency injection.
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();
Explicit parameter binding in minimal APIs
Explicit parameter binding in minimal APIs in ASP.NET Core 7 is a technique that allows developers to have more control over the binding process by explicitly specifying the data source for a given parameter.
This is useful in situations where the binding behavior cannot be inferred from the name or type of the parameter alone. In the ASP.NET Core 7 minimal APIs, developers can use the following attributes to explicitly specify the data source for a parameter:
- [FromQuery] specifies that the parameter value should be derived from the HTTP query string.
- [FromRoute] specifies that the parameter value should be derived from the route data of the HTTP request.
- [FromHeader] specifies that the parameter value should be taken from the HTTP request header.
- [FromBody] specifies that the parameter value must come from the body of the HTTP request.
For example, consider the following minimal API endpoint that accepts an instance of type Author in the request body.
app.MapPost("/demo", ([FromBody] Author author) =>
{
// Write your code here to process the author object
});
In this case, the [FromBody] The attribute tells the framework to bind the parameter to the data in the request body. If this attribute is not specified, the framework will attempt to bind the parameter using other available sources, such as a query string or path data, which is probably not what we want in this scenario.
Note that you can also use the [AsParameters] attribute to assign query parameters directly to an object without having to use the BindAsync or TryParse methods.
app.MapGet("/display", ([AsParameters] Author author) =>
{
return $"First Name: {author.FirstName}, Last Name: {author.LastName}";
});
Custom model binding in minimal APIs
Custom model binding allows developers to define their own binding logic for complex data types or scenarios that the default binding mechanisms cannot handle. Custom binding is especially useful when working with APIs that require data transformation or normalization before the application can use it.
In the ASP.NET Core 7 minimal APIs, custom model binding is accomplished by implementing the IModelBinder interface or by using the IModelBinderProvider interface to provide a custom implementation of the IModelBinder interface for a specific data type.
To create a custom model binder, you must implement the IModelBinder interface and override the BindModelAsync method. This method takes a BindingContext parameter, which contains information about the request and the model being bound.
In the BindModelAsync method, you can perform any necessary transformation or data validation before returning the bound model. Below is an example of a custom model binder that binds an incoming JSON payload to a Customer object.
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);
}
}
In this example, the CustomerModelBinder class implements the IModelBinder interface and provides a custom implementation of the BindModelAsync method. The method reads the JSON payload from the HTTP request body and deserializes it into a Client object using the Newtonsoft.Json library. The resulting Customer object is returned as a successful ModelBindingResult.
To use this custom model binder on a minimal API endpoint, you can use the [ModelBinder] attribute in the parameter.
app.MapPost("/demo", ([ModelBinder(typeof(CustomerModelBinder))] Customer customer) =>
{
// Write your code here to process the Customer object
});
In the code example above, the [ModelBinder] The attribute specifies that the Customer parameter should be bound using the CustomerModelBinder class.
Parameter binding simplifies writing code to handle HTTP requests. It enables developers to more easily handle complex data types, while simplifying code and improving code maintainability, while building the logic for your API endpoints. By leveraging parameter binding in minimal APIs, developers can create efficient, maintainable, and scalable APIs that meet the needs of their applications and users.
Copyright © 2023 IDG Communications, Inc.
Be First to Comment