使用 Microsoft Graph 生成 .NET 应用
本教程介绍如何生成使用 Microsoft Graph API 代表用户访问数据的 .NET 控制台应用。
备注
若要了解如何使用 Microsoft Graph 通过仅限应用的身份验证访问数据,请参阅此 仅限应用的身份验证教程。
在本教程中,你将:
- 获取已登录用户
- 列出用户的收件箱邮件
- "发送电子邮件"
提示
作为本教程的替代方法,可以通过 快速启动 工具下载完成的代码,该工具可自动执行应用注册和配置。 下载的代码无需进行任何修改即可正常工作。
还可以下载或克隆 GitHub 存储库 ,并按照 README 中的说明注册应用程序并配置项目。
先决条件
在开始本教程之前,应在开发计算机上安装 .NET SDK 。
还应该有一个包含 Exchange Online 邮箱Microsoft工作或学校帐户。 如果没有 Microsoft 365 租户,则可以通过 Microsoft 365 开发人员计划获得租户;有关详细信息,请参阅 常见问题解答。 或者,可以 注册 1 个月的免费试用版或购买 Microsoft 365 计划。
备注
本教程使用 .NET SDK 版本 7.0.102 编写。 本指南中的步骤可能适用于其他版本,但尚未测试。
在门户中注册该应用
在本练习中,你将在 Azure Active Directory 中注册一个新应用程序以启用 用户身份验证。 可以使用 Microsoft Entra 管理中心或使用 Microsoft Graph PowerShell SDK 注册应用程序。
注册应用程序进行用户身份验证
在本部分中,你将注册一个支持使用 设备代码流进行用户身份验证的应用程序。
打开浏览器,导航到 Microsoft Entra 管理中心 ,并使用全局管理员帐户登录。
在左侧导航栏中选择“Microsoft Entra ID”,依次展开“标识”、“应用程序”和“应用注册”。
选择“新注册”。 输入应用程序的名称,例如
Graph User Auth Tutorial
。根据需要设置 支持的帐户类型 。 选项包括:
选项 谁可以登录? 仅限此组织目录中的帐户 仅限 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 Microsoft.Extensions.Configuration.UserSecrets
dotnet add package Azure.Identity
dotnet add package Microsoft.Graph
加载应用程序设置
在本部分中,你将向项目添加应用注册的详细信息。
在 GraphTutorial 目录中创建名为 appsettings.json 的文件,并添加以下代码。
{ "settings": { "clientId": "YOUR_CLIENT_ID_HERE", "tenantId": "common", "graphUserScopes": [ "user.read", "mail.read", "mail.send" ] } }
根据下表更新值。
设置 值 clientId
应用注册的客户端 ID tenantId
如果选择了仅允许组织中的用户登录的选项,请将此值更改为租户 ID。 否则保留为 common
。提示
(可选)可以在名为 appsettings 的单独文件中设置这些值 。Development.json,或在 .NET 机密管理器中。
更新 GraphTutorial.csproj 以将 appsettings.json 复制到输出目录。 在 和
</Project>
行之间<Project>
添加以下代码。<ItemGroup> <None Include="appsettings*.json"> <CopyToOutputDirectory>Always</CopyToOutputDirectory> </None> </ItemGroup>
在 GraphTutorial 目录中创建一个名为 Settings.cs 的文件,并添加以下代码。
using Microsoft.Extensions.Configuration; public class Settings { public string? ClientId { get; set; } public string? TenantId { get; set; } public string[]? GraphUserScopes { get; set; } public static Settings LoadSettings() { // Load settings IConfiguration config = new ConfigurationBuilder() // appsettings.json is required .AddJsonFile("appsettings.json", optional: false) // appsettings.Development.json" is optional, values override appsettings.json .AddJsonFile($"appsettings.Development.json", optional: true) // User secrets are optional, values override both JSON files .AddUserSecrets<Program>() .Build(); return config.GetRequiredSection("Settings").Get<Settings>() ?? throw new Exception("Could not load app settings. See README for configuration instructions."); } }
设计应用
在本部分中,你将创建一个基于控制台的简单菜单。
打开 ./Program.cs ,并将其全部内容替换为以下代码。
Console.WriteLine(".NET Graph Tutorial\n"); var settings = Settings.LoadSettings(); // Initialize Graph InitializeGraph(settings); // Greet the user by name await GreetUserAsync(); int choice = -1; while (choice != 0) { Console.WriteLine("Please choose one of the following options:"); Console.WriteLine("0. Exit"); Console.WriteLine("1. Display access token"); Console.WriteLine("2. List my inbox"); Console.WriteLine("3. Send mail"); Console.WriteLine("4. Make a Graph call"); try { choice = int.Parse(Console.ReadLine() ?? string.Empty); } catch (System.FormatException) { // Set to invalid value choice = -1; } switch(choice) { case 0: // Exit the program Console.WriteLine("Goodbye..."); break; case 1: // Display access token await DisplayAccessTokenAsync(); break; case 2: // List emails from user's inbox await ListInboxAsync(); break; case 3: // Send an email message await SendMailAsync(); break; case 4: // Run any Graph code await MakeGraphCallAsync(); break; default: Console.WriteLine("Invalid choice! Please try again."); break; } }
在文件末尾添加以下占位符方法。 你将在后面的步骤中实现它们。
void InitializeGraph(Settings settings) { // TODO } async Task GreetUserAsync() { // TODO } async Task DisplayAccessTokenAsync() { // TODO } async Task ListInboxAsync() { // TODO } async Task SendMailAsync() { // TODO } async Task MakeGraphCallAsync() { // TODO }
这将实现基本菜单,并从命令行读取用户的选择。
添加用户身份验证
在本部分中,将扩展上一练习中的应用程序,以支持使用 Azure AD 进行身份验证。 这是获取调用 Microsoft Graph 所需的 OAuth 访问令牌所必需的。 在此步骤中,你将 将适用于 .NET 的 Azure 标识客户端库 集成到应用程序中,并为 Microsoft Graph .NET 客户端库配置身份验证。
Azure 标识库提供了许多 TokenCredential
实现 OAuth2 令牌流的类。 Microsoft Graph 客户端库使用这些类对 Microsoft Graph 的调用进行身份验证。
配置 Graph 客户端以用于用户身份验证
在本部分中, DeviceCodeCredential
你将使用 类通过 设备代码流请求访问令牌。
在 GraphTutorial 目录中创建名为 GraphHelper.cs 的新文件,并将以下代码添加到该文件。
using Azure.Core; using Azure.Identity; using Microsoft.Graph; using Microsoft.Graph.Models; using Microsoft.Graph.Me.SendMail; class GraphHelper { }
将以下代码添加到
GraphHelper
类。// Settings object private static Settings? _settings; // User auth token credential private static DeviceCodeCredential? _deviceCodeCredential; // Client configured with user authentication private static GraphServiceClient? _userClient; public static void InitializeGraphForUserAuth(Settings settings, Func<DeviceCodeInfo, CancellationToken, Task> deviceCodePrompt) { _settings = settings; var options = new DeviceCodeCredentialOptions { ClientId = settings.ClientId, TenantId = settings.TenantId, DeviceCodeCallback = deviceCodePrompt, }; _deviceCodeCredential = new DeviceCodeCredential(options); _userClient = new GraphServiceClient(_deviceCodeCredential, settings.GraphUserScopes); }
将 Program.cs 中的空
InitializeGraph
函数替换为以下内容。void InitializeGraph(Settings settings) { GraphHelper.InitializeGraphForUserAuth(settings, (info, cancel) => { // Display the device code message to // the user. This tells them // where to go to sign in and provides the // code to use. Console.WriteLine(info.Message); return Task.FromResult(0); }); }
此代码声明两个 DeviceCodeCredential
私有属性:对象和 GraphServiceClient
对象。 函数 InitializeGraphForUserAuth
创建 的新实例 DeviceCodeCredential
,然后使用该实例创建 的新 GraphServiceClient
实例。 每次通过 _userClient
进行 API 调用以Microsoft Graph 时,都会使用提供的凭据来获取访问令牌。
测试 DeviceCodeCredential
接下来,添加代码以从 DeviceCodeCredential
获取访问令牌。
将以下函数添加到
GraphHelper
类。public static async Task<string> GetUserTokenAsync() { // Ensure credential isn't null _ = _deviceCodeCredential ?? throw new System.NullReferenceException("Graph has not been initialized for user auth"); // Ensure scopes isn't null _ = _settings?.GraphUserScopes ?? throw new System.ArgumentNullException("Argument 'scopes' cannot be null"); // Request token with given scopes var context = new TokenRequestContext(_settings.GraphUserScopes); var response = await _deviceCodeCredential.GetTokenAsync(context); return response.Token; }
将 Program.cs 中的空
DisplayAccessTokenAsync
函数替换为以下内容。async Task DisplayAccessTokenAsync() { try { var userToken = await GraphHelper.GetUserTokenAsync(); Console.WriteLine($"User token: {userToken}"); } catch (Exception ex) { Console.WriteLine($"Error getting user access token: {ex.Message}"); } }
生成并运行应用。 当系统提示输入选项时,请输入
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. Make a Graph call 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 类。
public static Task<User?> GetUserAsync() { // Ensure client isn't null _ = _userClient ?? throw new System.NullReferenceException("Graph has not been initialized for user auth"); return _userClient.Me.GetAsync((config) => { // Only request specific properties config.QueryParameters.Select = new[] {"displayName", "mail", "userPrincipalName" }; }); }
将 Program.cs 中的空
GreetUserAsync
函数替换为以下内容。async Task GreetUserAsync() { try { var user = await GraphHelper.GetUserAsync(); Console.WriteLine($"Hello, {user?.DisplayName}!"); // For Work/school accounts, email is in Mail property // Personal accounts, email is in UserPrincipalName Console.WriteLine($"Email: {user?.Mail ?? user?.UserPrincipalName ?? ""}"); } catch (Exception ex) { Console.WriteLine($"Error getting user: {ex.Message}"); } }
如果立即运行应用,则登录后应用将按名称欢迎你。
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 的 JSON 响应返回 Microsoft.Graph.User
反序列化的对象。 由于代码使用 Select
,因此只有请求的属性在返回 User
的对象中具有值。 所有其他属性都具有默认值。
列出收件箱
在本部分中,你将添加在用户的电子邮件收件箱中列出邮件的功能。
打开 ./GraphHelper.cs 并将以下函数添加到 GraphHelper 类。
public static Task<MessageCollectionResponse?> GetInboxAsync() { // Ensure client isn't null _ = _userClient ?? throw new System.NullReferenceException("Graph has not been initialized for user auth"); return _userClient.Me // Only messages from Inbox folder .MailFolders["Inbox"] .Messages .GetAsync((config) => { // Only request specific properties config.QueryParameters.Select = new[] { "from", "isRead", "receivedDateTime", "subject" }; // Get at most 25 results config.QueryParameters.Top = 25; // Sort by received time, newest first config.QueryParameters.Orderby = new[] { "receivedDateTime DESC" }; }); }
将 Program.cs 中的空
ListInboxAsync
函数替换为以下内容。async Task ListInboxAsync() { try { var messagePage = await GraphHelper.GetInboxAsync(); if (messagePage?.Value == null) { Console.WriteLine("No results returned."); return; } // Output each message's details foreach (var message in messagePage.Value) { Console.WriteLine($"Message: {message.Subject ?? "NO SUBJECT"}"); Console.WriteLine($" From: {message.From?.EmailAddress?.Name}"); Console.WriteLine($" Status: {(message.IsRead!.Value ? "Read" : "Unread")}"); Console.WriteLine($" Received: {message.ReceivedDateTime?.ToLocalTime().ToString()}"); } // If NextPageRequest is not null, there are more messages // available on the server // Access the next page like: // var nextPageRequest = new MessagesRequestBuilder(messagePage.OdataNextLink, _userClient.RequestAdapter); // var nextPage = await nextPageRequest.GetAsync(); var moreAvailable = !string.IsNullOrEmpty(messagePage.OdataNextLink); Console.WriteLine($"\nMore messages available? {moreAvailable}"); } catch (Exception ex) { Console.WriteLine($"Error getting user's inbox: {ex.Message}"); } }
运行应用,登录,然后选择选项 2 列出收件箱。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. 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 类。
public static async Task SendMailAsync(string subject, string body, string recipient) { // Ensure client isn't null _ = _userClient ?? throw new System.NullReferenceException("Graph has not been initialized for user auth"); // Create a new message var message = new Message { Subject = subject, Body = new ItemBody { Content = body, ContentType = BodyType.Text }, ToRecipients = new List<Recipient> { new Recipient { EmailAddress = new EmailAddress { Address = recipient } } } }; // Send the message await _userClient.Me .SendMail .PostAsync(new SendMailPostRequestBody { Message = message }); }
将 Program.cs 中的空
SendMailAsync
函数替换为以下内容。async Task SendMailAsync() { try { // Send mail to the signed-in user // Get the user for their email address var user = await GraphHelper.GetUserAsync(); var userEmail = user?.Mail ?? user?.UserPrincipalName; if (string.IsNullOrEmpty(userEmail)) { Console.WriteLine("Couldn't get your email address, canceling..."); return; } await GraphHelper.SendMailAsync("Testing Microsoft Graph", "Hello world!", userEmail); Console.WriteLine("Mail sent."); } catch (Exception ex) { Console.WriteLine($"Error sending mail: {ex.Message}"); } }
运行应用,登录并选择选项 3 以向自己发送电子邮件。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. Make a Graph call 3 Mail sent.
备注
如果使用 Microsoft 365 开发人员计划中的开发人员租户进行测试,则发送的电子邮件可能未送达,并且可能会收到未送达报告。 如果发生这种情况,请通过 Microsoft 365 管理中心联系支持人员。
若要验证是否已收到邮件,请选择选项 2 列出收件箱。
代码说明
请考虑 函数中的 SendMailAsync
代码。
发送邮件
函数使用 _userClient.Me.SendMail
请求生成器,该生成器生成对 发送邮件 API 的请求。 请求生成器采用表示 Message
要发送的消息的 对象。
创建对象
与以前调用 Microsoft Graph(仅读取数据)不同,此调用会创建数据。 若要使用客户端库执行此操作,请创建表示数据 (的类的实例,在本例中, Microsoft.Graph.Message
) 使用 new
关键字,设置所需的属性,然后在 API 调用中发送它。 由于调用正在发送数据,因此使用 PostAsync
方法而不是 GetAsync
。
可选:添加自己的代码
在本部分中,将向应用程序添加自己的 Microsoft Graph 功能。 这可能是Microsoft Graph 文档 或 Graph 资源管理器中的代码片段,也可以是你创建的代码片段。 此部分是可选的。
更新应用
打开 ./GraphHelper.cs 并将以下函数添加到 GraphHelper 类。
// This function serves as a playground for testing Graph snippets // or other code public async static Task MakeGraphCallAsync() { // INSERT YOUR CODE HERE }
将 Program.cs 中的空
MakeGraphCallAsync
函数替换为以下内容。async Task MakeGraphCallAsync() { await GraphHelper.MakeGraphCallAsync(); }
选择 API
在 Microsoft Graph 中查找想要尝试的 API。 例如, 创建事件 API。 可以使用 API 文档中的示例之一,也可以在 Graph 资源管理器中自定义 API 请求并使用生成的代码片段。
配置权限
查看所选 API 的参考文档 的“权限” 部分,了解支持哪些身份验证方法。 例如,某些 API 不支持仅限应用或个人Microsoft帐户。
- 若要调用具有用户身份验证 (API(如果 API 支持用户 (委托) 身份验证) ),请在 appsettings.json 中添加所需的权限范围。
- 若要使用仅应用身份验证调用 API,请参阅 仅限应用的身份验证 教程。
添加代码
将代码复制到 MakeGraphCallAsync
GraphHelper.cs 中的 函数中。 如果要从文档或 Graph 资源管理器复制代码片段,请务必将 重命名 GraphServiceClient
为 _userClient
。
恭喜!
已完成 .NET Microsoft Graph 教程。 现在,你已有一个可调用 Microsoft Graph 的工作应用,可以试验和添加新功能。
- 了解如何通过 Microsoft Graph .NET SDK 使用 仅限应用的身份验证 。
- 访问 Microsoft Graph 概述 ,查看可以使用 Microsoft Graph 访问的所有数据。
.NET 示例
你有关于此部分的问题? 如果有,请向我们提供反馈,以便我们对此部分作出改进。