Szybki start: inicjowanie aplikacji klienckiej (C#)

2025-04-11

Ten przewodnik szybkiego startu pokaże, jak zaimplementować wzorzec inicjowania klienta używany przez pakiet MIP SDK w otoczce .NET podczas działania.

Uwaga

Kroki opisane w tym przewodniku szybkiego startu są wymagane dla każdej aplikacji klienckiej korzystającej z SDK plików, polityki lub ochrony wrappera MIP .NET. Mimo że w tym przewodniku Szybki start pokazano użycie zestawów SDK plików, ten sam wzorzec ma zastosowanie do klientów korzystających z zestawów SDK zasad i ochrony. Przyszłe przewodniki Szybkiego Startu powinny być wykonywane szeregowo, ponieważ każdy z nich opiera się na poprzednim, a ten jest pierwszym. 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:

Wykonaj kroki opisane w artykule Konfiguracja i konfiguracja zestawu SDK usługi Microsoft Information Protection (MIP). Ten szybki przewodnik startowy "Inicjalizacja aplikacji klienckiej" opiera się na odpowiednim ustawieniu i konfiguracji SDK.
Opcjonalnie:
- Przejrzyj obiekty profilu i silnika. Obiekty profilu i silnika są uniwersalnymi pojęciami wymaganymi przez klientów korzystających z zestawów SDK plików/zasad/ochrony MIP.
- Zapoznaj się z pojęciami dotyczącymi uwierzytelniania , aby dowiedzieć się, jak uwierzytelnianie i zgoda są implementowane przez zestaw SDK i aplikację kliencą.

Tworzenie rozwiązania i projektu programu Visual Studio

Najpierw tworzymy i konfigurujemy początkowe rozwiązanie i projekt w Visual Studio, na którym będą opierać się inne projekty szybkiego startu.

Otwórz program Visual Studio 2019, 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 okienku wybierz pozycję Aplikacja konsolowa (.NET Framework)
- W dolnym okienku zaktualizuj odpowiednio nazwę projektu,lokalizację i nazwę rozwiązania zawierającego.
- Po zakończeniu kliknij przycisk OK w prawym dolnym rogu.
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 pozycję 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.
Powtórz powyższe kroki, aby dodać pakiet MIP File SDK, ale zamiast tego dodaj "Microsoft.Identity.Client" do aplikacji.

Implementowanie delegata uwierzytelniania

Zestaw MIP SDK implementuje uwierzytelnianie przy użyciu rozszerzalności klas, co zapewnia mechanizm udostępniania pracy uwierzytelniania z aplikacją kliencką. Klient musi uzyskać odpowiedni token dostępu OAuth2 i przekazać go do MIP SDK podczas działania.

Teraz utwórz implementację delegata uwierzytelniania, rozszerzając interfejs SDK Microsoft.InformationProtection.IAuthDelegate i nadpisując/implementując wirtualną funkcję IAuthDelegate.AcquireToken(). Delegat uwierzytelniania jest tworzony i używany później przez obiekty FileProfile i FileEngine.

Kliknij prawym przyciskiem myszy nazwę projektu w programie Visual Studio, wybierz pozycję Dodaj , a następnie pozycję Klasa.
Wprowadź "AuthDelegateImplementation" w polu Nazwa. Kliknij przycisk Dodaj.
Dodaj deklaracje using dla biblioteki Microsoft Authentication Library (MSAL) oraz biblioteki MIP:
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
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. Element _appInfo.ApplicationId zostanie użyty w AuthDelegateImplementation klasie , aby podać identyfikator klienta do biblioteki uwierzytelniania. ApplicationName i ApplicationVersion zostaną uwidocznione w raportach Analytics usługi Azure Information Protection.

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. Te zmienne ciągu zostaną przekazane do biblioteki uwierzytelniania przez interfejs API i nie powinny być manipulowane. Wprowadź GUID dzierżawy z portalu Azure. Edytowanie ciągów znaków innych niż identyfikator GUID dzierżawy może spowodować niepowodzenie 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 implementując GetUserConsent(). Delegat zgody jest tworzony i używany później przez obiekty profil pliku i silnik plików. Pełnomocnik zgody otrzymuje adres usługi, na korzystanie z której użytkownik musi wyrazić zgodę, 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. Dla tego szybkiego startu użyj twardo zaszytego kodu Consent.Accept.

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.
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;
     }
}
```
Opcjonalnie spróbuj skompilować rozwiązanie, aby upewnić się, że kompiluje się bez błędów.

Inicjalizacja zarządzanego opakowania MIP SDK

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.
Usuń wygenerowaną implementację elementu main().
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.
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);
            
        }
    }
}

Utworzenie profilu pliku i silnika

Jak wspomniano, obiekty profilu i silnika są wymagane dla klientów zestawu SDK przy użyciu interfejsów API MIP. Ukończ część kodowania tego przewodnika Quickstart, dodając kod do załadowania natywnych bibliotek DLL, a następnie zainicjuj 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;
       }
  }
}

Zastąp wartości symboli zastępczych w kodzie źródłowym, który wkleiłeś, używając następujących wartości:

Element zastępczy	Wartość	Przykład
<identyfikator aplikacji>	Identyfikator aplikacji Entra firmy Microsoft przypisany do aplikacji zarejestrowanej w sekcji "Konfiguracja i konfiguracja zestawu MIP SDK" (2 wystąpienia).	0edbblll-8773-44de-b87c-b8c6276d41eb
<przyjazna nazwa>	Przyjazna nazwa aplikacji zdefiniowana przez użytkownika.	Inicjalizacja aplikacji
<Identyfikator GUID dzierżawy>	Tenant-ID dla instancji Microsoft Entra	TenantID

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

Następne kroki

Teraz, gdy kod inicjowania został ukończony, możesz przystąpić do następnego przewodnika szybkiego startu, w którym zaczniesz korzystać z zestawów SDK MIP dla plików.

Lista etykiet poufności

Udostępnij za pośrednictwem