快速入門：在通用 Windows 平台應用程式中登入使用者並呼叫 Microsoft Graph - Microsoft identity platform

發行項
11/23/2024

在本快速入門中，您會下載並執行程式碼範例，該範例會示範通用 Windows 平台 (UWP) 應用程式如何登入使用者，並取得存取權杖來呼叫 Microsoft Graph API。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
Visual Studio

注意

MSAL.NET 版本 4.61.0 和更新版本不支援通用 Windows 平台 (UWP)、Xamarin Android 和 Xamarin iOS。建議您將 UWP 應用程式移轉至 WINUI 等新式架構。深入瞭解宣佈即將淘汰適用於 Xamarin 和 UWP 的 MSAL.NET。

註冊並下載快速入門應用程式

有兩個選項可用來啟動快速入門應用程式：

[快速] 選項 1：註冊和自動設定您的應用程式，然後下載程式碼範例
[手動] 選項 2：註冊並手動設定您的應用程式和程式碼範例

選項 1：註冊和自動設定您的應用程式，然後下載程式碼範例

前往 AMicrosoft Entra 系統管理中心 - 應用程式註冊快速入門體驗。
輸入應用程式的名稱，並選取 [註冊]。
依照指示來下載並自動設定新應用程式。

選項 2：註冊並手動設定您的應用程式和程式碼範例

步驟 1：註冊您的應用程式

提示

本文中的步驟可能會依據您開始的入口網站而稍有不同。

若要註冊您的應用程式，並將應用程式註冊資訊新增到您的解決方案，請執行下列步驟：

登入 Microsoft Entra 系統管理中心。
若有權存取多個租用戶，請使用頂端功能表中的 [設定] 圖示，以從 [目錄 + 訂用帳戶] 功能表中切換至您想要在其中註冊應用程式的租用戶。
瀏覽至 [身分識別]>[應用程式]>[應用程式註冊]，選取 [新增註冊]。
輸入應用程式的名稱，例如 UWP-App-calling-MsGraph。您的應用程式使用者可能會看到此名稱，而且您稍後可以加以變更。
在 [支援的帳戶類型] 區段中，選取 [任何組織目錄中的帳戶及個人的 Microsoft 帳戶]，例如 Skype、Xbox、Outlook.com。
選取 [註冊] 以建立應用程式，然後記錄 [應用程式 (用戶端) 識別碼] 以供在稍後的步驟中使用。
在 [管理] 底下，選取 [驗證]。
選取 [新增平台]>[行動和傳統應用程式]。
在 [重新導向 URI] 之下，選取 https://login.microsoftonline.com/common/oauth2/nativeclient。
選取設定。

步驟 2：下載專案

下載 UWP 範例應用程式

提示

為了避免 Windows 中路徑長度限制所造成的錯誤，建議您將封存解壓縮或將存放庫複製到磁碟機根目錄附近的目錄中。

步驟 3：設定專案

將 .zip 封存檔解壓縮至靠近磁碟機根目錄的本機資料夾。例如，解壓縮至 C:\Azure-Samples。
在 Visual Studio 中開啟專案。安裝 [通用 Windows 平台開發] 工作負載和任何個別的 SDK 元件 (如果出現提示)。
在 MainPage.Xaml.cs 中，將 ClientId 變數的值變更為您稍早註冊之應用程式的 [應用程式 (用戶端) 識別碼]。
```
private const string ClientId = "Enter_the_Application_Id_here";
```
您可以在 Microsoft Entra 系統管理中心的 [概觀] 窗格中找到 應用程式 (用戶端) 識別碼 ([身分識別]>[應用程式]>[應用程式註冊]>{您的應用程式註冊})。
建立而後選取封裝新的自我簽署測試憑證：
1. 在 [方案總管] 中，按兩下 Package.appxmanifest 檔案。
2. 選取 [封裝]>[選擇憑證...]>[建立...]。
3. 輸入密碼，然後選取 [確定]。名稱為 Native_UWP_V2_TemporaryKey.pfx 的憑證隨即建立。
4. 選取 [確定] 以關閉 [選擇憑證] 對話方塊，然後確認您在方案總管中看到 Native_UWP_V2_TemporaryKey.pfx。
5. 在 [方案總管] 中，於 Native_UWP_V2 專案上按一下滑鼠右鍵，然後選取 [屬性]。
6. 選取 [簽署]，然後選取您在 [選擇強式名稱金鑰檔案] 下拉式集中建立的 .pfx。

