Szybki start: inicjowanie aplikacji klienckiej (C#)

W tym przewodniku Szybki start pokazano, jak zaimplementować wzorzec inicjowania klienta, którego zestaw MIP SDK .NET używa w czasie wykonywania.

Uwaga

Każda aplikacja kliencka korzystająca z pakietów SDK File, Policy lub Protection otoki .NET rozwiązania MIP wymaga wykonania kroków opisanych w tym przewodniku Szybki start. Chociaż w tym przewodniku Szybki start pokazano użycie zestawów File SDK, ten sam schemat ma zastosowanie do klientów korzystających z zestawów Policy SDK i Protection SDK. Ukończ następne przewodniki Szybki start po kolei, ponieważ każdy kolejny bazuje na poprzednim, a ten jest pierwszym z nich. Ten kod ma na celu pokazanie, jak rozpocząć pracę z zestawem MIP SDK i nie jest przeznaczony do użytku produkcyjnego.

Wymagania wstępne

Jeśli jeszcze tego nie zrobiono, upewnij się, że:

Tworzenie rozwiązania i projektu programu Visual Studio

Najpierw utwórz i skonfiguruj początkowe rozwiązanie programu Visual Studio oraz projekt, na których opierają się pozostałe przewodniki Szybki start.

  1. Otwórz program Visual Studio 2022 lub nowszy, wybierz menu Plik , Nowy, Projekt. W oknie dialogowym Nowy projekt :

    • W okienku po lewej stronie w obszarze Zainstalowane, Visual C# wybierz pozycję Pulpit systemu Windows.

    • W środkowym panelu wybierz pozycję Aplikacja konsolowa (dla platformy .NET 8 lub nowszej).

    • W dolnym okienku zaktualizuj odpowiednio nazwę projektu,lokalizację i nazwę rozwiązania zawierającego.

    • Po zakończeniu kliknij przycisk OK w prawym dolnym rogu.

      Tworzenie rozwiązania w programie Visual Studio.

  2. Dodaj pakiet NuGet dla zestawu MIP File SDK do projektu:

    • W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy węzeł projektu (bezpośrednio w węźle u góry/rozwiązania), a następnie wybierz polecenie Zarządzaj pakietami NuGet...:
    • Po otwarciu karty Menedżera pakietów NuGet w grupie kart edytora:
      • Wybierz przycisk Przeglądaj.
      • Wpisz "Microsoft.InformationProtection" w polu wyszukiwania.
      • Wybierz pakiet "Microsoft.InformationProtection.File".
      • Kliknij przycisk "Zainstaluj", a następnie kliknij "OK", kiedy pojawi się okno dialogowe Podgląd zmian.

  3. Powtórz powyższe kroki, aby dodać pakiet MIP File SDK, ale zamiast tego dodaj "Microsoft.Identity.Client" do aplikacji.

Implementowanie delegata uwierzytelniania

Pakiet SDK MIP implementuje uwierzytelnianie za pomocą mechanizmu rozszerzania klas, który umożliwia współdzielenie obsługi uwierzytelniania z aplikacją kliencką. Klient musi uzyskać odpowiedni token dostępu OAuth2 i udostępnić go zestawowi MIP SDK w czasie wykonywania.

Teraz utwórz implementację dla delegata uwierzytelniania, rozszerzając interfejs zestawu SDK Microsoft.InformationProtection.IAuthDelegate i przesłaniając lub implementując funkcję wirtualną IAuthDelegate.AcquireToken() . Obiekty FileProfile i FileEngine tworzą, a następnie używają delegata uwierzytelniania.

  1. Kliknij prawym przyciskiem myszy nazwę projektu w programie Visual Studio, wybierz pozycję Dodaj , a następnie pozycję Klasa.

  2. Wprowadź "AuthDelegateImplementation" w polu Nazwa. Kliknij przycisk Dodaj.

  3. Dodaj deklaracje using dla biblioteki Microsoft Authentication Library (MSAL) oraz biblioteki MIP:

    using Microsoft.InformationProtection;
using Microsoft.Identity.Client;

  4. Ustaw AuthDelegateImplementation do dziedziczenia Microsoft.InformationProtection.IAuthDelegate oraz zaimplementuj prywatną zmienną typu Microsoft.InformationProtection.ApplicationInfo i konstruktor, który akceptuje ten sam typ.

    public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}

    Obiekt ApplicationInfo zawiera trzy właściwości. Klasa AuthDelegateImplementation używa _appInfo.ApplicationId, aby przekazać identyfikator klienta bibliotece uwierzytelniania. ApplicationNamei ApplicationVersion są wyświetlane w raportach inspekcji Microsoft Purview.

  5. Dodaj metodę public string AcquireToken() . Ta metoda powinna akceptować Microsoft.InformationProtection.Identity i trzy ciągi: adres URL organu, identyfikator URI zasobu oraz oświadczenia, jeśli jest to wymagane. Interfejs API przekazuje te zmienne tekstowe do biblioteki uwierzytelniania i nie należy ich modyfikować. Wprowadź identyfikator GUID tenantu z portalu Azure dla swojego tenantu. Edytowanie ciągów innych niż identyfikator GUID dzierżawy może spowodować niepowodzenie podczas uwierzytelniania.

    public string AcquireToken(Identity identity, string authority, string resource, string claims)
{
   var authorityUri = new Uri(authority);
   authority = String.Format("https://{0}/{1}", authorityUri.Host, "<Tenant-GUID>");

   _app = PublicClientApplicationBuilder.Create(_appInfo.ApplicationId).WithAuthority(authority).WithDefaultRedirectUri().Build();
   var accounts = (_app.GetAccountsAsync()).GetAwaiter().GetResult();

   // Append .default to the resource passed in to AcquireToken().
   string[] scopes = new string[] { resource[resource.Length - 1].Equals('/') ? $"{resource}.default" : $"{resource}/.default" };
   var result = _app.AcquireTokenInteractive(scopes).WithAccount(accounts.FirstOrDefault()).WithPrompt(Prompt.SelectAccount)
              .ExecuteAsync().ConfigureAwait(false).GetAwaiter().GetResult();

   return result.AccessToken;
}

