Öğretici: Windows Presentation Foundation (WPF) masaüstü uygulamasında kullanıcılarda oturum açma ve Microsoft Graph'ı çağırma

Bu öğreticide, kullanıcılarda oturum açıp Microsoft Graph API'sini çağırmak için erişim belirteci alan bir yerel Windows Masaüstü .NET (XAML) uygulaması oluşturacaksınız.

Kılavuzu tamamladığınızda uygulamanız kişisel hesapları (outlook.com, live.com ve diğerleri dahil) kullanan korumalı bir API çağırabilecektir. Uygulama ayrıca Microsoft Entra Id kullanan herhangi bir şirket veya kuruluşa ait iş ve okul hesaplarını da kullanacaktır.

Bu öğreticide:

• Visual Studio'da Windows Presentation Foundation (WPF) projesi oluşturma
• .NET için Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) yükleme
• Uygulamayı kaydetme
• Kullanıcı oturum açma ve oturum kapatmayı desteklemek için kod ekleme
• Microsoft Graph API'sini çağırmak için kod ekleme
• Uygulamayı test etme

Önkoşullar

• .NET Framework 4.8
• Visual Studio 2019

Bu kılavuz tarafından oluşturulan örnek uygulama nasıl çalışır?

Bu kılavuzla oluşturduğunuz örnek uygulama, Microsoft Graph API'sini sorgulayan bir Windows Masaüstü uygulamasını veya Microsoft kimlik platformu uç noktasından belirteçleri kabul eden bir web API'sini etkinleştirir. Bu senaryo için, Yetkilendirme üst bilgisi aracılığıyla HTTP isteklerine bir belirteç eklersiniz. Microsoft Kimlik Doğrulama Kitaplığı (MSAL), belirteç alma ve yenileme işlemlerini gerçekleştirir.

Korumalı web API'lerine erişmek için belirteç alımını işleme

Kullanıcının kimliği doğrulandıktan sonra örnek uygulama, Microsoft Graph API'sini veya Microsoft kimlik platformu tarafından güvenliği sağlanan bir web API'sini sorgulamak için kullanabileceğiniz bir belirteç alır.

Microsoft Graph gibi API'ler, belirli kaynaklara erişime izin vermek için bir belirteç gerektirir. Örneğin, bir kullanıcının profilini okumak, kullanıcının takvimine erişmek veya e-posta göndermek için belirteç gereklidir. Uygulamanız, API kapsamları belirterek bu kaynaklara erişmek için MSAL kullanarak erişim belirteci isteyebilir. Bu erişim belirteci daha sonra korumalı kaynağa karşı yapılan her çağrı için HTTP Yetkilendirme üst bilgisine eklenir.

MSAL, uygulamanızın ihtiyaç duymaması için erişim belirteçlerini önbelleğe almayı ve yenilemeyi sizin yerinize yönetir.

NuGet paketleri

Bu kılavuzda aşağıdaki NuGet paketleri kullanılır:

Kitaplık	Açıklama
Microsoft.Identity.Client	Microsoft Kimlik Doğrulama Kitaplığı (MSAL.NET)

Projenizi ayarlama

Bu bölümde, bir Windows Masaüstü .NET uygulamasının (XAML) Microsoft ile Oturum Açma ile nasıl tümleştirildiğini göstermek için yeni bir proje oluşturacaksınız, böylece uygulama belirteç gerektiren web API'lerini sorgulayabilir.

Oluşturacağınız uygulama, Microsoft Graph API'sini çağıracak bir düğme, sonuçları görüntülemek için bir alan ve bir oturumu kapatma düğmesi görüntüler.

Not

Bunun yerine bu örneğin Visual Studio projesini indirmeyi mi tercih ediyorsunuz? Bir proje indirin ve kod örneğini yürütmeden önce yapılandırmak için Yapılandırma adımına atlayın.

Aşağıdaki adımları kullanarak uygulamayı oluşturun:

1. Visual Studio’yu açın
2. Başlangıç penceresinde Yeni proje oluştur'u seçin.
3. Tüm dil açılan listesinde C# öğesini seçin.
4. WPF Uygulaması (.NET Framework) şablonunu arayıp seçin ve ardından İleri'yi seçin.
5. Proje adı kutusuna Win-App-calling-MsGraph gibi bir ad girin.
6. Proje için bir Konum seçin veya varsayılan seçeneği kabul edin.
7. Framework'te .NET Framework 4.8'i seçin.
8. Oluştur'u belirleyin.

Projenize MSAL ekleme

