ApiMultipartFormDataFormatter

A. Description:

Handle data uploaded from client using multipart/form-data Content-Type. Previously, to handle multipart/form-data in WEB API 2, there is just only one possible solution mentioned in this topic.
This library helps developers to serialize information into view model in ASP.NET WEB API 2 just like ASP.Net does (please refer this tutorial).
Developers can re-use WEB API 2 Data annotation classes without repeating themselves doing manual data validation.

B. Implementation:

I. Installation:

You can choose one of following source to install nuget package into your project:
- Nuget (Stable releases)
- MyGet (nightly builds)

II. Formatter registration:

ASP.Net Framework

Please select one of the following implementation below for WebApiConfig.cs or Startup.cs:

WITHOUT dependency injection

public static void Register(HttpConfiguration config)
{
    // Web API configuration and services

    // Web API routes
    config.MapHttpAttributeRoutes();

    config.Routes.MapHttpRoute(
        "DefaultApi",
        "api/{controller}/{id}",
        new {id = RouteParameter.Optional}
    );

    config.Formatters.Add(new MultipartFormDataFormatter());
}

WITH dependency injection

public static void Register(HttpConfiguration config)
{
    // Web API configuration and services

    // Web API routes
    config.MapHttpAttributeRoutes();

    config.Routes.MapHttpRoute(
        "DefaultApi",
        "api/{controller}/{id}",
        new {id = RouteParameter.Optional}
    );
    var containerBuilder = new ContainerBuilder();

    // Register formatter as a single instance in the system.
    containerBuilder.RegisterType<MultipartFormDataFormatter>()
        .InstancePerLifetimeScope();

    var container = containerBuilder.Build();
    config.DependencyResolver = new AutofacWebApiDependencyResolver(container);

    // Register multipart/form-data formatter.
    var instance =
        (MultipartFormDataFormatter) config.DependencyResolver.GetService(typeof(MultipartFormDataFormatter));

    config.Formatters.Add(instance);
}

ASP.Net Core (>= 2.2)

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        //...
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers(options =>
            {
                //..
                options.InputFormatters.Add(new MultipartFormDataFormatter());
            });


    }
}

III. API Controller

ASP.NET Framework

[RoutePrefix("api/account")]
public class ApiAccountController : ApiController
{
    [Route("register")]
    [HttpPost]
    public HttpResponseMessage Register(AccountRegistrationViewModel parameters)
    {
        if (parameters == null)
        {
            parameters = new AccountRegistrationViewModel();
            Validate(parameters);
        }

        if (!ModelState.IsValid)
        {
            return Request.CreateResponse(HttpStatusCode.BadRequest);
        }

        return Request.CreateResponse(HttpStatusCode.OK);
    }
}

ASP.NET Core

[Route("api/upload")]
[ApiController]
public class ApiUploadController : Controller, IUploadController
{
    /// <summary>
    ///     Upload attachment to service end-point.
    /// </summary>
    /// <returns></returns>
    [HttpPost("")]
    public IActionResult BasicUpload([FromBody] UploadRequestViewModel model)
    {
        if (model == null)
        {
            model = new UploadRequestViewModel();
            TryValidateModel(model);
        }

        if (!ModelState.IsValid)
            return BadRequest(ModelState);


        return Ok(new UploadResponseViewModel(model));
    }
}

Start posting a multipart/form-data to your WEB API project and enjoy.
NOTE: In ASP.NET Core, you have to mark your controller with [ApiController] in order to make this plugin works. Otherwise, it doesn't.

C. HttpFile or HttpFileBase usage:

To specify a parameter to be a file in a ViewModel class, please use HttpFile or HttpFileBase class. HttpFile and HttpFileBase are treated as HttpPostedFileBase class in ASP.NET MVC.
Below is the example of HttpFile and HttpFileBase usage:

public class Category
{
	public int Id { get; set; }

	public List<Photo> Photos { get; set; }
}

public class AccountRegistrationViewModel
{
  /// <summary>
  /// Account owner.
  /// </summary>
  [Required]
  public Owner Owner { get; set; }

  /// <summary>
  /// User age.
  /// </summary>
  [Required]
  public int Age { get; set; }

  /// <summary>
  /// Account photo.
  /// </summary>
  [Required]
  public HttpFile Photo { get; set; }

  [Required]
  public List<HttpFileBase> Photos { get; set; }
}

IV. Data serializer customization with `IModelBinderService`

(Previously IMultiPartFormDataModelBinderService)

~~In version 2.0.0, this plugin uses IMultiPartFormDataModelBinderService to help developer override multpart-form/data parameter serialization.~~
From version 3.0.0, this plugin uses IModelBinderService to serialize data read from MultipartFormDataContent stream.
This helps developers to initialize Data type that has not been recoginized by ASP.NET Web API (Mostly about custom classes or data type).
For data that should be skipped analyzing, please throw UnhandledParameterException in BuildModelAsync function.
Below is an example of IModelBinderService implementation that can be found in project source code.

public class GuidModelBinderService : IModelBinderService
{
    #region Methods

