Rövid útmutató: Ügyfélalkalmazás inicializálása (C#)

Cikk
10/18/2023

Ez a rövid útmutató bemutatja, hogyan implementálhatja az ügyfél inicializálási mintáját, amelyet a MIP SDK .NET burkoló használ futásidőben.

Megjegyzés:

Az ebben a rövid útmutatóban ismertetett lépések szükségesek minden olyan ügyfélalkalmazáshoz, amely a MIP .NET burkoló fájlját, házirendjét vagy védelmi SDK-ját használja. Bár ez a rövid útmutató bemutatja a Fájl SDK-k használatát, ugyanez a minta vonatkozik a Szabályzat és védelem SDK-kat használó ügyfelekre is. A jövőbeli rövid útmutatókat sorozatosan kell elvégezni, mivel mindegyik az előzőre épül, és ez az első. Ez a kód a MIP SDK használatának első lépéseit mutatja be, és nem éles használatra készült.

Előfeltételek

Ha még nem tette meg, ügyeljen a következőre:

Hajtsa végre a Microsoft Information Protection (MIP) SDK beállításának és konfigurálásának lépéseit. Ez az "ügyfélalkalmazás inicializálása" rövid útmutató az SDK megfelelő beállítására és konfigurálására támaszkodik.
Tetszés szerint:
- Profil- és motorobjektumok áttekintése. A profil- és motorobjektumok univerzális fogalmak, amelyeket a MIP-fájlokat/szabályzatokat/védelmi SDK-okat használó ügyfelek igényelnek.
- Tekintse át a hitelesítési fogalmakat , és ismerje meg, hogyan valósítja meg a hitelesítést és a hozzájárulást az SDK és az ügyfélalkalmazás.

Visual Studio-megoldás és projekt létrehozása

Először létrehozzuk és konfiguráljuk a Visual Studio kezdeti megoldását és projektét, amelyre a többi rövid útmutató is épülni fog.

Nyissa meg a Visual Studio 2019-et, válassza a Fájl menü Új, Projekt parancsát. Az Új projekt párbeszédpanelen:
- A bal oldali panelEn a Visual C# alatt válassza a Windows Desktop lehetőséget.
- A középső panelen válassza a Konzolalkalmazás (.NET-keretrendszer) lehetőséget
- Az alsó panelen ennek megfelelően frissítse a projekt nevét, helyét és az azt tartalmazó megoldásnevet .
- Ha végzett, kattintson az OK gombra a jobb alsó sarokban.
Adja hozzá a MiP File SDK Nuget-csomagját a projekthez:
- A Megoldáskezelő kattintson a jobb gombbal a projektcsomópontra (közvetlenül a felső/megoldáscsomópont alatt), és válassza a NuGet-csomagok kezelése...:
- Amikor megnyílik a NuGet Csomagkezelő lap a Szerkesztőcsoport lapfülek területén:
  - Válassza a Tallózás lehetőséget.
  - Írja be a "Microsoft.InformationProtection" kifejezést a keresőmezőbe.
  - Válassza a "Microsoft.InformationProtection.File" csomagot.
  - Kattintson a "Telepítés", majd az "OK" gombra, amikor megjelenik az Előzetes verzió módosításainak megerősítése párbeszédpanel.
Ismételje meg a fenti lépéseket a MIP-fájl SDK-csomagjának hozzáadásához, de ehelyett adja hozzá a "Microsoft.Identity.Client" elemet az alkalmazáshoz.

Hitelesítési meghatalmazott implementálása

A MIP SDK az osztály bővíthetőségével valósítja meg a hitelesítést, amely lehetővé teszi a hitelesítés megosztását az ügyfélalkalmazással. Az ügyfélnek be kell szereznie egy megfelelő OAuth2 hozzáférési jogkivonatot, és futásidőben meg kell adnia a MIP SDK-nak.

Most hozzon létre egy implementációt egy hitelesítési delegált számára az SDK felületének Microsoft.InformationProtection.IAuthDelegate kibővítésével, valamint a IAuthDelegate.AcquireToken() virtuális függvény felülbírálásával/implementálásával. A hitelesítési meghatalmazott példányosítása és használata később történik az és FileEngine az FileProfile objektumok számára.

Kattintson a jobb gombbal a projekt nevére a Visual Studióban, és válassza a Hozzáadás , majd az Osztály lehetőséget.
Írja be az "AuthDelegateImplementation" kifejezést a Név mezőbe. Kattintson a Hozzáadás parancsra.
Adja hozzá a Microsoft Authentication Library (MSAL) és a MIP-kódtár felhasználói utasításait:
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
Úgy van beállítva AuthDelegateImplementation , hogy örököljön Microsoft.InformationProtection.IAuthDelegate és implementáljon egy privát változót Microsoft.InformationProtection.ApplicationInfo és egy konstruktort, amely ugyanazt a típust fogadja el.
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
Az ApplicationInfo objektum három tulajdonságot tartalmaz. A _appInfo.ApplicationId rendszer az AuthDelegateImplementation osztályban az ügyfélazonosító megadására szolgál a hitelesítési kódtár számára. ApplicationName és ApplicationVersion megjelennek az Azure Information Protection Analytics-jelentésekben.

Adja hozzá a metódust public string AcquireToken() . Ennek a metódusnak három sztringet kell elfogadnia Microsoft.InformationProtection.Identity : a szolgáltató URL-címét, az erőforrás-URI-t és a jogcímeket, ha szükséges. Ezeket a sztringváltozókat az API átadja a hitelesítési kódtárnak, és nem szabad manipulálni őket. Adja meg a bérlő GUID azonosítóját az Azure Portalról a bérlőhöz. A bérlői GUID-tól eltérő sztringek szerkesztése sikertelen hitelesítést eredményezhet.

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

Most hozzon létre egy implementációt egy hozzájárulási meghatalmazott számára az SDK felületének Microsoft.InformationProtection.IConsentDelegate kibővítésével, valamint a felülbírálással/implementálással GetUserConsent(). A hozzájárulási meghatalmazottat a fájlprofil és a fájlmotor objektumai később példányosítják és használják. A hozzájárulási meghatalmazott megadja annak a szolgáltatásnak a címét, amelyet a felhasználónak engedélyeznie kell a url paraméterben való használathoz. A meghatalmazottnak általában olyan folyamatot kell biztosítania, amely lehetővé teszi a felhasználó számára, hogy elfogadja vagy elutasítsa a szolgáltatáshoz való hozzáféréshez való hozzájárulást. Ebben a rövid útmutatóban szereplő kemény kód Consent.Accept.

Ha ugyanazt a Visual Studio "Osztály hozzáadása" funkciót használja, amelyet korábban használt, vegyen fel egy másik osztályt a projektbe. Ezúttal írja be a "ConsentDelegateImplementation" kifejezést az Osztálynév mezőbe.
Most frissítse a ConsentDelegateImpl.cs fájlt az új hozzájárulási delegált osztály implementálásához. Adja hozzá a using utasítást, Microsoft.InformationProtection és állítsa be az osztály öröklésére IConsentDelegate.
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
Ha szeretné, próbálja meg létrehozni a megoldást, hogy hiba nélkül lefordítsa.

A MIP SDK felügyelt burkolójának inicializálása

A Megoldáskezelő nyissa meg a metódus implementálását tartalmazó .cs fájlt a Main() projektben. Alapértelmezés szerint ugyanaz a név lesz, mint a projektet tartalmazó projekt, amelyet a projekt létrehozásakor adott meg.
Távolítsa el a generált implementációt.main()
A felügyelt burkoló tartalmaz egy statikus osztályt, Microsoft.InformationProtection.MIP amelyet inicializálásra, profilok MipContextlétrehozására, betöltésére és erőforrások felszabadítására használnak. A File SDK-műveletek burkolójának inicializálásához hívja MIP.Initialize()meg, majd adja át MipComponent.File a fájlműveletekhez szükséges kódtárakat.
A Main() Program.cs fájlban adja hozzá a következőket, és cserélje le <az alkalmazásazonosítót> a korábban létrehozott Microsoft Entra-alkalmazásregisztráció azonosítójára.

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

Fájlprofil és -motor létrehozása

Ahogy említettük, profil- és motorobjektumok szükségesek a MIP API-kat használó SDK-ügyfelekhez. Töltse ki a rövid útmutató kódolási részét úgy, hogy kódot ad hozzá a natív DLL-ek betöltéséhez, majd példányosíthatja a profilt és a motorobjektumokat.

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

Cserélje le a beszúrt forráskód helyőrző értékeit a következő értékekkel:

Helyőrző	Value	Example
<alkalmazásazonosító>	A Microsoft Entra alkalmazásazonosítója a "MIP SDK beállításában és konfigurációjában" regisztrált alkalmazáshoz (2 példány).	0edbblll-8773-44de-b87c-b8c6276d41eb
<rövid név>	Az alkalmazás felhasználó által definiált rövid neve.	AppInitialization
<Bérlő–GUID>	A Microsoft Entra-bérlő bérlőazonosítója	Bérlőazonosító

Most készítse el az alkalmazás végleges buildjét, és oldja meg a hibákat. A kódnak sikeresen létre kell épülnie.

Következő lépések

Most, hogy elkészült az inicializálási kód, készen áll a következő rövid útmutatóra, ahol megkezdheti a MIP-fájl SDK-k használatát.

Bizalmassági címkék listázása

Megosztás a következőn keresztül:

Rövid útmutató: Ügyfélalkalmazás inicializálása (C#)

Előfeltételek

Visual Studio-megoldás és projekt létrehozása

Hitelesítési meghatalmazott implementálása

A MIP SDK felügyelt burkolójának inicializálása

Fájlprofil és -motor létrehozása

Következő lépések

Visszajelzés

Visszajelzés

További források

Megosztás a következőn keresztül:

Rövid útmutató: Ügyfélalkalmazás inicializálása (C#)

Előfeltételek

Visual Studio-megoldás és projekt létrehozása

Hitelesítési meghatalmazott implementálása

Hozzájárulási meghatalmazott implementálása

A MIP SDK felügyelt burkolójának inicializálása

Fájlprofil és -motor létrehozása

Következő lépések

Visszajelzés

Visszajelzés

További források