1. Visual Studio'da, Araçlar>NuGet Paket Yöneticisi>Paket Yönetici Konsolu'nu seçin.

2. Paket Yöneticisi Konsolu penceresinde aşağıdaki Azure PowerShell komutunu yapıştırın:

   Install-Package Microsoft.Identity.Client -Pre
   

Uygulamanızı kaydetme

İpucu

Bu makaledeki adımlar, başladığınız portala göre biraz değişiklik gösterebilir.

Uygulamanızı kaydetmek ve yapılandırmak için şu adımları izleyin:

1. Microsoft Entra yönetim merkezinde en azından Uygulama Geliştiricisi olarak oturum açın.
2. Birden çok kiracıya erişiminiz varsa, dizinler + abonelikler menüsünden uygulamayı kaydetmek istediğiniz kiracıya geçmek için üst menüdeki Ayarlar simgesini kullanın.
3. Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları.
4. Yeni kayıt öğesini seçin.
5. Uygulamanız için bir Ad girin, örneğin Win-App-calling-MsGraph. Uygulamanızın kullanıcıları bu adı görebilir ve daha sonra değiştirebilirsiniz.
6. Desteklenen hesap türleri bölümünde, herhangi bir kuruluş dizininde (Herhangi bir Microsoft Entra dizini - Çok Kiracılı) ve kişisel Microsoft hesaplarında (örneğin Skype, Xbox) Hesaplar'ı seçin.
7. Kaydet'i seçin.
8. Yönet'in altında Kimlik Doğrulaması>Platform ekle'yi seçin.
9. Mobil ve masaüstü uygulamaları'nı seçin.
10. Yeniden yönlendirme URI'leri bölümünde öğesini seçinhttps://login.microsoftonline.com/common/oauth2/nativeclient.
11. Yapılandır'yı seçin.

MSAL'yi başlatmak için kodu ekleme

Bu adımda, belirteçlerin işlenmesi gibi MSAL ile etkileşimi işlemek için bir sınıf oluşturursunuz.

1. App.xaml.cs dosyasını açın ve ardından MSAL başvuruyu sınıfına ekleyin:

   using Microsoft.Identity.Client;
   

2. Uygulama sınıfını aşağıdakilere güncelleştirin:

   public partial class App : Application
   {
       static App()
       {
           _clientApp = PublicClientApplicationBuilder.Create(ClientId)
               .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
               .WithDefaultRedirectUri()
               .Build();
       }
   
       // Below are the clientId (Application Id) of your app registration and the tenant information.
       // You have to replace:
       // - the content of ClientID with the Application Id for your app registration
       // - the content of Tenant by the information about the accounts allowed to sign-in in your application:
       //   - For Work or School account in your org, use your tenant ID, or domain
       //   - for any Work or School accounts, use `organizations`
       //   - for any Work or School accounts, or Microsoft personal account, use `common`
       //   - for Microsoft Personal account, use consumers
       private static string ClientId = "Enter_the_Application_Id_here";
   
       private static string Tenant = "common";
   
       private static IPublicClientApplication _clientApp ;
   
       public static IPublicClientApplication PublicClientApp { get { return _clientApp; } }
   }
   

Uygulama kullanıcı arabirimini oluşturma

Bu bölümde, bir uygulamanın Microsoft Graph gibi korumalı bir arka uç sunucusunu nasıl sorgulayabileceğiniz gösterilmektedir.

Proje şablonunuzun bir parçası olarak bir MainWindow.xaml dosyası otomatik olarak oluşturulur. Bu dosyayı açın ve uygulamanızın <Kılavuz> düğümünü aşağıdaki kodla değiştirin:

<Grid>
    <StackPanel Background="Azure">
        <StackPanel Orientation="Horizontal" HorizontalAlignment="Right">
            <Button x:Name="CallGraphButton" Content="Call Microsoft Graph API" HorizontalAlignment="Right" Padding="5" Click="CallGraphButton_Click" Margin="5" FontFamily="Segoe Ui"/>
            <Button x:Name="SignOutButton" Content="Sign-Out" HorizontalAlignment="Right" Padding="5" Click="SignOutButton_Click" Margin="5" Visibility="Collapsed" FontFamily="Segoe Ui"/>
        </StackPanel>
        <Label Content="API Call Results" Margin="0,0,0,-5" FontFamily="Segoe Ui" />
        <TextBox x:Name="ResultText" TextWrapping="Wrap" MinHeight="120" Margin="5" FontFamily="Segoe Ui"/>
        <Label Content="Token Info" Margin="0,0,0,-5" FontFamily="Segoe Ui" />
        <TextBox x:Name="TokenInfoText" TextWrapping="Wrap" MinHeight="70" Margin="5" FontFamily="Segoe Ui"/>
    </StackPanel>