步驟 4：執行應用程式

若要在您的本機電腦上執行範例應用程式：

在 Visual Studio 工具列中，選擇正確的平台 (可能是 x64 或 x86，但不是 ARM)。目標裝置應從「裝置」變成「本機電腦」。
選取 [偵錯]>[啟動但不偵錯]。

如果系統提示您這麼做，您可能必須先啟用 [開發人員模式]，然後再次 [啟動但不偵錯] 以啟動應用程式。

當應用程式的視窗出現時，您可以選取 [呼叫 Microsoft Graph API] 按鈕，輸入您的認證，然後同意應用程式所要求的權限。如果成功，應用程式會顯示一些權杖資訊，以及從呼叫 Microsoft Graph API 取得的資料。

此範例的運作方式

此圖表顯示此快速入門所產生的範例應用程式的運作方式。

MSAL.NET

MSAL (Microsoft.Identity.Client) 是用來登入使用者並要求安全性權杖的程式庫。安全性權杖可用來存取受 Microsoft 身分識別平台保護的 API。您可以在 Visual Studio 的 [套件管理員主控台] 中，透過執行下列命令來安裝 MSAL：

Install-Package Microsoft.Identity.Client

MSAL 初始化

您可以透過加入下列程式碼來新增 MSAL 的參考：

using Microsoft.Identity.Client;

接著，系統便會使用下列程式碼將 MSAL 初始化：

public static IPublicClientApplication PublicClientApp;
PublicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                                                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                                                    .Build();

ClientId 的值是您在 Microsoft Entra 系統管理中心註冊的應用程式的 應用程式 (用戶端) 識別碼。您可以在 Microsoft Entra 系統管理中心的應用程式 [概觀] 頁面中找到這個值。

要求權杖

MSAL 有兩種方法可取得 UWP 應用程式中的權杖：AcquireTokenInteractive 與 AcquireTokenSilent。

以互動方式取得使用者權杖

有些情況需要強制使用者透過快顯視窗與 Microsoft 身分識別平台進行互動，以驗證其認證或取得同意。這些範例包含：

使用者首次登入應用程式
使用者因為密碼已過期而可能需要重新輸入其認證時
您的應用程式要求存取的資源需要使用者同意時
需要雙因素驗證時

authResult = await PublicClientApp.AcquireTokenInteractive(scopes)
                      .ExecuteAsync();

scopes 參數包含所要求的範圍，例如適用於 Microsoft Graph 的 { "user.read" } 或適用於自訂 Web API 的 { "api://<Application ID>/access_as_user" }。

以無訊息方式取得使用者權杖

在初始的 AcquireTokenInteractive 方法之後，使用 AcquireTokenSilent 方法來取得權杖以存取受保護的資源。您不應該在每次使用者需要存取資源時都要求使用者驗證其認證。在大部分情況下，您應該以不需要與使用者進行任何互動的方式處理權杖取得和更新作業

var accounts = await PublicClientApp.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await PublicClientApp.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();

scopes 包含所要求的範圍，例如適用於 Microsoft Graph 的 { "user.read" } 或適用於自訂 Web API 的 { "api://<Application ID>/access_as_user" }。
firstAccount 指定快取中的第一個使用者帳戶 (MSAL 在單一應用程式中支援多個使用者)。

說明與支援

如果您需要協助、想要回報問題，或想要深入了解您的支援選項，請參閱開發人員的協助與支援。

下一步

嘗試 Windows Desktop 教學課程以取得建置應用程式與新功能的完整逐步指南，包括此快速入門的完整說明。

UWP - 呼叫圖形 API 教學課程

共用方式為