aspnetcore/mvc/advanced/custom-model-binding.md
:::moniker range=">= aspnetcore-3.0"
By Kirk Larkin
Model binding allows controller actions to work directly with model types (passed in as method arguments), rather than HTTP requests. Mapping between incoming request data and application models is handled by model binders. Developers can extend the built-in model binding functionality by implementing custom model binders (though typically, you don't need to write your own provider).
View or download sample code (how to download)
The default model binders support most of the common .NET Core data types and should meet most developers' needs. They expect to bind text-based input from the request directly to model types. You might need to transform the input prior to binding it. For example, when you have a key that can be used to look up model data. You can use a custom model binder to fetch data based on the key.
<!-- Duplicated in uid: mvc/models/model-binding -->Model binding uses specific definitions for the types it operates on. A simple type is converted from a single string using xref:System.ComponentModel.TypeConverter or a TryParse method. A complex type is converted from multiple input values. The framework determines the difference based on the existence of a TypeConverter or TryParse. We recommend creating a type converter or using TryParse for a string to SomeType conversion that doesn't require external resources or multiple inputs.
See Simple types for a list of types that the model binder can convert from strings.
Before creating your own custom model binder, it's worth reviewing how existing model binders are implemented. Consider the xref:Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinder which can be used to convert base64-encoded strings into byte arrays. The byte arrays are often stored as files or database BLOB fields.
Base64-encoded strings can be used to represent binary data. For example, an image can be encoded as a string. The sample includes an image as a base64-encoded string in Base64String.txt.
ASP.NET Core MVC can take a base64-encoded string and use a ByteArrayModelBinder to convert it into a byte array. The xref:Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinderProvider maps byte[] arguments to ByteArrayModelBinder:
public IModelBinder GetBinder(ModelBinderProviderContext context)
{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
if (context.Metadata.ModelType == typeof(byte[]))
{
var loggerFactory = context.Services.GetRequiredService<ILoggerFactory>();
return new ByteArrayModelBinder(loggerFactory);
}
return null;
}
When creating your own custom model binder, you can implement your own IModelBinderProvider type, or use the xref:Microsoft.AspNetCore.Mvc.ModelBinderAttribute.
The following example shows how to use ByteArrayModelBinder to convert a base64-encoded string to a byte[] and save the result to a file:
You can POST a base64-encoded string to the previous API method using a tool like curl.
As long as the binder can bind request data to appropriately named properties or arguments, model binding will succeed. The following example shows how to use ByteArrayModelBinder with a view model:
In this section, we'll implement a custom model binder that:
The following sample uses the ModelBinder attribute on the Author model:
In the preceding code, the ModelBinder attribute specifies the type of IModelBinder that should be used to bind Author action parameters.
The following AuthorEntityBinder class binds an Author parameter by using the author route value to fetch the entity from a data source with Entity Framework Core:
[!NOTE] The preceding
AuthorEntityBinderclass is intended to illustrate a custom model binder. The class isn't intended to illustrate best practices for a lookup scenario. For lookup, bind theauthorparameter directly and query the database in an action method. This approach separates model binding failures fromNotFoundcases.
The following code shows how to use the AuthorEntityBinder in an action method:
The ModelBinder attribute can be used to apply the AuthorEntityBinder to parameters that don't use default conventions:
In this example, since the route parameter name (id) doesn't match the action method parameter name (author), the Name property on the ModelBinder attribute is used to specify which route value to bind. Both the controller and action method are simplified compared to looking up the entity in the action method. The logic to fetch the author using Entity Framework Core is moved to the model binder. This can be a considerable simplification when you have several methods that bind to the Author model.
You can apply the ModelBinder attribute to individual model properties (such as on a viewmodel) or to action method parameters to specify a certain model binder or model name for just that type or action.
Instead of applying an attribute, you can implement IModelBinderProvider. This is how the built-in framework binders are implemented. When you specify the type your binder operates on, you specify the type of argument it produces, not the input your binder accepts. The following binder provider works with the AuthorEntityBinder. When it's added to MVC's collection of providers, you don't need to use the ModelBinder attribute on Author or Author-typed parameters.
[!NOTE] The preceding code returns a
BinderTypeModelBinder.BinderTypeModelBinderacts as a factory for model binders and provides dependency injection (DI). TheAuthorEntityBinderrequires DI to access EF Core. UseBinderTypeModelBinderif your model binder requires services from DI.
To use a custom model binder provider, add it in ConfigureServices:
When evaluating model binders, the collection of providers is examined in order. The first provider that returns a binder that matches the input model is used. Adding your provider to the end of the collection may thus result in a built-in model binder being called before your custom binder has a chance. In this example, the custom provider is added to the beginning of the collection to ensure it's always used for Author action arguments.
Binding to different models of derived types is known as polymorphic model binding. Polymorphic custom model binding is required when the request value must be bound to the specific derived model type. Polymorphic model binding:
However, if an app requires polymorphic model binding, an implementation might look like the following code:
Custom model binders:
:::moniker-end :::moniker range="< aspnetcore-3.0"
By Steve Smith
Model binding allows controller actions to work directly with model types (passed in as method arguments), rather than HTTP requests. Mapping between incoming request data and application models is handled by model binders. Developers can extend the built-in model binding functionality by implementing custom model binders (though typically, you don't need to write your own provider).
View or download sample code (how to download)
The default model binders support most of the common .NET Core data types and should meet most developers' needs. They expect to bind text-based input from the request directly to model types. You might need to transform the input prior to binding it. For example, when you have a key that can be used to look up model data. You can use a custom model binder to fetch data based on the key.
Model binding uses specific definitions for the types it operates on. A simple type is converted from a single string in the input. A complex type is converted from multiple input values. The framework determines the difference based on the existence of a TypeConverter. We recommend you create a type converter if you have a simple string -> SomeType mapping that doesn't require external resources.
Before creating your own custom model binder, it's worth reviewing how existing model binders are implemented. Consider the xref:Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinder which can be used to convert base64-encoded strings into byte arrays. The byte arrays are often stored as files or database BLOB fields.
Base64-encoded strings can be used to represent binary data. For example, an image can be encoded as a string. The sample includes an image as a base64-encoded string in Base64String.txt.
ASP.NET Core MVC can take a base64-encoded string and use a ByteArrayModelBinder to convert it into a byte array. The xref:Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinderProvider maps byte[] arguments to ByteArrayModelBinder:
public IModelBinder GetBinder(ModelBinderProviderContext context)
{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
if (context.Metadata.ModelType == typeof(byte[]))
{
return new ByteArrayModelBinder();
}
return null;
}
When creating your own custom model binder, you can implement your own IModelBinderProvider type, or use the xref:Microsoft.AspNetCore.Mvc.ModelBinderAttribute.
The following example shows how to use ByteArrayModelBinder to convert a base64-encoded string to a byte[] and save the result to a file:
You can POST a base64-encoded string to the previous api method using a tool like curl.
As long as the binder can bind request data to appropriately named properties or arguments, model binding will succeed. The following example shows how to use ByteArrayModelBinder with a view model:
In this section we'll implement a custom model binder that:
The following sample uses the ModelBinder attribute on the Author model:
In the preceding code, the ModelBinder attribute specifies the type of IModelBinder that should be used to bind Author action parameters.
The following AuthorEntityBinder class binds an Author parameter by fetching the entity from a data source using Entity Framework Core and an author route value:
[!NOTE] The preceding
AuthorEntityBinderclass is intended to illustrate a custom model binder. The class isn't intended to illustrate best practices for a lookup scenario. For lookup, bind theauthorparameter directly and query the database in an action method. This approach separates model binding failures fromNotFoundcases.
The following code shows how to use the AuthorEntityBinder in an action method:
The ModelBinder attribute can be used to apply the AuthorEntityBinder to parameters that don't use default conventions:
In this example, since the route parameter name (id) doesn't match the action method parameter name (author), the Name property on the ModelBinder attribute is used to specify which route value to bind. Both the controller and action method are simplified compared to looking up the entity in the action method. The logic to fetch the author using Entity Framework Core is moved to the model binder. This can be a considerable simplification when you have several methods that bind to the Author model.
You can apply the ModelBinder attribute to individual model properties (such as on a viewmodel) or to action method parameters to specify a certain model binder or model name for just that type or action.
Instead of applying an attribute, you can implement IModelBinderProvider. This is how the built-in framework binders are implemented. When you specify the type your binder operates on, you specify the type of argument it produces, not the input your binder accepts. The following binder provider works with the AuthorEntityBinder. When it's added to MVC's collection of providers, you don't need to use the ModelBinder attribute on Author or Author-typed parameters.
[!NOTE] The preceding code returns a
BinderTypeModelBinder.BinderTypeModelBinderacts as a factory for model binders and provides dependency injection (DI). TheAuthorEntityBinderrequires DI to access EF Core. UseBinderTypeModelBinderif your model binder requires services from DI.
To use a custom model binder provider, add it in ConfigureServices:
When evaluating model binders, the collection of providers is examined in order. The first provider that returns a binder is used. Adding your provider to the end of the collection may result in a built-in model binder being called before your custom binder has a chance. In this example, the custom provider is added to the beginning of the collection to ensure it's used for Author action arguments.
Binding to different models of derived types is known as polymorphic model binding. Polymorphic custom model binding is required when the request value must be bound to the specific derived model type. Polymorphic model binding:
However, if an app requires polymorphic model binding, an implementation might look like the following code:
Custom model binders:
:::moniker-end