大网数据广告活动
.NET 与 C# 开发

使用 .NET Core 创建 REST 客户端

· 52CE 我爱测

此教程将介绍 .NET Core 和 C# 语言的许多功能。

介绍

此教程将介绍 .NET Core 和 C# 语言的许多功能。 你将了解:

  • .NET Core 命令行接口 (CLI) 的基础知识。
  • C# 语言功能概述。
  • 如何使用 NuGet 管理依赖项
  • HTTP 通信
  • 如何处理 JSON 信息
  • 如何管理含特性的配置。

将生成一个应用程序,向 GitHub 上的 REST 服务发出 HTTP 请求。 需要读取 JSON 格式的信息,并将相应的 JSON 数据包转换成 C# 对象。 最后将了解如何使用 C# 对象。

此教程将介绍许多功能。 我们将逐个生成这些功能。

如果想要按照针对本主题的最终示例操作,可以下载它。 有关下载说明,请参阅示例和教程。

系统必备

必须将计算机设置为运行 .Net Core。 有关安装说明,请访问 .NET Core 页。 可以在 Windows、Linux、macOS 或 Docker 容器中运行此应用程序。 必须安装常用的代码编辑器。 在以下说明中,我们使用的是开放源代码跨平台编辑器 Visual Studio Code。 不过,你可以使用习惯使用的任意工具。

创建应用程序

第一步是新建应用程序。 打开命令提示符,然后新建应用程序的目录。 将新建的目录设为当前目录。 在命令提示符处,键入命令 dotnet new console。 这将为基本的“Hello World”应用程序创建起始文件。 因为这是新项目,所有没有任何依赖项,第一次运行时将下载 .NET Core 框架、安装开发证书并运行 NuGet 包管理器来还原缺少的依赖项。

在开始修改之前,在命令提示符中键入 dotnet run(参见注释)以运行应用程序。 如果环境缺少依赖项,则 dotnet run 会自动执行 dotnet restore。 如果需要重新生成应用程序,它还会执行 dotnet build。 初始设置完成后,只需在对项目有意义的情况下运行 dotnet restore 或 dotnet build。

添加新的依赖项

.NET Core 的主要设计目标之一是最小化 .NET 安装的大小。 如果应用程序需要使用其他库来生成某些功能,请将这些依赖项添加到 C# 项目 (*.csproj) 文件中。 对于我们的示例,将需要添加 System.Runtime.Serialization.Json 包,以便应用程序可以处理 JSON 响应。

打开 csproj 项目文件。 此文件的第一行应如下所示:

<Project Sdk="Microsoft.NET.Sdk">

在这行后面紧接着添加以下代码:

   <ItemGroup>
      <PackageReference Include="System.Runtime.Serialization.Json" Version="4.3.0" />
   </ItemGroup>

大多数代码编辑器都会完成这些库的不同版本。 通常需要使用所添加的任意包的最新版本。 不过,请务必确保所有包的版本均一致,且与 .NET Core 应用程序框架的版本一致。

完成这些更改后,执行 dotnet restore(参见注释),以便在系统上安装包。

发出 Web 请求

现在,可以开始检索 Web 数据了。 在此应用程序中,需要读取 GitHub API 返回的信息。 让我们在 .NET Foundation 的保护下读取项目信息。 先向 GitHub API 发出请求,以检索项目信息。 将使用终结点 https://api.github.com/orgs/dotnet/repos。 由于要检索这些项目的所有信息,因此将发出 HTTP GET 请求。 此外,浏览器也使用 HTTP GET 请求,以便你可以将相应的 URL 粘贴到浏览器,查看将要收到并处理的信息。

使用 xref:System.Net.Http.HttpClient 类发出 Web 请求。 与所有新式 .NET API 一样,xref:System.Net.Http.HttpClient 只支持长时间运行 API 的异步方法。 从异步方法入手。 将一边填充实现代码,一边生成应用程序功能。 首先,打开项目目录中的 program.cs 文件,然后向 Program 类添加以下方法:

private static async Task ProcessRepositories()
{
}

需要在 Main 方法的最上面添加 using 语句,以便 C# 编译器能够识别 xref:System.Threading.Tasks.Task 类型:

using System.Threading.Tasks;

如果此时生成项目,将会看到系统针对此方法生成的警告,因为其中不含任何 await 运算符,将以同步方式运行。 暂且忽略此警告;将在填充方法时添加 await 运算符。

接下来,将 namespace 语句中定义的命名空间从默认名称 ConsoleApp 重命名为 WebAPIClient。 我们稍后将在此命名空间中定义 repo 类。

接下来,将 Main 方法更新为调用此方法。 ProcessRepositories 方法会返回一个任务,不得在此任务完成前退出程序。 因此,必须使用 Wait 方法来阻止退出并等待任务完成:

static void Main(string[] args)
{
    ProcessRepositories().Wait();
}

现在,生成了一个不执行任何操作但具备异步功能的程序。 现在进行改进。

首先需要一个能从 Web 检索数据的对象;可使用 xref:System.Net.Http.HttpClient 执行此操作。 此对象负责处理请求和响应。 在 Program.cs 文件内的 Program 类中初始化该类型的一个实例。

namespace WebAPIClient
{
    class Program
    {
        private static readonly HttpClient client = new HttpClient();

        static void Main(string[] args)
        {
            //...
        }
    }
}

让我们回到 ProcessRepositories 方法,并填充它的第一个版本:

private static async Task ProcessRepositories()
{
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(
        new MediaTypeWithQualityHeaderValue("application/vnd.github.v3+json"));
    client.DefaultRequestHeaders.Add("User-Agent", ".NET Foundation Repository Reporter");

    var stringTask = client.GetStringAsync("https://api.github.com/orgs/dotnet/repos");

    var msg = await stringTask;
    Console.Write(msg);
}

此外,为了让编译能够顺利进行,还需要在文件的最上面添加两个新的 using 语句:

using System.Net.Http;
using System.Net.Http.Headers;

第一个版本发出 Web 请求来读取 .NET Foundation 组织下的所有存储库列表。 (.NET Foundation 的 gitHub ID 为“dotnet”)。 前几行代码针对该请求设置 xref:System.Net.Http.HttpClient。 在第一行中,它被配置为接受 GitHub JSON 响应。 此格式仅为 JSON。 下一代码行将用户代理标头添加到此对象发出的所有请求中。 这两个标头均由 GitHub 服务器代码进行检查,必须使用它们,才能检索 GitHub 中的信息。

配置 xref:System.Net.Http.HttpClient 后,发出 Web 请求并检索响应。 在此第一个版本中,将使用 xref:System.Net.Http.HttpClient.GetStringAsync(System.String)?displayProperty=nameWithType 便捷方法。 此便捷方法先执行发出 Web 请求的任务,然后当返回请求时读取响应流,并从流中提取内容。 响应正文以 xref:System.String 的形式返回。 此字符串在任务完成时可用。

此方法的最后两行代码用于等待任务完成,然后在控制台中打印输出响应。 生成并运行应用程序。 此时,生成警告不再显示,因为 ProcessRepositories 现在的确包含 await 运算符。 将看到很长的 JSON 格式文本。

处理 JSON 结果

此时,你已编写用于检索来自 Web 服务器的响应,并显示响应文本的代码。 接下来,让我们将相应的 JSON 响应转换成 C# 对象。

JSON 序列化程序将 JSON 数据转换成 C# 对象。 首要任务是定义 C# 类类型来包含要使用的此响应信息。 我们将慢慢生成,所以从包含存储库名称的简单 C# 类型入手:

using System;

namespace WebAPIClient
{
    public class repo
    {
        public string name;
    }
}

