使用 Microsoft Graph 生成 .NET 应用
本教程介绍如何生成使用 Microsoft Graph API 的 .NET 控制台应用。
提示
如果只希望下载已完成的教程，可以下载或克隆 GitHub 存储库。
先决条件
在开始本教程之前，应在开发计算机上安装 .NET SDK 。
你还应有一个个人 Microsoft 帐户，其中包含 Outlook.com 上的邮箱，或者 Microsoft 工作或学校帐户。 如果没有 Microsoft 帐户，可以使用以下几个选项来获取免费帐户：
- 可以 注册新的个人 Microsoft 帐户。
- 可以 注册 Microsoft 365 开发人员计划 以获取免费的 Microsoft 365 订阅。
备注
本教程是使用 .NET SDK 版本 6.0.102 编写的。 本指南中的步骤可能适用于其他版本，但尚未进行测试。
在门户中注册该应用
在本练习中，你将在Azure Active Directory中注册一个新应用程序，以启用用户身份验证。 可以使用Azure Active Directory管理中心或使用 Microsoft Graph PowerShell SDK 注册应用程序。
注册应用程序以进行用户身份验证
在本部分中，你将注册一个应用程序，该应用程序将使用 设备代码流支持用户身份验证。
打开浏览器，并转到 Azure Active Directory 管理中心。然后，使用 个人帐户（亦称为“Microsoft 帐户”）或 工作或学校帐户 登录。
选择左侧导航栏中的“Azure Active Directory”，再选择“管理”下的“应用注册”。
选择“新注册”。 例如
.NET Graph Tutorial，输入应用程序的名称。根据需要设置 支持的帐户类型 。 选项包括：
选项 Who可以登录？ 仅限此组织目录中的帐户 仅Microsoft 365组织中的用户 任何组织目录中的帐户 任何Microsoft 365组织中的用户 (工作或学校帐户) 任何组织目录中的帐户...和个人 Microsoft 帐户 任何Microsoft 365组织中的用户 (工作或学校帐户) 和个人 Microsoft 帐户 保留“重定向 URI”为空。
选择“注册”。 在应用程序的 “概述 ”页上，复制应用程序 (客户端) ID 的值并将其保存，下一步将需要它。 如果仅针对 受支持的帐户类型 选择 此组织目录中的 帐户，请复制 目录 (租户) ID 并保存它。
选择“管理”下的“身份验证”。 找到 “高级设置” 部分，将 “允许公共客户端流 ”切换为 “是”，然后选择 “保存”。
备注
请注意，你未配置任何 Microsoft Graph对应用注册的权限。 这是因为示例将使用 动态许可 请求用户身份验证的特定权限。
创建 .NET 控制台应用
首先，使用 .NET CLI 创建新的 .NET 控制台项目。
在要在其中创建项目的目录中打开命令行接口 (CLI) 。 运行以下命令：
dotnet new console -o GraphTutorial创建项目后，请通过将当前目录更改为 GraphTutorial 目录并在 CLI 中运行以下命令来验证其是否正常工作。
dotnet run如果工作，应用应输出
Hello, World!。
安装依赖项
在继续操作之前，请添加一些稍后将使用的附加依赖项。
- 从 appsettings.json 读取应用程序配置的 .NET 配置包。
- 用于 .NET 的 Azure 标识客户端库 ，用于对用户进行身份验证并获取访问令牌。
- Microsoft Graph .NET 客户端库来调用 Microsoft Graph。
在 CLI 中运行以下命令以安装依赖项。
dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Azure.Identity
dotnet add package Microsoft.Graph
加载应用程序设置
在本部分中，你将向项目添加应用注册的详细信息。
在名为 appsettings.json 的 GraphTutorial 目录中创建文件并添加以下代码。
根据下表更新值。
设置 值 clientId应用注册的客户端 ID authTenant如果选择仅允许组织中的用户登录的选项，请将此值更改为租户 ID。 否则，请保留为 common.提示
（可选）可以在名为 appsettings 的单独文件中设置这些值 。Development.json 或 .NET Secret Manager。
更新 GraphTutorial.csproj 以将 appsettings.json 复制到输出目录。 在两行之间
<Project>``</Project>添加以下代码。<ItemGroup> <None Include="appsettings*.json"> <CopyToOutputDirectory>Always</CopyToOutputDirectory> </None> </ItemGroup>在名为 设置.cs 的 GraphTutorial 目录中创建文件并添加以下代码。
设计应用
在本部分中，你将创建一个简单的基于控制台的菜单。
打开 ./Program.cs 并将其整个内容替换为以下代码。
在文件末尾添加以下占位符方法。 你将在后续步骤中实现它们。
void InitializeGraph() { // TODO } async Task GreetUserAsync() { // TODO } async Task DisplayAccessTokenAsync() { // TODO } async Task ListInboxAsync() { // TODO } async Task SendMailAsync() { // TODO } async Task ListUsersAsync() { // TODO } async Task MakeGraphCallAsync() { // TODO }
这会实现基本菜单，并从命令行读取用户的选择。
添加用户身份验证
在本部分中，将从上一练习扩展应用程序，以支持使用 Azure AD 进行身份验证。 这是获取调用 Microsoft Graph 所需的 OAuth 访问令牌所必需的。 在此步骤中，你将将适用于 .NET 的 Azure 标识客户端库集成到应用程序中，并为 Microsoft Graph .NET 客户端库配置身份验证。
Azure 标识库提供许多实现 OAuth2 令牌流的 TokenCredential 类。 Microsoft Graph 客户端库使用这些类对 Microsoft Graph 的调用进行身份验证。 在此示例中，我们将使用以下 TokenCredential 类。
DeviceCodeCredential实现用于用户身份验证的 设备代码流 。ClientSecretCredential实现仅应用身份验证 的客户端凭据流 。 你将在可选的仅限应用的部分中使用此类。
为用户身份验证配置Graph客户端
在本部分中， DeviceCodeCredential 你将使用该类通过设备 代码流请求访问令牌。
在名为 GraphHelper.cs 的 GraphTutorial 目录中创建新文件，并将以下代码添加到该文件。
using Azure.Core; using Azure.Identity; using Microsoft.Graph; class GraphHelper { }将以下代码添加到
GraphHelper类。将 Program.cs 中的空
InitializeGraph函数替换为以下内容。
此代码声明两个私有属性，一个 DeviceCodeCredential 对象和一个 GraphServiceClient 对象。 该 InitializeGraphForUserAuth 函数创建新的实例 DeviceCodeCredential，然后使用该实例创建新的实例 GraphServiceClient。 每次通过 API 调用 Microsoft Graph_userClient时，它都会使用提供的凭据来获取访问令牌。
测试 DeviceCodeCredential
接下来，添加代码以从中 DeviceCodeCredential获取访问令牌。
将以下函数添加到
GraphHelper类。将 Program.cs 中的空
DisplayAccessTokenAsync函数替换为以下内容。生成并运行应用。 在系统提示输入选项时输入
1。 应用程序显示 URL 和设备代码。.NET Graph Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 1 To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code RB2RUD56D to authenticate.打开浏览器并浏览到显示的 URL。 输入提供的代码并登录。
重要
请注意浏览到浏览器时登录到浏览器的任何
https://microsoft.com/devicelogin现有Microsoft 365帐户。 使用浏览器功能（例如配置文件、来宾模式或专用模式）来确保将身份验证为要用于测试的帐户。完成后，返回到应用程序以查看访问令牌。
提示
仅 出于验证和调试目的，只能使用 Microsoft 的联机令牌分析器 https://jwt.ms解码工作或学校帐户的用户访问令牌 () 。 如果在调用 Microsoft Graph 时遇到令牌错误，这可能很有用。 例如，验证
scp令牌中的声明是否包含预期的 Microsoft Graph权限范围。
获取用户
在本部分中，你将将 Microsoft Graph合并到应用程序中。 对于此应用程序，你将使用 Microsoft Graph .NET 客户端库来调用 Microsoft Graph。
打开 ./GraphHelper.cs 并将以下函数添加到 GraphHelper 类。
将 Program.cs 中的空
GreetUserAsync函数替换为以下内容。
如果现在运行应用，则在登录应用后，欢迎你按名称操作。
Hello, Megan Bowen!
Email: MeganB@contoso.com
代码解释
考虑函数中的 GetUserAsync 代码。 这只是几行，但有一些关键详细信息需要注意。
访问“me”
该函数使用 _userClient.Me 请求生成器，该生成器会生成对 Get 用户 API 的请求。 可通过以下两种方式访问此 API：
GET /me
GET /users/{user-id}
在这种情况下，代码将调用 GET /me API 终结点。 这是一种快捷方式，用于在不知道用户 ID 的情况下获取经过身份验证的用户。
备注
GET /me由于 API 终结点获取经过身份验证的用户，因此它仅适用于使用用户身份验证的应用。 仅限应用的身份验证应用无法访问此终结点。
请求特定属性
该函数使用 Select 请求上的方法来指定所需的属性集。 这会将 $select查询参数 添加到 API 调用。
强类型返回类型
该函数从 API 返回 Microsoft.Graph.User 从 JSON 响应反序列化的对象。 由于代码使用 Select，因此仅请求的属性在返回 User 的对象中具有值。 所有其他属性都将具有默认值。
列出收件箱
在本部分中，你将添加在用户的电子邮件收件箱中列出邮件的功能。
打开 ./GraphHelper.cs 并将以下函数添加到 GraphHelper 类。
将 Program.cs 中的空
ListInboxAsync函数替换为以下内容。运行应用、登录并选择选项 2 以列出收件箱。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 2 Message: Updates from Ask HR and other communities From: Contoso Demo on Yammer Status: Read Received: 12/30/2021 4:54:54 AM -05:00 Message: Employee Initiative Thoughts From: Patti Fernandez Status: Read Received: 12/28/2021 5:01:10 PM -05:00 Message: Voice Mail (11 seconds) From: Alex Wilber Status: Unread Received: 12/28/2021 5:00:46 PM -05:00 Message: Our Spring Blog Update From: Alex Wilber Status: Unread Received: 12/28/2021 4:49:46 PM -05:00 Message: Atlanta Flight Reservation From: Alex Wilber Status: Unread Received: 12/28/2021 4:35:42 PM -05:00 Message: Atlanta Trip Itinerary - down time From: Alex Wilber Status: Unread Received: 12/28/2021 4:22:04 PM -05:00 ... More messages available? True
代码解释
考虑函数中的 GetInboxAsync 代码。
访问已知邮件文件夹
该函数使用 _userClient.Me.MailFolders["Inbox"].Messages 请求生成器，该生成器生成对 列表消息 API 的请求。 由于它包括 MailFolders["Inbox"] 请求生成器，因此 API 只会返回请求的邮件文件夹中的邮件。 在这种情况下，由于收件箱是用户邮箱中的默认已知文件夹，因此可通过其已知名称访问该收件箱。 通过将已知名称替换为邮件文件夹的 ID 属性，以相同的方式访问非默认文件夹。 有关可用的已知文件夹名称的详细信息，请参阅 mailFolder 资源类型。
访问集合
GetUserAsync与上一部分返回单个对象的函数不同，此方法返回消息集合。 Microsoft Graph中返回集合的大多数 API 不会在单个响应中返回所有可用结果。 相反，它们使用 分页 返回部分结果，同时为客户端提供请求下一个“页面”的方法。
默认页面大小
使用分页的 API 实现默认页面大小。 对于消息，默认值为 10。 客户端可以使用$top查询参数请求更多 (或更少 ) 。 在 GetInboxAsync其中，这是通过方法实现的 .Top(25) 。
备注
传递给 .Top() 的值是上限，而不是显式数字。 API 将返回一些消息 ，直至 指定的值。
获取后续页面
如果服务器上有更多可用的结果，则集合响应包括一个 @odata.nextLink 具有 API URL 的属性，用于访问下一页。 .NET 客户端库将此信息公开为 NextPageRequest 集合页对象上的属性。 如果此属性为非 null，则有更多的结果可用。
该 NextPageRequest 属性公开返回下一 GetAsync 页的方法。
集合排序
该函数使用 OrderBy 请求上的方法来请求在收到消息时排序的结果 (ReceivedDateTime 属性) 。 它包括 DESC 关键字，以便首先列出最近收到的消息。 这会将 $orderby查询参数 添加到 API 调用。
发送邮件
在本部分中，你将添加以经过身份验证的用户发送电子邮件的功能。
打开 ./GraphHelper.cs 并将以下函数添加到 GraphHelper 类。
将 Program.cs 中的空
SendMailAsync函数替换为以下内容。运行应用、登录并选择选项 3 以向自己发送电子邮件。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 3 Mail sent.备注
如果要从Microsoft 365开发人员计划中测试开发人员租户，则可能无法传递您发送的电子邮件，并且可能会收到未送达报告。 如果发生这种情况，请通过Microsoft 365 管理中心联系支持人员。
代码解释
考虑函数中的 SendMailAsync 代码。
发送邮件
该函数使用 _userClient.Me.SendMail 请求生成器，该生成器生成对 发送邮件 API 的请求。 请求生成器采用一个 Message 表示要发送的消息的对象。
创建对象
与之前对仅读取数据的 Microsoft Graph的调用不同，此调用会创建数据。 若要使用客户端库执行此操作，请创建表示本例中数据 (的类的实例， Microsoft.Graph.Message) 使用 new 关键字，设置所需的属性，然后在 API 调用中发送它。 由于调用正在发送数据， PostAsync 因此将使用该方法，而不是 GetAsync使用该方法。
可选：配置仅限应用的身份验证
在本部分中，你将更新上一部分中的应用注册，以支持 仅限应用的身份验证。 仅限应用的身份验证是后台服务的一个不错选择，还有一些 API 仅支持仅限应用的身份验证。 如果打算使用本教程的仅限应用的部分，则只需完成本部分。 如果没有，可以安全地跳到下一步。
重要
本部分中的步骤需要具有全局管理员角色的工作/学校帐户。
在 Azure AD 管理中心打开上一部分中的应用注册。
在“管理”下选择 “API 权限”。
通过选择其行中的省略号 (...) 并选择“删除权限”，删除配置权限下 的 默认 User.Read 权限。
选择 “添加权限”，然后 选择 Microsoft Graph。
选择 应用程序权限。
选择 User.Read.All，然后选择 “添加权限”。
选择 “授予管理员同意...”，然后选择 “是 ”以为所选权限提供管理员同意。
在 “管理” 下选择 “证书和机密”，然后选择 “新建客户端机密”。
输入说明，选择持续时间，然后选择 “添加”。
从 “值 ”列复制机密，在后续步骤中需要它。
重要
此客户端密码不会再次显示，所以请务必现在就复制它。
备注
请注意，与注册用户身份验证时的步骤不同，在本部分中确实配置了 Microsoft Graph 应用注册权限。 这是因为仅应用身份验证使用 客户端凭据流，这要求对应用注册配置权限。 有关详细信息，请参阅 .default 范围 。
可选：添加仅限应用的身份验证
在本部分中，你将向应用程序添加仅限应用的身份验证。 本部分是可选的，需要完成 可选：配置仅限应用的身份验证。 这些步骤只能使用工作或学校帐户完成。
为仅限应用的身份验证配置Graph客户端
在本部分中， ClientSecretCredential 你将使用该类通过使用 客户端凭据流请求访问令牌。
更新 appsettings.json (或 appsettings 中的值
tenantId。Development.json 使用组织的租户 ID) 。将客户端机密添加到 .NET Secret Manager。 在命令行接口中，将目录更改为 GraphTutorial.csproj 的位置，并运行以下命令，将客户端机密>替换< 为客户端机密。
dotnet user-secrets init dotnet user-secrets set settings:clientSecret <client-secret>备注
.NET 机密管理器仅在开发期间可用。 生产应用应将客户端机密存储在安全存储中，例如 Azure 密钥保管库。
打开 ./GraphHelper.cs 并将以下代码添加到 GraphHelper 类。
可选：列出用户
在本部分中，你将添加使用仅应用身份验证列出Azure Active Directory中所有用户的功能。 本部分是可选的，需要完成 可选：配置仅限应用的身份验证 和 可选：添加仅限应用的身份验证。 这些步骤只能使用工作或学校帐户完成。
打开 ./GraphHelper.cs 并将以下函数添加到 GraphHelper 类。
将 Program.cs 中的空
ListUsersAsync函数替换为以下内容。运行应用、登录并选择选项 4 列出用户。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 4 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? True
代码解释
考虑函数中的 GetUsersAsync 代码。 它与以下代码 GetInboxAsync非常相似：
- 它获取用户的集合
- 它用于
Select请求特定属性 - 它用于
Top限制返回的用户数 - 它用于
OrderBy对响应进行排序
关键区别在于，此代码使用而不是_userClient使用 _appClient。 两个客户端使用相同的语法和请求生成器，但配置了不同的凭据。
可选：添加自己的代码
在本部分中，你将向应用程序添加自己的 Microsoft Graph 功能。 这可能是 Microsoft Graph文档或Graph资源管理器或你创建的代码的代码片段。 本部分是可选的。
更新应用
打开 ./GraphHelper.cs 并将以下函数添加到 GraphHelper 类。
将 Program.cs 中的空
MakeGraphCallAsync函数替换为以下内容。
选择 API
在 Microsoft Graph中查找要尝试的 API。 例如， 创建事件 API。 可以使用 API 文档中的一个示例，也可以在Graph资源管理器中自定义 API 请求并使用生成的代码片段。
配置权限
检查所选 API 参考文档的 “权 限”部分，查看支持哪些身份验证方法。 例如，某些 API 不支持仅限应用或个人 Microsoft 帐户。
- 若要使用用户身份验证调用 API， (如果 API 支持用户 (委派) 身份验证) ，请在 appsettings.json 中添加所需的权限范围。
- 若要使用仅应用身份验证调用 API， (API 是否支持) ，请在 Azure AD 管理中心中添加所需的权限范围。
添加代码
将代码复制到 MakeGraphCallAsync GraphHelper.cs 中的函数 中。 如果要从文档或Graph资源管理器复制代码段，请务必将代码段重命名GraphServiceClient为适当的客户端：_userClient或 _appClient。
恭喜！
你已完成 .NET Microsoft Graph教程。 现在，你有一个调用 Microsoft Graph 的工作应用，可以试验和添加新功能。 请访问 Microsoft Graph概述，查看可以使用 Microsoft Graph 访问的所有数据。
.NET 示例
你有关于此部分的问题？ 如果有，请向我们提供反馈，以便我们对此部分作出改进。