使用 Microsoft Graph 和僅限應用程式驗證建置 .NET 應用程式

本教學課程會教導您如何建置使用 Microsoft Graph API 的 .NET 控制台應用程式，以使用僅限應用程式驗證來存取數據。 對於需要存取組織中所有用戶數據的背景服務或應用程式而言，僅限應用程式驗證是不錯的選擇。

在本教學課程中，您將：

• 列出使用者

必要條件

開始本教學課程之前，您應該先在開發計算機上安裝 .NET SDK 。

您也應該擁有具有全域管理員角色Microsoft公司或學校帳戶。 如果您沒有Microsoft 365 租使用者，您可能有資格透過 Microsoft 365 開發人員計劃;如需詳細資訊，請參閱 常見問題。 或者，您可以 註冊 1 個月的免費試用版，或購買Microsoft 365 方案。

在入口網站中註冊應用程式

• 剩餘 18 分鐘

在此練習中，您將在 Azure Active Directory 中註冊新的應用程式，以啟用 僅限應用程式的驗證。 您可以使用 Microsoft Entra 系統管理中心或使用 Microsoft Graph PowerShell SDK 來註冊應用程式。

註冊應用程式以進行僅限應用程式驗證

在本節中，您將使用 用戶端認證流程註冊支援僅限應用程式驗證的應用程式。

建立 .NET 主控台應用程式

• 剩餘 15 分鐘

首先，使用 .NET CLI 建立新的 .NET 控制台專案。

1. 在您要建立項目的目錄中， (CLI) 開啟命令行介面。 執行下列指令：

   dotnet new console -o GraphAppOnlyTutorial
   

2. 建立項目之後，請在 CLI 中將當前目錄變更為 GraphTutorial 目錄並執行下列命令，以確認其運作正常。

   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

載入應用程式設定

在本節中，您會將應用程式註冊的詳細數據新增至專案。

1. 在名為appsettings.json 的 GraphAppOnlyTutorial 目錄中建立檔案，並新增下列程序代碼。

   {
     "settings": {
       "clientId": "YOUR_CLIENT_ID_HERE",
       "tenantId": "YOUR_TENANT_ID_HERE"
     }
   }
   

2. 根據下表更新值。

   設定	值
   clientId	應用程式註冊的用戶端識別碼
   tenantId	您組織的租用戶標識碼。

   提示

   您可以選擇性地在名為 appsettings 的個別檔案中設定這些值 。Development.json。

3. 將您的客戶端密碼新增至 .NET 秘密管理員。 在命令行介面中，將目錄變更為 GraphAppOnlyTutorial.csproj 的位置，然後執行下列命令，並將 client-secret> 取代<為您的客戶端密碼。

   dotnet user-secrets init
   dotnet user-secrets set settings:clientSecret <client-secret>
   

4. 更新 GraphAppOnlyTutorial.csproj 以將 appsettings.json 複製到輸出目錄。 在和行之間<Project></Project>新增下列程序代碼。

   <ItemGroup>
     <None Include="appsettings*.json">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
   </ItemGroup>
   

5. 在名為Settings.cs 的 GraphAppOnlyTutorial 目錄中建立檔案，並新增下列程序代碼。

   using Microsoft.Extensions.Configuration;
   
   public class Settings
   {
       public string? ClientId { get; set; }
       public string? ClientSecret { get; set; }
       public string? TenantId { 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.");
       }
   }
   

設計應用程式

在本節中，您將建立簡單的控制台型功能表。

1. 開 啟 ./Program.cs ，並以下列程序代碼取代其整個內容。

   Console.WriteLine(".NET Graph App-only Tutorial\n");
   
   var settings = Settings.LoadSettings();
   
   // Initialize Graph
   InitializeGraph(settings);
   
   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 users");
       Console.WriteLine("3. 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 users
               await ListUsersAsync();
               break;
           case 3:
               // Run any Graph code
               await MakeGraphCallAsync();
               break;
           default:
               Console.WriteLine("Invalid choice! Please try again.");
               break;
       }
   }
   

2. 在文件尾新增下列佔位符方法。 您將在後續步驟中實作它們。

   void InitializeGraph(Settings settings)
   {
       // TODO
   }
   
   async Task DisplayAccessTokenAsync()
   {
       // TODO
   }
   
   async Task ListUsersAsync()
   {
       // TODO
   }
   
   async Task MakeGraphCallAsync()
   {
       // TODO
   }
   

這會實作基本功能表，並從命令行讀取用戶的選擇。

新增僅限應用程序驗證