将以上代码添加到“repo.cs”新文件中。 此版本的类表示处理 JSON 数据的最简单路径。 类名和成员名称与 JSON 数据包中使用的名称一致,而不是遵循以下 C# 约定。 稍后将通过提供某些配置特性进行修复。 此类展示了 JSON 序列化和反序列化的另一个重要功能:并非 JSON 数据包中的所有字段都属于此类。 JSON 序列化程序将忽略所使用的类类型未包含的信息。 借助此功能,可更轻松地创建仅处理一部分 JSON 数据包字段的类型。

至此,你已创建类型,让我们来进行反序列化吧。 需要创建 xref:System.Runtime.Serialization.Json.DataContractJsonSerializer 对象。 此对象必须知道它检索的 JSON 数据包的预期 CLR 类型。 GitHub 发送的数据包中有一系列存储库,所以正确的类型是 List<repo>。 将下面这行代码添加到 ProcessRepositories 方法中:

var serializer = new DataContractJsonSerializer(typeof(List<repo>));

由于要使用两个新的命名空间,因此还需要添加以下代码:

using System.Collections.Generic;
using System.Runtime.Serialization.Json;

接下来,使用序列化程序将 JSON 转换成 C# 对象。 使用以下两行代码替换 ProcessRepositories 方法中对 xref:System.Net.Http.HttpClient.GetStringAsync(System.String) 的调用:

var streamTask = client.GetStreamAsync("https://api.github.com/orgs/dotnet/repos");
var repositories = serializer.ReadObject(await streamTask) as List<repo>;

请注意,现使用 xref:System.Net.Http.HttpClient.GetStreamAsync(System.String),而不是 xref:System.Net.Http.HttpClient.GetStringAsync(System.String)。 序列化程序使用流(而不是字符串)作为其源。 让我们来看看上面第二行代码所使用的两项 C# 语言功能。 xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.ReadObject(System.IO.Stream) 的自变量是一个 await 表达式。 Await 表达式可以出现在代码中的几乎任何位置,尽管到目前为止,你只在赋值语句中看到过它们。

其次,as 运算符将编译时类型 object 转换成 List<repo>。 xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.ReadObject(System.IO.Stream) 的声明会声明其返回 xref:System.Object?displayProperty=nameWithType 类型的对象。 xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.ReadObject(System.IO.Stream) 将返回你在构造它时指定的类型(在此教程中为 List<repo>)。 如果转换失败,那么 as 运算符的计算结果为 null,而不是抛出异常。

即将完成此部分的操作。 至此,你已将 JSON 数据转换成 C# 对象,让我们来显示每个存储库的名称。 将以下代码行:

var msg = await stringTask;   //**Deleted this
Console.Write(msg);

替换为:

foreach (var repo in repositories)
    Console.WriteLine(repo.name);

编译并运行该应用程序。 将打印输出属于 .NET Foundation 的存储库的名称。

控制序列化

在添加更多功能之前,让我们来处理一下 repo 类型,使其更加遵循标准的 C# 约定。 为此,使用可控制 JSON 序列化程序的工作方式的特性对 repo 类型添加批注。 在此示例中,将使用这些特性来定义 JSON 键名和 C# 类名及成员名称之间的映射。 使用的是 xref:System.Runtime.Serialization.DataContractAttribute 和 xref:System.Runtime.Serialization.DataMemberAttribute 两个特性。 按照约定,所有特性类均以后缀 Attribute 结尾。 不过,在应用特性时无需使用此后缀。

由于 xref:System.Runtime.Serialization.DataContractAttribute 和 xref:System.Runtime.Serialization.DataMemberAttribute 特性位于不同的库中,因此需要将相应的库作为依赖项添加到 C# 项目文件中。 将下面这行代码添加到项目文件的 <ItemGroup> 部分中:

<PackageReference Include="System.Runtime.Serialization.Primitives" Version="4.3.0" />

保存文件后,运行 dotnet restore(请参阅备注)来检索此包。