</Grid>

Microsoft Graph API'sine belirteç almak için MSAL kullanma

Bu bölümde, Microsoft Graph API'sine yönelik bir belirteç almak için MSAL kullanacaksınız.

1. MainWindow.xaml.cs dosyasında MSAL başvuruyu sınıfına ekleyin:

   using Microsoft.Identity.Client;
   

2. MainWindow Sınıf kodunu aşağıdaki kodla değiştirin:

   public partial class MainWindow : Window
   {
       //Set the API Endpoint to Graph 'me' endpoint
       string graphAPIEndpoint = "https://graph.microsoft.com/v1.0/me";
   
       //Set the scope for API call to user.read
       string[] scopes = new string[] { "user.read" };
   
   
       public MainWindow()
       {
           InitializeComponent();
       }
   
     /// <summary>
       /// Call AcquireToken - to acquire a token requiring user to sign-in
       /// </summary>
       private async void CallGraphButton_Click(object sender, RoutedEventArgs e)
       {
           AuthenticationResult authResult = null;
           var app = App.PublicClientApp;
           ResultText.Text = string.Empty;
           TokenInfoText.Text = string.Empty;
   
           var accounts = await app.GetAccountsAsync();
           var firstAccount = accounts.FirstOrDefault();
   
           try
           {
               authResult = await app.AcquireTokenSilent(scopes, firstAccount)
                   .ExecuteAsync();
           }
           catch (MsalUiRequiredException ex)
           {
               // A MsalUiRequiredException happened on AcquireTokenSilent.
               // This indicates you need to call AcquireTokenInteractive to acquire a token
               System.Diagnostics.Debug.WriteLine($"MsalUiRequiredException: {ex.Message}");
   
               try
               {
                   authResult = await app.AcquireTokenInteractive(scopes)
                       .WithAccount(accounts.FirstOrDefault())
                       .WithPrompt(Prompt.SelectAccount)
                       .ExecuteAsync();
               }
               catch (MsalException msalex)
               {
                   ResultText.Text = $"Error Acquiring Token:{System.Environment.NewLine}{msalex}";
               }
           }
           catch (Exception ex)
           {
               ResultText.Text = $"Error Acquiring Token Silently:{System.Environment.NewLine}{ex}";
               return;
           }
   
           if (authResult != null)
           {
               ResultText.Text = await GetHttpContentWithToken(graphAPIEndpoint, authResult.AccessToken);
               DisplayBasicTokenInfo(authResult);
               this.SignOutButton.Visibility = Visibility.Visible;
           }
       }
       }
   

Daha Fazla Bilgi

Etkileşimli olarak kullanıcı belirteci alma

yönteminin çağrılması AcquireTokenInteractive , kullanıcıların oturum açmasını isteyen bir pencereye neden olur. Uygulamalar genellikle kullanıcıların korumalı bir kaynağa ilk kez erişmeleri gerektiğinde etkileşimli olarak oturum açmalarını gerektirir. Ayrıca, bir belirteci almak için sessiz bir işlem başarısız olduğunda (örneğin, kullanıcının parolasının süresi dolduğunda) oturum açmaları gerekebilir.

Kullanıcı belirtecini sessizce alma

yöntemi, AcquireTokenSilent herhangi bir kullanıcı etkileşimi olmadan belirteç alımlarını ve yenilemelerini işler. sonra ilk kez yürütüldükten sonra AcquireTokenInteractive , AcquireTokenSilent istek veya yenileme belirteçleri çağrıları sessizce yapıldığından, sonraki çağrılar için korumalı kaynaklara erişen belirteçleri almak için kullanılan olağan yöntemdir.

Sonunda yöntemi AcquireTokenSilent başarısız olabilir. Hatanın nedenleri, kullanıcının başka bir cihazda oturumunu kapatması veya parolasını değiştirmesi olabilir. MSAL, sorunun etkileşimli bir eylem gerektirerek çözülebileceğini algıladığında bir MsalUiRequiredException özel durum tetikler. Uygulamanız bu özel durumu iki şekilde işleyebilir:

• Hemen karşı çağrı AcquireTokenInteractive yapabilir. Bu çağrı, kullanıcıdan oturum açmasını istemeye neden olur. Bu düzen, kullanıcı için kullanılabilir çevrimdışı içerik bulunmayan çevrimiçi uygulamalarda kullanılır. Bu kurulum tarafından oluşturulan örnek, örneği ilk kez yürütürken eylemde görülebilen bu deseni izler.

