Rychlý start: Inicializace klientské aplikace (C#)

Článek
10/18/2023

V tomto rychlém startu se dozvíte, jak implementovat model inicializace klienta používaný obálkou .NET SADY MIP SDK za běhu.

Poznámka:

Kroky popsané v tomto rychlém startu jsou vyžadovány pro všechny klientské aplikace, které používají obálky MIP .NET File, Policy nebo Protection SDK. I když tento rychlý start ukazuje použití sad FILE SDK, tento vzor platí pro klienty používající sady SDK zásad a ochrany. Budoucí rychlé starty by se měly provádět sériově, protože každý z nich vychází z předchozího, přičemž první z nich je. Tento kód je určený k předvedení toho, jak začít se sadou MIP SDK a není určený pro produkční použití.

Předpoklady

Pokud jste to ještě neudělali, nezapomeňte:

Dokončete kroky v nastavení a konfiguraci sady Microsoft Information Protection (MIP) SDK. Tento rychlý start "Inicializace klientské aplikace" spoléhá na správné nastavení a konfiguraci sady SDK.
Volitelně:
- Zkontrolujte objekty profilu a modulu. Objekty profilu a modulu jsou univerzální koncepty vyžadované klienty, kteří používají sady SDK MIP File/Policy/Protection.
- Projděte si koncepty ověřování a zjistěte, jak jsou ověřování a souhlas implementovány sadou SDK a klientskou aplikací.

Vytvoření řešení a projektu sady Visual Studio

Nejprve vytvoříme a nakonfigurujeme počáteční řešení a projekt sady Visual Studio, na kterém se sestaví další rychlé starty.

Otevřete Visual Studio 2019 a vyberte nabídku Soubor , Nový, Projekt. V dialogovém okně Nový projekt :
- V levém podokně v části Nainstalováno, Visual C# vyberte Windows Desktop.
- V prostředním podokně vyberte Konzolová aplikace (.NET Framework)
- V dolním podokně odpovídajícím způsobem aktualizujte název projektu, umístění a obsahující název řešení.
- Po dokončení klikněte na tlačítko OK v pravém dolním rohu.
Přidejte balíček NuGet pro sadu MIP File SDK do projektu:
- V Průzkumník řešení klikněte pravým tlačítkem na uzel projektu (přímo pod horním uzlem nebo uzlem řešení) a vyberte Spravovat balíčky NuGet...:
- Když se v oblasti Karet skupiny editoru otevře karta Správce balíčků NuGet:
  - Vyberte Procházet.
  - Do vyhledávacího pole zadejte "Microsoft.InformationProtection".
  - Vyberte balíček Microsoft.InformationProtection.File.
  - Po zobrazení potvrzovací dialogového okna Náhled změn klikněte na Instalovat a potom klikněte na OK.
Opakujte výše uvedené kroky pro přidání balíčku MIP File SDK, ale místo toho do aplikace přidejte Microsoft.Identity.Client.

Implementace delegáta ověřování

Sada MIP SDK implementuje ověřování pomocí rozšiřitelnosti tříd, který poskytuje mechanismus pro sdílení ověřování s klientskou aplikací. Klient musí získat vhodný přístupový token OAuth2 a poskytnout sadě MIP SDK za běhu.

Teď vytvořte implementaci pro delegáta ověřování rozšířením rozhraní sady SDK Microsoft.InformationProtection.IAuthDelegate a přepsáním/implementací IAuthDelegate.AcquireToken() virtuální funkce. Delegát ověřování se vytvoří instance a později se použije pro FileProfile objekty a FileEngine objekty.

Klikněte pravým tlačítkem myši na název projektu v sadě Visual Studio a vyberte Přidat a potom třídu.
Do pole Název zadejte AuthDelegateImplementation. Klikněte na tlačítko Přidat.
Přidejte příkazy using pro knihovnu MSAL (Microsoft Authentication Library) a knihovnu MIP:
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
Nastavte AuthDelegateImplementation na dědění Microsoft.InformationProtection.IAuthDelegate a implementaci privátní proměnné Microsoft.InformationProtection.ApplicationInfo a konstruktoru, který přijímá stejný typ.
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
Objekt ApplicationInfo obsahuje tři vlastnosti. Použije _appInfo.ApplicationId se ve AuthDelegateImplementation třídě k zadání ID klienta do knihovny ověřování. ApplicationName a ApplicationVersion zobrazí se v sestavách Azure Information Protection Analytics.

Přidejte metodu public string AcquireToken() . V případě potřeby by tato metoda měla přijmout Microsoft.InformationProtection.Identity a tři řetězce: adresa URL autority, identifikátor URI prostředku a deklarace identity. Tyto řetězcové proměnné se předají do knihovny ověřování rozhraním API a neměly by být manipulovány. Zadejte identifikátor GUID tenanta z webu Azure Portal pro vašeho tenanta. Úprava řetězců jiných než IDENTIFIKÁTOR GUID tenanta může způsobit selhání ověření.

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;
}

