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

Şunlar için geçerlidir: Aşağıdaki içeriğin iş gücü kiracıları için geçerli olduğunu gösteren beyaz onay işareti simgesine sahip yeşil daire. İş gücü kiracıları Aşağıdaki içeriğin dış kiracılar için geçerli olduğunu gösteren beyaz onay işareti simgesine sahip yeşil daire. Dış kiracılar (daha fazla bilgi edinin)

Bu öğreticide, kullanıcıların oturum açmasını sağlayan ve Microsoft Graph API'yi çağırmak için bir erişim belirteci alan yerel bir 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 şunları yapacaksınız:

  • 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

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

Bu öğretici tarafından oluşturulan örnek uygulamanın nasıl çalıştığını gösteren ekran görüntüsü.

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şturduğunuz uygulama, Microsoft Graph API'sini çağıracak bir düğme, sonuçları görüntülemek için bir alan ve bir oturum kapatma düğmesi görüntüler.

Not

Bunun yerine bu örneğin Visual Studio projesini indirmeyi mi tercih ediyorsunuz? Bir proje indirin ve yürütmeden önce kod örneğini yapılandırmak için uygulamanızı kaydedin.

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

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 MSAL'yi sınıfa referans olarak 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 sınıfa MSAL için başvuruyu 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 al

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

Sonunda AcquireTokenSilent yöntemi 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 AcquireTokenInteractive ile ilgili bir çağrı 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, ilk kez çalıştırdığınızda pratikte görülebilecek olan 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, ağ geçici olarak kullanılamadıktan sonra geri yüklendiğinde uygulama AcquireTokenSilent'yı yeniden denemeye karar verebilir.

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

Aşağıdaki yeni yöntemi MainWindow.xaml.cs öğenize ekleyin. Bu yöntem, Yetkilendirme üst bilgisi kullanılarak Graph API'sine yönelik bir GET isteği yapmak 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 GetHttpContentWithToken isteğini yapmak ve ardından içeriği çağırana geri döndürmek için GET yöntemini kullanırsınız. 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ı çıkışı hakkında daha fazla bilgi

SignOutButton_Click yöntemi, kullanıcıları MSAL kullanıcı önbelleğinden kaldırır. Bu da MSAL'ye mevcut kullanıcıyı unutmasını ve gelecekte bir belirteç alma isteğinin ancak etkileşimli yapıldığında 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. MSAL belirtecin yenilenmesi gerektiğine karar verdiğinde, sona erme tarihinin uzatıldığını da görebilirsiniz.

Kodunuzu test edin

Projenizi çalıştırmak için Visual Studio'da F5'i seçin. Uygulamanız MainWindow 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.

Uygulamada oturum açın.

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 erişimi için onayınızı sağlayın.

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. AcquireTokenInteractive veya AcquireTokenSilent çağrısıyla alınan belirteçle ilgili temel bilgiler Belirteç Bilgileri kutusunda görünür olmalıdır. Sonuçlar aşağıdaki özellikleri içerir:

Mülk Biçim Açıklama
Kullanıcı adı user@domain.com Kullanıcıyı tanımlamak için kullanılan kullanıcı adı.
Belirtecin Süresi Doluyor TarihSaat Jetonun 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. Microsoft Graph için diğer API'ler ve arka uç sunucunuz için özel API'ler daha fazla kapsam 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 çağrısına 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ım

Ç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ı

  • Last updated on