    public Task<object> BuildModelAsync(Type propertyType, object value,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // Get property type.
        var underlyingType = Nullable.GetUnderlyingType(propertyType);

        // Property is GUID.
        if (propertyType == typeof(Guid) && Guid.TryParse(value.ToString(), out var guid))
            return Task.FromResult((object) guid);

        if (underlyingType == typeof(Guid))
        {
            if (Guid.TryParse(value?.ToString(), out guid))
                return Task.FromResult((object)guid);

            return Task.FromResult(default(object));
        }

        throw new UnhandledParameterException();
    }


    #endregion
}

IModelBinderService can be registered in DI Frameworks such as (AutoFac, Ninject, ...). This requires MultipartFormDataFormatter to be registered in DI Frameworks also. Example:

    // ...
    containerBuilder.RegisterType<GuidModelBinderService>()
                    .AsImplementedInterfaces()
                    .SingleInstance();
    // ...

IModelBinderService can be registered DIRECTLY while initializing MultipartFormDataFormatter object.

    config.Formatters.Add(new MultipartFormDataFormatter(
                    new IModelBinderService[]
                {
                    new GuidModelBinderService()
                }));

BY DEFAULT, MultipartFormDataFormatter is registered with a list of default services WHEN NO ModelBinderService is specified:

        public MultipartFormDataFormatter(IEnumerable<IModelBinderService> modelBinderServices = null)
        {
            _modelBinderServices = modelBinderServices?.ToArray();

            if (_modelBinderServices == null || _modelBinderServices.Length < 1)
            {
                _modelBinderServices = new IModelBinderService[]
                {
                    new DefaultMultiPartFormDataModelBinderService(),
                    new GuidModelBinderService(),
                    new EnumModelBinderService(),
                    new HttpFileModelBinderService()
                };
            }


            // Register multipart/form-data as the supported media type.
            SupportedMediaTypes.Add(new MediaTypeHeaderValue(SupportedMediaType));
        }

VI. Examples:

You can refer to this project for further information of how to implement ASP Web API 2 project with this plugin.

VII. Limitation:

Currently, this formatter cannot deal with interfaces such as: IAccount, IList, IEnumerable, ... To use it with a collection, please specify : List, Enumerable, ....
For a collection, please use List, Enumerable, ... instead of [] (array). This feature will be updated later.

VIII. Change logs:

3.0.0:
- ASP.Net Core supported.
- Provided HttpFile and HttpFileBase support (previously HttpFile only). HttpFileBase is recommended since it reads data using stream instead of convert data into bytes array. Please refer discussion for further information.
  - (Thank Driedas for his pull request)
- Replaced ~~IMultiPartFormDataModelBinderService~~ with IModelBinderService for custom data serialization. Therefore, IModelBinderService classes can be registered to handle custom data that plugin cannot handled.
2.1.0:
- Merge pull request 6 created by everfrown which supported extended data types binding such as:
  - enum (string or number)
  - guid
  - and nullable value types
- Removed ApiMultipartFormDataFormatter.cs class. Please use MultipartFormDataFormatter.cs instead.
1.0.4:
- Fixed bug #3 : Bad request while trying casting string to GUID
- Added IMultiPartFormDataModelBinderService for intercepting model serialization.
- ApiMultipartFormDataFormatter now is obsoleted. An exception is thrown if this class is used. Please using MultipartFormDataFormatter instead.
- FindContentDispositionParametersInterceptor: Allow developer to custmize how parameter will be serialized. Please take a look at MultipartFormDataFormatter.cs
1.0.3:
- Prevent dependencies such as NewtonSoft.Json, ... from being compiled and included in release nuget package. Therefore, the package size is smaller.
- Prevent dependencies from being removed when ApiMultipartFormDataFormatter nuget is uninstalled.
1.0.1:
- Fixed issue about list serialization, mentioned here
1.0.2:
- Incorrect release version. Please skip this.
1.0.0:
- Initial release.

IMPORTANT NOTE:

While sending the request, please make sure not to attach Content-Type in header or make Content-Type be NULL
ApiMultipartFormDataFormatter is obsolete and will be removed in version after 1.0.3. Please use MultipartFormDataFormatter instead.

Images:

Postman request

Parameter analyzation

ApiMultipartFormFormatter
ApiMultipartFormFormatter copied to clipboard

Metadata

ApiMultipartFormDataFormatter

A. Description:

B. Implementation:

C. HttpFile or HttpFileBase usage:

IV. Data serializer customization with `IModelBinderService`

VI. Examples:

VII. Limitation:

VIII. Change logs:

IMPORTANT NOTE:

Images:

← Metadata

Owner

Metadata

ApiMultipartFormFormatter ApiMultipartFormFormatter copied to clipboard

Metadata

ApiMultipartFormDataFormatter

A. Description:

B. Implementation:

C. HttpFile or HttpFileBase usage:

IV. Data serializer customization with IModelBinderService

VI. Examples:

VII. Limitation:

VIII. Change logs:

IMPORTANT NOTE:

Images:

← Metadata

Owner

Metadata

ApiMultipartFormFormatter
ApiMultipartFormFormatter copied to clipboard

IV. Data serializer customization with `IModelBinderService`