Form 表单提交（URL 编码）

在互联网应用中，保存用户自定义的数据最常见的方式是使用 Form 表单提交。Form 表单不仅能携带文本数据，还能携带二进制数据，如文件。

var content = await httpRemoteService.PostAsAsync<YourRemoteFormResult>("https://localhost:7044/HttpRemote/AddForm?id=1",    builder => builder.SetMultipartContent(multipart => multipart   // 设置多部分表单内容        .AddJson(new { id = 1, name = "furion" })   // 设置 JSON 数据        .AddFileAsStream(@"C:\Workspaces\httptest.jpg", "file")));  // 设置文件（支持流方式、字节数组方式、远程 URL 地址和 Base64 字符串）

SetMultipartContent 方法专门用于设置请求类型为 multipart/form-data 的表单数据，并提供了丰富的扩展选项，包括：

Boundary 或 SetBoundary(boundary)：设置多部分表单内容边界。
AddJson(rawJson)：添加 JSON 内容。
AddFormItem(value, name)：添加单个表单项内容。
AddHtml(htmlString, name)：添加 HTML 内容。
AddXml(xmlString, name)：添加 XML 内容。
AddText(text, name)：添加文本内容。
AddObject(rawObject, name)：添加对象内容。
AddFileFromRemote(url, name)：添加互联网文件内容。
AddFileFromBase64String(base64String, name, fileName)：添加 Base64 字符串文件内容。
AddFileAsStream(path, name)：添加本地文件作为流内容。
AddFileWithProgressAsStream(path, channel, name)：添加本地文件作为流内容（带文件传输进度）。
AddFileAsByteArray(path, name)：添加本地文件作为字节数组内容。
AddFile(multipartFile, name)：添加 MultipartFile 文件内容。
AddFile(fileInfo, name)：添加 FileInfo 文件内容。
AddFile(IFormFile)：添加 IFormFile 文件内容。
AddFiles(IFormFileCollection)：添加 IFormFileCollection 文件内容。
AddFile(IBrowserFile)：添加 IBrowserFile 文件内容。
AddFiles(IEnumerable<IBrowserFile>)：添加多个 IBrowserFile 文件内容。
AddStream(stream, name)：添加二进制流内容。
AddByteArray(byteArray, name)：添加二进制字节数组内容。
Add(httpContent)：添加 HttpContent 内容。

这些只是常用的设置方法，SetMultipartContent 提供了更多的灵活性。

除了上述方式，还支持以下几种方法：

// 使用构建器模式var content = await httpRemoteService.SendAsAsync<YourRemoteFormResult>(HttpRequestBuilder.Post("https://localhost:7044/HttpRemote/AddForm?id=1")    .SetMultipartContent(multipart => multipart   // 设置多部分表单内容        .AddJson(new { id = 1, name = "furion" })   // 设置 JSON 数据        .AddFileAsStream(@"C:\Workspaces\httptest.jpg", "file")));  // 设置文件（支持流方式、字节数组方式、远程 URL 地址和 Base64 字符串// 更多详细用法可参考第 19.2.1 节

以下是一些 Form 表单提交的常见例子：

var content = await httpRemoteService.PostAsAsync<YourRemoteFormResult>("https://localhost:7044/HttpRemote/AddForm?id=1",    builder => builder.SetMultipartContent(multipart => multipart   // 设置多部分表单内容        .AddJson(new { id = 1, name = "furion" })   // 设置 JSON 数据        .AddFormItem("age", "Age")  // 支持设置单个值        .AddFileAsStream(@"C:\Workspaces\httptest.jpg", "file") // 设置单个文件（对应表单 File 字段）        // 支持互联网文件地址        .AddFileFromRemote("https://furion.net/img/furionlogo.png", "files")    // 设置多个文件（对应表单 Files 字段）        // 支持读取本地文件作为字节数组        .AddFileAsByteArray(@"C:\Workspaces\httptest.jpg", "files"));  // 设置多个文件（对应表单 Files 字段）        // 添加 MultipartFile 文件        .AddFile(MultipartFile.CreateFromPath(@"C:\Workspaces\httptest.jpg")));

特别说明

如果使用 SetContent 方法来设置请求类型为 multipart/form-data 的内容且不是 MultipartContent 类型实例时，将会触发 NotSupportedException 异常。异常信息提示如下：

The method does not support setting the request content type to `multipart/form-data`. Please use the `SetMultipartContent` method instead. If you are using an HTTP declarative requests, define the parameter with the `Action<HttpMultipartFormDataBuilder>` type or annotate the parameter with the `MultipartAttribute`.

在需要设置请求内容类型为 multipart/form-data 类型时，应正确使用 SetMultipartContent 方法，而非 SetContent。

URL 编码表单

除了包含多个部分的 multipart/form-data 表单请求外，还有一种常见的请求类型是 application/x-www-form-urlencoded，它以 URL 编码形式发送数据。这种表单的特点是，所有特殊字符都会进行 URL 编码，通常用于无需上传文件等二进制数据的简单表单提交场景。

以下示例将展示如何构建符合 application/x-www-form-urlencoded 提交类型的表单数据。

var content = await httpRemoteService.PostAsAsync<YourRemoteModel>("https://localhost:7044/HttpRemote/AddURLForm",    builder => builder        .SetFormUrlEncodedContent(new { id = 1, name = "furion" })); // 设置 application/x-www-form-urlencoded 请求内容// 支持 URL 编码字符串格式var content = await httpRemoteService.PostAsAsync<YourRemoteModel>("https://localhost:7044/HttpRemote/AddURLForm",    builder => builder        .SetFormUrlEncodedContent("id=1&name=furion", useStringContent: true);

URL 编码表单内容说明

默认情况下，URL 编码表单通过 FormUrlEncodedContent 类型进行构建，但此类型不支持自定义请求内容编码，它默认使用 Encoding.Latin1 而不是 UTF-8。 这可能在提交到某些接口时引发异常。

为解决此问题，可以通过设置参数 useStringContent 为 true 来采用 StringContent 方式构建表单数据，从而允许自定义编码为 UTF-8。
cs
```
1
2
3
```
```
var content = await httpRemoteService.PostAsAsync<YourRemoteModel>("https://localhost:7044/HttpRemote/AddURLForm",    builder => builder        .SetFormUrlEncodedContent(new { id = 1, name = "furion" }, useStringContent: true));
```
某些服务器要求显式声明字符集（charset），此时可通过 contentEncoding 参数指定编码方式，例如使用 UTF-8：
cs
```
1
2
3
```
```
var content = await httpRemoteService.PostAsAsync<YourRemoteModel>("https://localhost:7044/HttpRemote/AddURLForm",    builder => builder        .SetFormUrlEncodedContent(new { id = 1, name = "furion" }, Encoding.UTF8));
```
此设置在发送远程请求时会生成如下 Content-Type 请求头：application/x-www-form-urlencoded; charset=UTF-8。