• 剩餘 9 分鐘

在本節中，您會將僅限應用程式的驗證新增至應用程式。 這是取得必要的 OAuth 存取令牌以呼叫 Microsoft Graph 的必要專案。 在此步驟中，您會將 適用於 .NET 的 Azure 身分識別用戶端連結庫 整合到應用程式中，並設定 Microsoft Graph .NET 客戶端連結庫的驗證。

Azure 身分識別連結庫提供數個實作 OAuth2 令牌流程的 TokenCredential 類別。 Microsoft Graph 用戶端連結庫會使用這些類別來驗證對 Microsoft Graph 的呼叫。

設定僅限應用程式驗證的 Graph 用戶端

在本節中， ClientSecretCredential 您將使用 類別，使用 用戶端認證流程來要求存取令牌。

1. 在名為GraphHelper.cs 的 GraphTutorial 目錄中建立新檔案，並將下列程式代碼新增至該檔案。

   using Azure.Core;
   using Azure.Identity;
   using Microsoft.Graph;
   using Microsoft.Graph.Models;
   
   class GraphHelper
   {
   }
   

2. 將下列程式碼新增至 GraphHelper 類別。

   // Settings object
   private static Settings? _settings;
   // App-ony auth token credential
   private static ClientSecretCredential? _clientSecretCredential;
   // Client configured with app-only authentication
   private static GraphServiceClient? _appClient;
   
   public static void InitializeGraphForAppOnlyAuth(Settings settings)
   {
       _settings = settings;
   
       // Ensure settings isn't null
       _ = settings ??
           throw new System.NullReferenceException("Settings cannot be null");
   
       _settings = settings;
   
       if (_clientSecretCredential == null)
       {
           _clientSecretCredential = new ClientSecretCredential(
               _settings.TenantId, _settings.ClientId, _settings.ClientSecret);
       }
   
       if (_appClient == null)
       {
           _appClient = new GraphServiceClient(_clientSecretCredential,
               // Use the default scope, which will request the scopes
               // configured on the app registration
               new[] {"https://graph.microsoft.com/.default"});
       }
   }
   

3. 以下列內容取代 Program.cs 中的空白InitializeGraph函式。

   void InitializeGraph(Settings settings)
   {
       GraphHelper.InitializeGraphForAppOnlyAuth(settings);
   }
   

此程式代碼會宣告兩個 ClientSecretCredential 私用屬性：對象和 GraphServiceClient 物件。 函 InitializeGraphForAppOnlyAuth 式會建立 的新實例 ClientSecretCredential，然後使用該實例來建立 的新實 GraphServiceClient例。 每次呼叫 API 以透過 Microsoft Graph _appClient時，都會使用提供的認證來取得存取令牌。

測試 ClientSecretCredential

接下來，新增程式代碼以從 ClientSecretCredential取得存取令牌。

1. 將下列函式新增至 GraphHelper 類別。

   public static async Task<string> GetAppOnlyTokenAsync()
   {
       // Ensure credential isn't null
       _ = _clientSecretCredential ??
           throw new System.NullReferenceException("Graph has not been initialized for app-only auth");
   
       // Request token with given scopes
       var context = new TokenRequestContext(new[] {"https://graph.microsoft.com/.default"});
       var response = await _clientSecretCredential.GetTokenAsync(context);
       return response.Token;
   }
   

2. 以下列內容取代 Program.cs 中的空白DisplayAccessTokenAsync函式。

   async Task DisplayAccessTokenAsync()
   {
       try
       {
           var appOnlyToken = await GraphHelper.GetAppOnlyTokenAsync();
           Console.WriteLine($"App-only token: {appOnlyToken}");
       }
       catch (Exception ex)
       {
           Console.WriteLine($"Error getting app-only access token: {ex.Message}");
       }
   }
   

3. 建置並執行應用程式。 當系統提示您輸入選項時，請輸入 1 。 應用程式會顯示存取令牌。

   .NET Graph Tutorial
   
   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List users
   3. Make a Graph call
   1
   App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
   

   提示

   僅供驗證和偵錯之用，您可以在 使用 Microsoft 的在線令牌剖析器https://jwt.ms來譯碼僅限應用程式的存取令牌。 如果您在呼叫 Microsoft Graph 時遇到令牌錯誤，這會很有用。 例如，確認 role 令牌中的宣告包含預期的 Microsoft Graph 許可權範圍。

列出使用者

• 剩餘 6 分鐘

在本節中，您將新增使用僅限應用程式驗證列出 Azure Active Directory 中所有使用者的功能。