• Hiçbir kullanıcı uygulamayı kullanmadığından, PublicClientApp.Users.FirstOrDefault() null bir değer içerir ve bir MsalUiRequiredException özel durum oluşturulur.

• Örnekteki kod daha sonra çağrısı AcquireTokenInteractiveyaparak özel durumu işler ve bu da kullanıcıdan oturum açmasını istemesine neden olur.

• Bunun yerine, kullanıcılara etkileşimli oturum açmanın gerekli olduğuna dair görsel bir gösterge sunabilir, böylece oturum açmak için doğru zamanı seçebilirler. Veya uygulama daha sonra yeniden deneyebilir AcquireTokenSilent . Bu düzen, kullanıcılar kesinti olmadan diğer uygulama işlevlerini kullanabildiğinde sıklıkla kullanılır. Örneğin, uygulamada çevrimdışı içerik kullanılabilir olduğunda. Bu durumda, kullanıcılar korumalı kaynağa erişmek veya eski bilgileri yenilemek için ne zaman oturum açmak istediklerine karar verebilir. Alternatif olarak uygulama, ağ geçici olarak kullanılamadıktan sonra geri yüklendiğinde yeniden denemeye AcquireTokenSilent karar verebilir.

Az önce aldığınız belirteci kullanarak Microsoft Graph API'sini çağırma

Aşağıdaki yeni yöntemi kendi yönteminize MainWindow.xaml.csekleyin. yöntemi, Yetkilendirme üst bilgisi kullanılarak Graph API'sine yönelik istekte bulunmak GET için kullanılır:

/// <summary>
/// Perform an HTTP GET request to a URL using an HTTP Authorization header
/// </summary>
/// <param name="url">The URL</param>
/// <param name="token">The token</param>
/// <returns>String containing the results of the GET operation</returns>
public async Task<string> GetHttpContentWithToken(string url, string token)
{
    var httpClient = new System.Net.Http.HttpClient();
    System.Net.Http.HttpResponseMessage response;
    try
    {
        var request = new System.Net.Http.HttpRequestMessage(System.Net.Http.HttpMethod.Get, url);
        //Add the token in Authorization header
        request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
        response = await httpClient.SendAsync(request);
        var content = await response.Content.ReadAsStringAsync();
        return content;
    }
    catch (Exception ex)
    {
        return ex.ToString();
    }
}

Korumalı API'ye karşı REST çağrısı yapma hakkında daha fazla bilgi

Bu örnek uygulamada, belirteç gerektiren korumalı bir kaynağa http GET isteğinde bulunmak ve ardından içeriği çağırana döndürmek için yöntemini kullanırsınızGetHttpContentWithToken. Bu yöntem, alınan belirteci HTTP Yetkilendirme üst bilgisine ekler. Bu örnek için kaynak, kullanıcının profil bilgilerini görüntüleyen Microsoft Graph API me uç noktasıdır.

Kullanıcının oturumunu kapatmak için yöntem ekleme

Bir kullanıcının oturumunu kapatmak için dosyanıza MainWindow.xaml.cs aşağıdaki yöntemi ekleyin:

/// <summary>
/// Sign out the current user
/// </summary>
private async void SignOutButton_Click(object sender, RoutedEventArgs e)
{
    var accounts = await App.PublicClientApp.GetAccountsAsync();

    if (accounts.Any())
    {
        try
        {
            await App.PublicClientApp.RemoveAsync(accounts.FirstOrDefault());
            this.ResultText.Text = "User has signed-out";
            this.CallGraphButton.Visibility = Visibility.Visible;
            this.SignOutButton.Visibility = Visibility.Collapsed;
        }
        catch (MsalException ex)
        {
            ResultText.Text = $"Error signing-out user: {ex.Message}";
        }
    }
}

Kullanıcı oturumu kapatma hakkında daha fazla bilgi

SignOutButton_Click yöntemi, kullanıcıları MSAL kullanıcı önbelleğinden kaldırır. Bu da MSAL'ye geçerli kullanıcıyı unutmasını ve gelecekteki bir belirteç alma isteğinin yalnızca etkileşimli olması durumunda başarılı olmasını sağlar.

Bu örnekteki uygulama tek kullanıcıları desteklese de MSAL, birden çok hesabın aynı anda oturum açabildiği senaryoları destekler. Örneğin, kullanıcının birden çok hesabı olan bir e-posta uygulamasıdır.

Temel belirteç bilgilerini görüntüleme