Teraz utwórz implementację delegata zgody, rozszerzając interfejs SDK Microsoft.InformationProtection.IConsentDelegate i zastępując lub implementując GetUserConsent(). Obiekty profilu pliku i mechanizmu plików tworzą, a następnie używają delegata zgody. Delegat zgody otrzymuje adres usługi, którą użytkownik musi wyrazić zgodę na użycie w parametrze url . Delegat powinien ogólnie zapewnić przepływ, który umożliwia użytkownikowi akceptowanie lub odrzucanie zgody na dostęp do usługi. Na potrzeby tego przewodnika Szybki start za pomocą twardego kodu Consent.Accept.

  1. Korzystając z tej samej funkcji "Dodaj klasę" programu Visual Studio, której użyliśmy wcześniej, dodaj kolejną klasę do projektu. Tym razem wprowadź "ConsentDelegateImplementation" w polu Nazwa klasy.

  2. Teraz zaktualizuj ConsentDelegateImpl.cs , aby zaimplementować nową klasę delegata zgody. Dodaj instrukcję using dla Microsoft.InformationProtection i ustaw klasę, aby dziedziczyła po IConsentDelegate.

    class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}

  3. Opcjonalnie spróbuj skompilować rozwiązanie, aby upewnić się, że kompiluje się bez błędów.

Inicjalizacja zarządzanego opakowania MIP SDK

  1. W Eksploratorze rozwiązań otwórz plik .cs w projekcie zawierający implementację Main() metody . Domyślnie ma taką samą nazwę jak projekt zawierający go, który został określony podczas tworzenia projektu.

  2. Usuń wygenerowaną implementację elementu main().

  3. Zarządzana otoka zawiera klasę statyczną używaną Microsoft.InformationProtection.MIP do inicjowania, tworzenia MipContext, ładowania profilów i wydawania zasobów. Aby zainicjować opakowanie dla operacji plików w SDK, wywołaj MIP.Initialize(), przekazując MipComponent.File do załadowania bibliotek niezbędnych do operacji na plikach.

  4. W Main()Program.cs dodaj następujący kod, zastępując <application-id> identyfikatorem utworzonej wcześniej rejestracji aplikacji Microsoft Entra.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.Exceptions;