接下来,打开 repo.cs 文件。 让我们改用 Pascal 命名法,完整拼写出全称 Repository。 我们仍要将 JSON“repo”节点映射到此类型,所以需要将 xref:System.Runtime.Serialization.DataContractAttribute 特性添加到类声明。 将特性的 Name 属性设置为映射到此类型的 JSON 节点的名称:

[DataContract(Name="repo")]
public class Repository

由于 xref:System.Runtime.Serialization.DataContractAttribute 属于 xref:System.Runtime.Serialization 命名空间,因此需要在文件的最上面添加适当的 using 语句:

using System.Runtime.Serialization;

由于已将 repo 类名更改为 Repository,因此需要在 Program.cs 中执行相同的名称更改(某些编辑器可能支持重命名重构,这样就可以自动执行此更改了):

var serializer = new DataContractJsonSerializer(typeof(List<Repository>));

// ...

var repositories = serializer.ReadObject(await streamTask) as List<Repository>;

接下来,让我们使用 xref:System.Runtime.Serialization.DataMemberAttribute 类对 name 字段执行相同的更改。 对 repo.cs 中的 name 字段声明执行以下更改:

[DataMember(Name="name")]
public string Name;

此更改意味着需要更改用于在 program.cs 中写入每个存储库名称的代码:

Console.WriteLine(repo.Name);

依次执行 dotnet build 和 dotnet run,以确保生成正确映射。 应能看到与之前一样的输出。 让我们先对 Repository 类执行另一项更改,然后再处理更多 Web 服务器属性。 Name 成员是可公开访问的字段。 这不是一种很好的面向对象的做法,因此,让我们将其更改为属性。 鉴于我们的目的,获取或设置属性时,我们不需要运行任何特定代码,但更改为属性,稍后就可以更加轻松地添加这些更改,同时还不会破坏任何使用 Repository 类的代码。

删除字段定义,然后将其替换为自动实现的属性:

public string Name { get; set; }

编译器生成 get 和 set 访问器的主体,以及用于存储名称的专用字段。 代码如下(可以手动键入):

public string Name
{
    get { return this._name; }
    set { this._name = value; }
}
private string _name;

让我们在添加新功能前执行另一项更改。 ProcessRepositories 方法可以执行异步工作,并返回一组存储库。 我们将使用此方法返回 List<Repository>,并将用于写入信息的代码移到 Main 方法中。

更改 ProcessRepositories 的签名,以返回可生成 Repository 对象列表的任务:

private static async Task<List<Repository>> ProcessRepositories()

然后,在处理 JSON 响应后仅返回存储库:

var repositories = serializer.ReadObject(await streamTask) as List<Repository>;
return repositories;

编译器将生成返回内容的 Task<T> 对象,因为你已将此方法标记为 async。 然后,我们将把 Main 方法修改为,捕获这些结果并将每个存储库名称写入控制台。 现在,Main 方法如下所示:

public static void Main(string[] args)
{
    var repositories = ProcessRepositories().Result;

    foreach (var repo in repositories)
        Console.WriteLine(repo.Name);
}

只有在任务完成后,才能访问任务的 Result 属性。 通常情况下,在 ProcessRepositories 方法中,你倾向于 await(等待)任务完成,但在 Main 方法中这是不允许的。

读取详细信息

最后,让我们来处理 GitHub API 发送的 JSON 数据包中的其他一些属性。 虽然你不想面面俱到,但添加其他一些属性将展示更多的 C# 语言功能。

首先,将其他一些简单类型添加到 Repository 类定义中。 将这些属性添加到此类:

[DataMember(Name="description")]
public string Description { get; set; }

[DataMember(Name="html_url")]
public Uri GitHubHomeUrl { get; set; }

[DataMember(Name="homepage")]
public Uri Homepage { get; set; }

[DataMember(Name="watchers")]
public int Watchers { get; set; }