Belirteçle ilgili temel bilgileri görüntülemek için MainWindow.xaml.cs dosyanıza aşağıdaki yöntemi ekleyin:

/// <summary>
/// Display basic information contained in the token
/// </summary>
private void DisplayBasicTokenInfo(AuthenticationResult authResult)
{
    TokenInfoText.Text = "";
    if (authResult != null)
    {
        TokenInfoText.Text += $"Username: {authResult.Account.Username}" + Environment.NewLine;
        TokenInfoText.Text += $"Token Expires: {authResult.ExpiresOn.ToLocalTime()}" + Environment.NewLine;
    }
}

Daha Fazla Bilgi

Kullanıcı oturum açtığında MSAL, Microsoft Graph API'sini çağırmak için kullanılan erişim belirtecine ek olarak bir kimlik belirteci de alır. Bu belirteç, kullanıcılara ait bilgilerin küçük bir alt kümesini içerir. yöntemi, DisplayBasicTokenInfo belirteçte yer alan temel bilgileri görüntüler. Örneğin, kullanıcının görünen adını ve kimliğinin yanı sıra belirteç süre sonu tarihini ve erişim belirtecinin kendisini temsil eden dizeyi görüntüler. Microsoft Graph API'sini Ara düğmesini birden çok kez seçebilir ve sonraki istekler için aynı belirtecin yeniden kullanıldığını görebilirsiniz. Ayrıca, MSAL belirteci yenileme zamanına karar verdikten sonra sona erme tarihinin uzatıldığını da görebilirsiniz.

Kodunuza test etme

Projenizi çalıştırmak için Visual Studio'da F5'i seçin. Uygulamanız MainWindow burada gösterildiği gibi görüntülenir:

Uygulamayı ilk kez çalıştırdığınızda ve Microsoft Graph API'sini Ara düğmesini seçtiğinizde oturum açmanız istenir. Test etmek için bir Microsoft Entra hesabı (iş veya okul hesabı) veya bir Microsoft hesabı (live.com, outlook.com) kullanın.

Uygulama erişimi için onay verme

Uygulamanızda ilk kez oturum açtığınızda, burada gösterildiği gibi uygulamanın profilinize erişmesine ve oturum açmanıza izin vermek için onay vermeniz de istenir:

Uygulama sonuçlarını görüntüleme

Oturum açtığınızda, Microsoft Graph API çağrısı tarafından döndürülen kullanıcı profili bilgilerini görmeniz gerekir. Sonuçlar API Çağrı Sonuçları kutusunda görüntülenir. çağrısıyla AcquireTokenInteractive alınan veya AcquireTokenSilent Belirteç Bilgileri kutusunda görünür olması gereken belirteçle ilgili temel bilgiler. Sonuçlar aşağıdaki özellikleri içerir:

Özellik	Biçimlendir	Açıklama
Kullanıcı adı	user@domain.com	Kullanıcıyı tanımlamak için kullanılan kullanıcı adı.
Belirtecin Süresi Doluyor	DateTime	Belirtecin süresinin dolma zamanı. MSAL, belirteci gerektiği gibi yenileyerek son kullanma tarihini uzatır.

Kapsamlar ve temsilci izinleri hakkında daha fazla bilgi

Microsoft Graph API'sinde kullanıcının profilini okumak için user.read kapsamı gerekir. Bu kapsam, Uygulama Kayıt Portalı'nda kayıtlı olan her uygulamaya varsayılan olarak otomatik olarak eklenir. Diğer Microsoft Graph API'lerinin yanı sıra arka uç sunucunuz için özel API'ler ek kapsamlar gerektirebilir. Microsoft Graph API'sinde , kullanıcının takvimlerini listelemek için Calendars.Read kapsamı gerekir.

Kullanıcının takvimlerine bir uygulama bağlamında erişmek için, uygulama kayıt bilgilerine Calendars.Read temsilci iznini ekleyin. Ardından Calendars.Read kapsamını acquireTokenSilent aramaya ekleyin.

Not

Kapsam sayısını artırdığınızda kullanıcıdan ek onaylar istenebilir.

Yardım ve destek 

Yardıma ihtiyacınız varsa, bir sorunu bildirmek veya destek seçenekleriniz hakkında bilgi edinmek istiyorsanız bkz . Geliştiriciler için yardım ve destek.

Sonraki adımlar

Çok parçalı senaryo serimizde korumalı web API'lerini çağıran masaüstü uygulamaları oluşturma hakkında daha fazla bilgi edinin:

Senaryo: Web API'lerini çağıran masaüstü uygulaması