Sending files and additional data using HttpClient in .NET Core

How to send a multipart HTTP requests containing files using HttpClient in .NET Core? What to do if the target endpoint requires some additional data? This article describes the solutions for common cases and presents raw HTTP messages that are generated by the HttpClient for multipart requests.

Bartłomiej Iskrzycki

22 July 2021

Sending a single file

Say we've got an existing .NET Core app running on localhost:5001 with a single endpoint defined like below. For simplicity, we return the 200 status code.

1[ApiController]2[Route("file")]3public class FileController : ControllerBase4{5    [HttpPost]6    public IActionResult Upload([FromForm] IFormFile file)7    {8        // code responsible for file processing9        return Ok();10    }11}

Ok, now we want to send a request to this endpoint from another app using HttpClient. Because the endpoint’s argument file is decorated with the FromForm attribute it expects a multipart/form-data content type.

Firstly, we initialize the HttpClient. Note that, in real life, it’s not a good practice to create HttpClient on every request. That’s because of the socket exhaustion problem. However, it is out of scope of this article.

The request itself is defined by the HttpRequestMessage object and MultipartFormDataContent attached to it. The MultipartFormDataContent contains a single file stream that we want to send. The "file" is a name of an argument with type IFormFile required by the target endpoint 🌐.

1private static async Task UploadSampleFile()2{3    var client = new HttpClient4    {5        BaseAddress = new("https://localhost:5001")6    };7
8    await using var stream = System.IO.File.OpenRead("./Test.txt");9    using var request = new HttpRequestMessage(HttpMethod.Post, "file");10    using var content = new MultipartFormDataContent11    {12        { new StreamContent(stream), "file", "Test.txt" }13    };14
15    request.Content = content;16
17    await client.SendAsync(request);18}

Below you can see raw HTTP request produced by this code. When we execute our client app, then the file is mapped to the file argument on the endpoint side 👏.

1POST https://localhost:5001/file HTTP/1.12Host: localhost:50013traceparent: 00-993857cecaf029429fa329eda04bf984-5241706235957046-004Content-Type: multipart/form-data; boundary="f18c569a-003f-4395-baa0-1fbe71efee38"5Content-Length: 1786
7--f18c569a-003f-4395-baa0-1fbe71efee388Content-Disposition: form-data; name=file; filename=Test.txt; filename*=utf-8''Test.txt9
10--f18c569a-003f-4395-baa0-1fbe71efee38--

HTTP

Sending a file with additional data

What to do if the target endpoint accepts a single file and some additional fields?

1[ApiController]2[Route("file")]3public class FileController : ControllerBase4{5    [HttpPost]6    public IActionResult Upload([FromForm] FileDataDto dto)7    {8        // code responsible for file processing9        return Ok();10    }11}

1public class FileDataDto2{3    public IFormFile FileToUpload1 { get; set; }4    public DataDto Data { get; set; }5}6
7public class DataDto8{9    public string Name { get; set; }10    public string[] Tags { get; set; }11    public ChildDataDto ChildData { get; set; }12}13
14public class ChildDataDto15{16    public string Description { get; set; }17}

The key thing on the client side is to prepare a request object that will be correctly mapped by the model binder to FileDataDto. Again, because the endpoint’s DTO is decorated with the FromForm attribute, it expects a multipart request.

This time the MultipartFormDataContent contains a collection of HttpContent objects. We specify StreamContent containing the file’s stream and multiple objects of the type StringContent.

Each StringContent object defines a single property that will be mapped to DataDto in the target endpoint. For instance, in order to populate the Name property on DataDto, we need to specify the whole path to this property as a content’s name. Collection properties like Tags can be populated with multiple StringContent objects with the same name.

1private static async Task UploadSampleFile()2{3    var client = new HttpClient4    {5        BaseAddress = new("https://localhost:5001")6    };7
8    await using var stream = System.IO.File.OpenRead("./Test.txt");9
10    var payload = new11    {12        Name = "payload name",13        Tags = new[] { "tag1", "tag2" },14        ChildData = new15        {16            Description = "test description"17        }18    };19
20    using var request = new HttpRequestMessage(HttpMethod.Post, "file");21
22    using var content = new MultipartFormDataContent23    {24        // file25        { new StreamContent(stream), "FileToUpload1", "Test.txt" },26
27        // payload28        { new StringContent(payload.Name), "Data.Name" },29        { new StringContent(payload.Tags[0]), "Data.Tags" },30        { new StringContent(payload.Tags[1]), "Data.Tags" },31        { new StringContent(payload.ChildData.Description), "Data.ChildData.Description" }32    };33
34    request.Content = content;35
36    await client.SendAsync(request);37}

As you can see, this approach is not convenient. You must manually create multiple string contents for each target property. Perhaps it would be worth considering a helper method that converts the payload to a collection of StringContent objects?

Here is the raw HTTP request. As expected, it consists of stream content and multiple string contents. The model binder can populate the target DTO correctly 👍.

1POST https://localhost:5001/file HTTP/1.12Host: localhost:50013traceparent: 00-853f01b7762c9746912e3775865d60ba-c43a730c1a434848-004Content-Type: multipart/form-data; boundary="949a4299-4662-4775-94e2-de82e76936a5"5Content-Length: 7726
7--949a4299-4662-4775-94e2-de82e76936a58Content-Disposition: form-data; name=fileToUpload1; filename=Test.txt; filename*=utf-8''Test.txt9
10
11--949a4299-4662-4775-94e2-de82e76936a512Content-Type: text/plain; charset=utf-813Content-Disposition: form-data; name=Data.Name14
15payload name16--949a4299-4662-4775-94e2-de82e76936a517Content-Type: text/plain; charset=utf-818Content-Disposition: form-data; name=Data.Tags19
20tag121--949a4299-4662-4775-94e2-de82e76936a522Content-Type: text/plain; charset=utf-823Content-Disposition: form-data; name=Data.Tags24
25tag226--949a4299-4662-4775-94e2-de82e76936a527Content-Type: text/plain; charset=utf-828Content-Disposition: form-data; name=Data.ChildData.Description29
30test description31--949a4299-4662-4775-94e2-de82e76936a5--

HTTP

The alternative approach – sending additional data as JSON

The target endpoint might be prepared to accept the application/json content type for additional data. It needs custom model binders that deserializes the JSON content to the target type. In this case, the Data property is decorated with the ModelBinder attribute that takes the type of a custom binder.

1public class FileDataDto2{3    public IFormFile FileToUpload1 { get; set; }4
5    [ModelBinder(BinderType = typeof(FormDataJsonBinder))]6    public DataDto Data { get; set; }7}

1public class FormDataJsonBinder : IModelBinder2{3    private readonly ILogger<FormDataJsonBinder> _logger;4
5    public FormDataJsonBinder(ILogger<FormDataJsonBinder> logger)6    {7        _logger = logger;8    }9
10    public Task BindModelAsync(ModelBindingContext bindingContext)11    {12        if (bindingContext == null)13        {14            throw new ArgumentNullException(nameof(bindingContext));15        }16
17        var modelName = bindingContext.ModelName;18
19        var valueProviderResult = bindingContext.ValueProvider.GetValue(modelName);20
21        if (valueProviderResult == ValueProviderResult.None)22        {23            return Task.CompletedTask;24        }25
26        bindingContext.ModelState.SetModelValue(modelName, valueProviderResult);27
28        var value = valueProviderResult.FirstValue;29
30        if (string.IsNullOrEmpty(value))31        {32            return Task.CompletedTask;33        }34
35        try36        {37            var result = JsonSerializer.Deserialize(value, bindingContext.ModelType);38            bindingContext.Result = ModelBindingResult.Success(result);39        }40        catch (Exception ex)41        {42            _logger.LogError(ex, ex.Message);43            bindingContext.Result = ModelBindingResult.Failed();44        }45
46        return Task.CompletedTask;47    }48}

Now, the client itself requires some minor adjustments. Instead of sending individual objects of type StringContent, we send the aggregated one with a serialized payload.

1private static async Task UploadSampleFile()2{3    var client = new HttpClient4    {5        BaseAddress = new("https://localhost:5001")6    };7
8    await using var stream = System.IO.File.OpenRead("./Test.txt");9
10    var payload = new11    {12        Name = "payload name",13        Tags = new[] { "tag1", "tag2" },14        ChildData = new15        {16            Description = "test description"17        }18    };19
20    using var request = new HttpRequestMessage(HttpMethod.Post, "file");21
22    using var content = new MultipartFormDataContent23    {24        // file25        { new StreamContent(stream), "FileToUpload1", "Test.txt" },26
27        // payload28        { new StringContent(29            JsonSerializer.Serialize(payload),30            Encoding.UTF8,31            "application/json"),32            "Data" },33    };34
35    request.Content = content;36
37    await client.SendAsync(request);38}

Everything is ready 🎉. The HttpClient produces an HTTP message like the one below. The FileDataDto is fully populated.

1POST https://localhost:5001/file HTTP/1.12Host: localhost:50013traceparent: 00-7b5c963871ed1c4986ecada82e82c544-b963915470a64149-004Content-Type: multipart/form-data; boundary="f06a5661-47cd-45bd-a90f-69c4e2f88c64"5Content-Length: 4146
7--f06a5661-47cd-45bd-a90f-69c4e2f88c648Content-Disposition: form-data; name=fileToUpload1; filename=Test.txt; filename*=utf-8''Test.txt9
10
11--f06a5661-47cd-45bd-a90f-69c4e2f88c6412Content-Type: application/json; charset=utf-813Content-Disposition: form-data; name=Data14
15{"Name":"payload name","Tags":["tag1","tag2"],"ChildData":{"Description":"test description"}}16--f06a5661-47cd-45bd-a90f-69c4e2f88c64--

HTTP

Sending multiple files (with additional data)

What if the target endpoint accepts multiple files?

1[ApiController]2[Route("file")]3public class FileController : ControllerBase4{5    [HttpPost]6    public IActionResult Upload([FromForm] FileDataDto dto)7    {8        // code responsible for file processing9        return Ok();10    }11}

1public class FileDataDto2{3    public List<IFormFile> FilesToUpload { get; set; }4
5    [ModelBinder(BinderType = typeof(FormDataJsonBinder))]6    public DataDto Data { get; set; }7}

The only thing that we need to do on the client side is to adjust the MultipartFormDataContent by adding another file stream. Note that both contents should have the same name FilesToUpload. I didn't duplicate the whole client's code again so go back if you missed something 😅.

1using var content = new MultipartFormDataContent2{3    // files4    { new StreamContent(stream), "FilesToUpload", "Test.txt" },5    { new StreamContent(anotherStream), "FilesToUpload", "NewTest.txt" },6
7    // payload8    ...9};

Everything works as expected!

1POST https://localhost:5001/file HTTP/1.12Host: localhost:50013traceparent: 00-882ae85a7db6a74597e78460578430ba-590a3900255d784c-004Content-Type: multipart/form-data; boundary="d9b747c2-c028-4cc2-b53d-904af4f558f1"5Content-Length: 5656
7--d9b747c2-c028-4cc2-b53d-904af4f558f18Content-Disposition: form-data; name=FilesToUpload; filename=Test.txt; filename*=utf-8''Test.txt9
10
11--d9b747c2-c028-4cc2-b53d-904af4f558f112Content-Disposition: form-data; name=FilesToUpload; filename=NewTest.txt; filename*=utf-8''NewTest.txt13
14
15--d9b747c2-c028-4cc2-b53d-904af4f558f116Content-Type: application/json; charset=utf-817Content-Disposition: form-data; name=Data18
19{"Name":"payload name","Tags":["tag1","tag2"],"ChildData":{"Description":"test description"}}20--d9b747c2-c028-4cc2-b53d-904af4f558f1--

HTTP

Conclusion

I hope that this article helped you understand how to utilize the HttpClient to send multipart requests. I tried to cover all scenarios but, in the world of programming, there is an endless number of various cases 😅. Questions or problems? Leave the comment below.