这些属性内置转换功能,可从字符串类型(即 JSON 数据包所含)转换成目标类型。 你可能是刚开始接触 xref:System.Uri 类型。 它代表 URI(或在此示例中,代表 URL)。 在有 Uri 和 int 类型的情况下,如果 JSON 数据包内的数据未转换成目标类型,那么序列化操作将会抛出异常。

添加这些元素后,将 Main 方法更新为显示它们:

foreach (var repo in repositories)
{
    Console.WriteLine(repo.Name);
    Console.WriteLine(repo.Description);
    Console.WriteLine(repo.GitHubHomeUrl);
    Console.WriteLine(repo.Homepage);
    Console.WriteLine(repo.Watchers);
    Console.WriteLine();
}

最后一步,让我们添加最后一次推送操作的信息。 此信息按如下方式在 JSON 响应中进行格式化:

2016-02-08T21:27:00Z

此格式不符合任何标准 .NET xref:System.DateTime 格式。 因此,需要编写一个自定义转换方法。 你可能也不希望向 Repository 类的用户公开原始字符串。 特性还有助于控制此情况。 首先,定义 private 属性,用于在 Repository 类中保存日期时间的字符串表示形式:

[DataMember(Name="pushed_at")]
private string JsonDate { get; set; }

xref:System.Runtime.Serialization.DataMemberAttribute 特性指示序列化程序应对此进行处理,即使不是公共成员,也不例外。 接下来,需要编写一个公共只读属性,用于将字符串转换成有效的 xref:System.DateTime 对象,并返回 xref:System.DateTime:

[IgnoreDataMember]
public DateTime LastPush
{
    get
    {
        return DateTime.ParseExact(JsonDate, "yyyy-MM-ddTHH:mm:ssZ", CultureInfo.InvariantCulture);
    }
}

让我们来看一下上面的新构造。 IgnoreDataMember 特性指示序列化程序,不得将此类型读入任何 JSON 对象,也不得从中写入此类型。 此属性只包含 get 访问器。 不存在 set 访问器。 这就是在 C# 中定义只读属性的方式。 (是的,可以在 C# 中创建只写属性,但属性值受限。)xref:System.DateTime.ParseExact(System.String,System.String,System.IFormatProvider) 方法分析字符串,并使用提供的日期格式创建 xref:System.DateTime 对象,然后使用 CultureInfo 对象将其他元数据添加到 DateTime 中。 如果分析操作失败,那么属性访问器会抛出异常。

若要使用 xref:System.Globalization.CultureInfo.InvariantCulture ,需要将 xref:System.Globalization 命名空间添加到 repo.cs 中的 using 语句:

using System.Globalization;

最后,在控制台中再添加一个输出语句,然后就可以再次生成并运行此应用程序:

Console.WriteLine(repo.LastPush);

你的版本现在应与已完成的示例匹配。

结束语

此教程介绍了如何发出 Web 请求、分析结果,以及如何显示这些结果的属性。 你也已经在项目中将新的包添加为依赖项, 并已了解一些支持面向对象的技术的 C# 语言功能。

Note: 从 .NET Core 2.0 SDK 开始,无需运行 dotnet restore,因为它由所有需要还原的命令隐式运行,如 dotnet new、dotnet build 和 dotnet run。 在执行显式还原有意义的某些情况下,例如 Azure DevOps Services 中的持续集成生成中,或在需要显式控制还原发生时间的生成系统中,它仍然是有效的命令。

历史资料。此文对应 2019-08-18 的中文文档快照,适用产品版本和命令行为以原文为准。

来源与署名:Microsoft 和文档贡献者。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站展开固定版本仓库内的引用内容,将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。

资料来源与适用范围

资料来源
Microsoft / .NET 中文文档历史快照
适用范围
历史中文快照 2019-08-18;详见原文产品版本;文档日期 03/06/2017
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0(文档)/ MIT(示例代码)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。