Nyní vytvořte implementaci pro delegáta souhlasu rozšířením rozhraní sady SDK Microsoft.InformationProtection.IConsentDelegate a přepsáním nebo implementací GetUserConsent(). Delegát souhlasu se vytvoří instance a později ho použije objekty file profile a file engine. Delegát souhlasu je poskytován s adresou služby, kterou uživatel musí odsouhlasit použití v parametru url . Delegát by měl obecně poskytnout určitý tok, který uživateli umožní přijmout nebo odmítnout souhlas s přístupem ke službě. Pro tento rychlý start pevný kód Consent.Accept.

Pomocí stejné funkce Přidat třídu sady Visual Studio, kterou jsme použili dříve, přidejte do projektu další třídu. Tentokrát do pole Název třídy zadejte ConsentDelegateImplementation.
Nyní aktualizujte ConsentDelegateImpl.cs pro implementaci nové třídy delegáta souhlasu. Přidejte příkaz using pro Microsoft.InformationProtection a nastavte třídu tak, aby dědila IConsentDelegate.
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
Volitelně se pokuste sestavit řešení, aby se zajistilo, že se zkompiluje bez chyb.

Inicializace spravované obálky sady MIP SDK

Z Průzkumník řešení otevřete soubor .cs v projektu, který obsahuje implementaci Main() metody. Ve výchozím nastavení se použije stejný název jako projekt, který obsahuje, který jste zadali při vytváření projektu.
Odeberte vygenerovanou implementaci .main()
Spravovaný obálka obsahuje statickou třídu, Microsoft.InformationProtection.MIP která se používá k inicializaci, vytvoření MipContext, načítání profilů a uvolnění prostředků. Chcete-li inicializovat obálku pro operace se sadou File SDK, zavolejte MIP.Initialize()a předejte MipComponent.File knihovny potřebné pro operace se soubory.
Do Main() souboru Program.cs přidejte následující kód a nahraďte <ID> aplikace ID registrace aplikace Microsoft Entra vytvořené dříve.

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);
            
        }
    }
}

Vytvoření profilu souboru a modulu

Jak už bylo zmíněno, objekty profilu a modulu jsou vyžadovány pro klienty sady SDK pomocí rozhraní API MIP. Dokončete část kódu tohoto rychlého startu přidáním kódu pro načtení nativních knihoven DLL a vytvořte instanci objektu profilu a modulu.

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;
       }
  }
}

Zástupné hodnoty ve zdrojovém kódu, do kterého jste vložili, nahraďte následujícími hodnotami:

Zástupný symbol	Hodnota	Příklad
<ID aplikace>	ID aplikace Microsoft Entra přiřazené k aplikaci zaregistrované v nastavení a konfiguraci sady MIP SDK (2 instance).	0edbblll-8773-44de-b87c-b8c6276d41eb
<popisný název>	Uživatelsky definovaný popisný název aplikace.	AppInitialization
<Guid tenanta>	ID tenanta pro vašeho tenanta Microsoft Entra	TenantID

Teď proveďte finální sestavení aplikace a vyřešte případné chyby. Kód by se měl úspěšně sestavit.

Další kroky

Teď, když je inicializační kód hotový, jste připraveni na další rychlý start, kde začnete používat sady MIP File SDK.

Výpis popisků citlivosti

Sdílet prostřednictvím

Rychlý start: Inicializace klientské aplikace (C#)

Předpoklady

Vytvoření řešení a projektu sady Visual Studio

Implementace delegáta ověřování

Inicializace spravované obálky sady MIP SDK

Vytvoření profilu souboru a modulu

Další kroky

Váš názor

Další materiály

Sdílet prostřednictvím

Rychlý start: Inicializace klientské aplikace (C#)

Předpoklady

Vytvoření řešení a projektu sady Visual Studio

Implementace delegáta ověřování

Implementace delegáta souhlasu

Inicializace spravované obálky sady MIP SDK

Vytvoření profilu souboru a modulu

Další kroky

Váš názor

Další materiály