nanoFramework.System.Net.Http.Client 1.5.145

欢迎使用 .NET nanoFramework System.Net.Http 库存储库

构建状态

组件	构建状态	NuGet 包
System.Net.Http
System.Net.Http.Client
System.Net.Http.Server

使用示例

在此库中的 API、类和命名空间尽可能地遵循 .NET 的规范。例外情况包括缺乏异步调用、泛型和 Task，以及缺少带 CancelationToken 参数重载的方法。命名反映了这一点，即通过省略 Async 后缀，不返回 Task，并缺少带 CancelationToken 参数的重载方法。

值得注意的是，为了能够验证服务器证书，需要将 CA 根证书传递给 HttpClient。

HttpClient 调用 REST 服务

HttpClient 使连接和消耗 REST 服务变得非常容易。为了使用它，必须创建该对象并执行调用。请注意，HttpClient 旨在在整个应用程序生命周期中重复使用，不需要在每次调用时创建一个新的实例。如下所示

static readonly HttpClient _httpClient = new HttpClient();

传递 CA 根证书以允许验证安全的服务器证书。CA 根证书也可以来自资源中的二进制文件或文本文件。

_httpClient.HttpsAuthentCert = new X509Certificate(
@"-----BEGIN CERTIFICATE-----
MIIEDzCCAvegAwIBAgIBADANBgkqhkiG9w0BAQUFADBoMQswCQYDVQQGEwJVUzEl
MCMGA1UEChMcU3RhcmZpZWxkIFRlY2hub2xvZ2llcywgSW5jLjEyMDAGA1UECxMp
U3RhcmZpZWxkIENsYXNzIDIgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMDQw
NjI5MTczOTE2WhcNMzQwNjI5MTczOTE2WjBoMQswCQYDVQQGEwJVUzElMCMGA1UE
ChMcU3RhcmZpZWxkIFRlY2hub2xvZ2llcywgSW5jLjEyMDAGA1UECxMpU3RhcmZp
ZWxkIENsYXNzIDIgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwggEgMA0GCSqGSIb3
DQEBAQUAA4IBDQAwggEIAoIBAQC3Msj+6XGmBIWtDBFk385N78gDGIc/oav7PKaf
8MOh2tTYbitTkPskpD6E8J7oX+zlJ0T1KKY/e97gKvDIr1MvnsoFAZMej2YcOadN
+lq2cwQlZut3f+dZxkqZJRRU6ybH838Z1TBwj6+wRir/resp7defqgSHo9T5iaU0
X9tDkYI22WY8sbi5gv2cOj4QyDvvBmVmepsZGD3/cVE8MC5fvj13c7JdBmzDI1aa
K4UmkhynArPkPw2vCHmCuDY96pzTNbO8acr1zJ3o/WSNF4Azbl5KXZnJHoe0nRrA
1W4TNSNe35tfPe/W93bC6j67eA0cQmdrBNj41tpvi/JEoAGrAgEDo4HFMIHCMB0G
A1UdDgQWBBS/X7fRzt0fhvRbVazc1xDCDqmI5zCBkgYDVR0jBIGKMIGHgBS/X7fR
zt0fhvRbVazc1xDCDqmI56FspGowaDELMAkGA1UEBhMCVVMxJTAjBgNVBAoTHFN0
YXJmaWVsZCBUZWNobm9sb2dpZXMsIEluYy4xMjAwBgNVBAsTKVN0YXJmaWVsZCBD
bGFzcyAyIENlcnRpZmljYXRpb24gQXV0aG9yaXR5ggEAMAwGA1UdEwQFMAMBAf8w
DQYJKoZIhvcNAQEFBQADggEBAAWdP4id0ckaVaGsafPzWdqbAYcaT1epoXkJKtv3
L7IezMdeatiDh6GX70k1PncGQVhiv45YuApnP+yz3SFmH8lU+nLMPUxA2IGvd56D
eruix/U0F47ZEUD0/CwqTRV/p2JdLiXTAAsgGh1o+Re49L2L7ShZ3U0WixeDyLJl
xy16paq8U4Zt3VekyvggQQto8PT7dL5WXXp59fkdheMtlb71cZBDzI0fmgAKhynp
VSJYACPq4xJDKVtHCN2MQWplBqjlIapBtJUhlbl90TSrE9atvNziPTnNvT51cKEY
WQPJIrSPnNVeKtelttQKbfi3QBFGmh95DmK/D5fs4C8fF5Q=
-----END CERTIFICATE-----");

[!注意]

为了从服务器获取根证书，如果您安装了OpenSSL，您可以运行以下命令：openssl s_client -connect the.server-to-get-the-cert.com:443 -showcerts这会将使用到的所有根证书显示出来，并以PEM格式展示。然后您可以复制/粘贴您所需要的证书。

您可以为每个请求添加要发送的HTTP头部。

_httpClient.DefaultRequestHeaders.Add("x-ms-blob-type", "BlockBlob");

执行HTTP GET请求

以下是一个HTTP请求示例，用于将一些内容作为字符串读取

HttpResponseMessage response = _httpClient.Get("https://httpbin.org/get");
response.EnsureSuccessStatusCode();
var responseBody = response.Content.ReadAsString();

上述调用将返回类似以下内容，您可以通过调用Debug.WriteLine(responseBody)在Visual Studio中输出

{
  "args": {}, 
  "headers": {
    "Host": "httpbin.org", 
    "X-Amzn-Trace-Id": "Root=1-6214aad3-38e5f8357bdf90530300eb5f", 
    "X-Ms-Blob-Type": "BlockBlob"
  }, 
  "origin": "5.249.47.208", 
  "url": "https://httpbin.org/get"
}

注意调用response.EnsureSuccessStatusCode();。如果HTTP请求的状态码不是成功状态，这将抛出HttpRequestException异常。

执行HTTP POST请求

以下是一个HTTP请求示例，展示如何将一些JSON内容通过POST请求发送到端点。

var content = new StringContent("{\"someProperty\":\"someValue\"}", Encoding.UTF8, "application/json");
var result = _httpClient.Post("https://httpbin.org/anything", content);
result.EnsureSuccessStatusCode();

值得注意的是，上面的JSON内容以简单的字符串形式展示，以简化代码。存在一个JSON库，可以帮助将数据序列化并反序列化到/from C#类中，即使是最复杂的类。

同样，请注意调用response.EnsureSuccessStatusCode();以确保HTTP请求已成功执行。

将二进制内容下载到文件

使用HttpClient处理二进制内容也很容易。以下是如何从Web服务器下载文件的示例。

HttpResponseMessage response = _httpClient.Get("https://storage-on-the-cloud.net/file-with-binary-content");
response.EnsureSuccessStatusCode();

using FileStream fs = new FileStream($"I:\\i-am-a-binary-file.bin", FileMode.Create, FileAccess.Write);
response.Content.ReadAsStream().CopyTo(fs);

释放响应

[!Important]您**必须**释放所有请求发送的响应。设备内存有限，如果不请求释放，响应内容将永远不会被释放。根据设备不同，您可能在内存不足之前只能发送16个请求。

以下是一些确保正确释放响应内容的正确模式

using HttpResponseMessage response = client.Get(apiUrl);
// do whatever you want
// When the response object won't be used, it will be disposed

您可以为块使用显式的using

using HttpResponseMessage response = client.Get(apiUrl)
{
  // do whatever you want
  // when exiting the block, the response will be disposed
}

或显式地释放响应

HttpResponseMessage response = client.Get(apiUrl);
// do whatever you want
// Dispose explicitly the content
response.Dispose();

在所有情况下，您**必须**确保您释放了响应内容。

通过反向代理进行调试

当代码部署到MCU时，可能希望让设备连接到运行IIS Express的开发计算机。可以通过以下代理实现，例如这个代理。请注意，这会导致使用当前版本的strong>nanoFramework System.Net.Http发送连续请求到开发计算机时出现SocketExceptions。在调试模式下添加简单的重试机制可以解决这个问题。

反馈和文档

有关文档、提供反馈、问题和了解如何贡献，请参阅主仓库。

加入我们的Discord社区这里。

鸣谢

该项目的贡献者列表可在CONTRIBUTORS中找到。

许可证

strong>nanoFramework类库采用MIT许可。

行为准则

本项目已采用由贡献者公约定义的行为准则，以阐明我们对社区期望的行为。更多信息请参阅.NET基金会行为准则。

.NET基金会

此项目由.NET基金会支持。