1. 開 啟 ./GraphHelper.cs ，並將下列函式新增至 GraphHelper 類別。

   public static Task<UserCollectionResponse?> GetUsersAsync()
   {
       // Ensure client isn't null
       _ = _appClient ??
           throw new System.NullReferenceException("Graph has not been initialized for app-only auth");
   
       return _appClient.Users.GetAsync((config) =>
       {
           // Only request specific properties
           config.QueryParameters.Select = new[] { "displayName", "id", "mail" };
           // Get at most 25 results
           config.QueryParameters.Top = 25;
           // Sort by display name
           config.QueryParameters.Orderby = new[] { "displayName" };
       });
   }
   

2. 以下列內容取代 Program.cs 中的空白ListUsersAsync函式。

   async Task ListUsersAsync()
   {
       try
       {
           var userPage = await GraphHelper.GetUsersAsync();
   
           if (userPage?.Value == null)
           {
               Console.WriteLine("No results returned.");
               return;
           }
   
           // Output each users's details
           foreach (var user in userPage.Value)
           {
               Console.WriteLine($"User: {user.DisplayName ?? "NO NAME"}");
               Console.WriteLine($"  ID: {user.Id}");
               Console.WriteLine($"  Email: {user.Mail ?? "NO EMAIL"}");
           }
   
           // If NextPageRequest is not null, there are more users
           // available on the server
           // Access the next page like:
           // var nextPageRequest = new UsersRequestBuilder(userPage.OdataNextLink, _appClient.RequestAdapter);
           // var nextPage = await nextPageRequest.GetAsync();
           var moreAvailable = !string.IsNullOrEmpty(userPage.OdataNextLink);
   
           Console.WriteLine($"\nMore users available? {moreAvailable}");
       }
       catch (Exception ex)
       {
           Console.WriteLine($"Error getting users: {ex.Message}");
       }
   }
   

3. 執行應用程式，然後選擇選項 2 以列出使用者。

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List users
   3. Make a Graph call
   2
   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 代碼。

• 它會取得使用者的集合
• 它會使用 Select 來要求特定屬性
• 它會使用 Top 來限制傳回的用戶數目
• 它會使用 OrderBy 來排序回應

選擇性：新增您自己的程序代碼

• 剩餘 4 分鐘

在本節中，您會將自己的 Microsoft Graph 功能新增至應用程式。 這可能是來自 Microsoft Graph 檔 或 Graph 總管的代碼段，或您所建立的程式碼。 此區段為選擇性。

更新應用程式

1. 開 啟 ./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
   }
   

2. 以下列內容取代 Program.cs 中的空白MakeGraphCallAsync函式。

   async Task MakeGraphCallAsync()
   {
       await GraphHelper.MakeGraphCallAsync();
   }
   

選擇 API

在您想要嘗試Microsoft圖形中尋找 API。 例如， 建立事件 API。 您可以使用 API 檔中的其中一個範例，也可以自訂範例。

設定許可權

請查看所選取 API 參考檔的 [許可權] 區段， 以查看支援哪些驗證方法。 例如，某些 API 不支援僅限應用程式或個人Microsoft帳戶。

• 若要在 API 支援使用者 (委派的) 驗證) 時，使用使用者驗證 (呼叫 API，請參閱 使用者 (委派的) 驗證 教學課程。
• 若要使用僅限應用程式的驗證來呼叫 API (如果 API 支援它) ，請在 Azure AD 系統管理中心新增必要的許可權範圍。

新增您的程序代碼

將您的程式代碼複製到 MakeGraphCallAsync GraphHelper.cs 中的函 式。 如果您要從檔案或 Graph 總管複製代碼段，請務必將 重新命名 GraphServiceClient 為 _appClient。

恭喜！

• 100% 完成！

您已完成 .NET Microsoft Graph 教學課程。 既然您有一個可呼叫 Microsoft Graph 的工作應用程式，您可以實驗並新增新功能。

• 瞭解如何使用 使用者 (委派的) 驗證 搭配 Microsoft Graph .NET SDK。
• 請造訪 Microsoft Graph 概觀 ，以查看您可以使用 Microsoft Graph 存取的所有數據。

.NET 範例

• ASP.NET Core MVC 應用程式
• 通用 Windows 平臺 (UWP) 應用程式
• Xamarin 應用程式
• Blazor WebAssembly 應用程式
• Azure Functions
• Bot Framework
• Teams 應用程式
• 變更通知
• ASP.NET 核心代碼段