using Microsoft.InformationProtection.File;
using Microsoft.InformationProtection.Protection;

namespace mip_sdk_dotnet_quickstart
{
    class Program
    {
        private const string clientId = "<application-id>";
        private const string appName = "<friendly-name>";

        static void Main(string[] args)
        {
            //Initialize Wrapper for File SDK operations
            MIP.Initialize(MipComponent.File);
            
        }
    }
}

Tworzenie profilu pliku i silnika

Jak wspomniano, klienci zestawu SDK korzystający z interfejsów API MIP wymagają obiektów profilu i silnika. Ukończ część tego przewodnika Szybki start dotyczącą kodu, dodając kod do załadowania natywnych bibliotek DLL, a następnie tworząc obiekty profilu i silnika.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.File;

namespace mip_sdk_dotnet_quickstart
{
  class Program
  {
       private const string clientId = "<application-id>";
       private const string appName = "<friendly-name>";

       static void Main(string[] args)
       {
            // Initialize Wrapper for File SDK operations.
            MIP.Initialize(MipComponent.File);

            // Create ApplicationInfo, setting the clientID from Microsoft Entra App Registration as the ApplicationId.
            ApplicationInfo appInfo = new ApplicationInfo()
            {
                 ApplicationId = clientId,
                 ApplicationName = appName,
                 ApplicationVersion = "1.0.0"
            };

            // Instantiate the AuthDelegateImpl object, passing in AppInfo.
            AuthDelegateImplementation authDelegate = new AuthDelegateImplementation(appInfo);

            // Create MipConfiguration Object
            MipConfiguration mipConfiguration = new MipConfiguration(appInfo, "mip_data", LogLevel.Trace, false);

            // Create MipContext using Configuration
            MipContext mipContext = MIP.CreateMipContext(mipConfiguration);

            // Initialize and instantiate the File Profile.
            // Create the FileProfileSettings object.
            // Initialize file profile settings to create/use local state.
            var profileSettings = new FileProfileSettings(mipContext,
                                     CacheStorageType.OnDiskEncrypted,
                                     new ConsentDelegateImplementation());

            // Load the Profile async and wait for the result.
            var fileProfile = Task.Run(async () => await MIP.LoadFileProfileAsync(profileSettings)).Result;

            // Create a FileEngineSettings object, then use that to add an engine to the profile.
            // This pattern sets the engine ID to user1@tenant.com, then sets the identity used to create the engine.
            var engineSettings = new FileEngineSettings("user1@tenant.com", authDelegate, "", "en-US");
            engineSettings.Identity = new Identity("user1@tenant.com");

            var fileEngine = Task.Run(async () => await fileProfile.AddEngineAsync(engineSettings)).Result;

            // Application Shutdown
            // handler = null; // This will be used in later quick starts.
            fileEngine = null;
            fileProfile = null;
            mipContext.ShutDown();
            mipContext = null;
       }
  }
}

  1. Zastąp wartości zastępcze w kodzie źródłowym, który został wklejony, używając następujących wartości:

    Element zastępczy Wartość Przykład
    <identyfikator aplikacji> Identyfikator aplikacji Microsoft Entra przypisany do aplikacji zarejestrowanej w sekcji "Konfiguracja i konfiguracja zestawu MIP SDK" (2 wystąpienia). 00001111-aaaa-2222-bbbb-3333cccc44444
    <przyjazna nazwa> Przyjazna nazwa aplikacji zdefiniowana przez użytkownika. Inicjalizacja aplikacji
    <Identyfikator GUID dzierżawy> Identyfikator tenanta dla środowiska Microsoft Entra. TenantID

  2. Teraz wykonaj ostateczną kompilację aplikacji i rozwiąż wszelkie błędy. Kod powinien zostać pomyślnie skompilowany.

Następne kroki

Teraz, gdy kod inicjalizacyjny jest już gotowy, możesz przejść do kolejnego przewodnika Szybki start, w którym zaczniesz poznawać zestawy SDK MIP File.

Lista etykiet poufności

  • Ostatnia aktualizacja o