Snabbstart: Initiering av klientprogram (C#)

Artikel
10/18/2023

Den här snabbstarten visar hur du implementerar klientinitieringsmönstret, som används av MIP SDK .NET-omslutningen vid körning.

Kommentar

De steg som beskrivs i den här snabbstarten krävs för alla klientprogram som använder MIP .NET-omslutningens SDK:er för fil, princip eller skydd. Även om den här snabbstarten visar hur fil-SDK:erna används, gäller samma mönster för klienter som använder SDK:er för princip och skydd. Framtida snabbstarter bör utföras seriellt, eftersom var och en bygger på den föregående, där den här är den första. Den här koden är avsedd att visa hur du kommer igång med MIP SDK och inte är avsedd för produktionsanvändning.

Förutsättningar

Om du inte redan har gjort det måste du:

Slutför stegen i Konfiguration och konfiguration av Microsoft Information Protection (MIP) SDK. Den här snabbstarten "Klientprograminitiering" förlitar sig på korrekt SDK-konfiguration.
Valfritt:
- Granska profil- och motorobjekt. Profil- och motorobjekten är universella begrepp som krävs av klienter som använder SDK:er för MIP-fil/princip/skydd.
- Läs Autentiseringsbegrepp för att lära dig hur autentisering och medgivande implementeras av SDK och klientprogrammet.

Skapa en Visual Studio-lösning och ett projekt

Först skapar och konfigurerar vi den första Visual Studio-lösningen och projektet, som de andra snabbstarterna bygger på.

Öppna Visual Studio 2019, välj menyn Arkiv , Nytt, Projekt. I dialogrutan Nytt projekt:
- I den vänstra rutan, under Installerad, Visual C#, väljer du Windows Desktop.
- I mittenfönstret väljer du Konsolapp (.NET Framework)
- I den nedre rutan uppdaterar du projektets namn, plats och det innehållande lösningsnamnet i enlighet med detta.
- När du är klar klickar du på OK-knappen längst ned till höger.
Lägg till Nuget-paketet för MIP File SDK i projektet:
- I Solution Explorer högerklickar du på projektnoden (direkt under den övre noden/lösningsnoden) och väljer Hantera NuGet-paket...:
- När fliken NuGet Package Manager öppnas i området Redigerargruppflikar:
  - Välj bläddra.
  - Ange "Microsoft.InformationProtection" i sökrutan.
  - Välj paketet "Microsoft.InformationProtection.File".
  - Klicka på "Installera" och sedan på "OK" när bekräftelsedialogrutan Förhandsgranskningsändringar visas.
Upprepa stegen ovan för att lägga till MIP File SDK-paketet, men lägg i stället till "Microsoft.Identity.Client" i programmet.

Implementera en autentiseringsdelegat

MIP SDK implementerar autentisering med hjälp av utökningsbarhet för klassen, vilket ger en mekanism för att dela autentiseringsarbete med klientprogrammet. Klienten måste hämta en lämplig OAuth2-åtkomsttoken och tillhandahålla MIP SDK vid körning.

Skapa nu en implementering för en autentiseringsdelegat genom att utöka SDK:ts Microsoft.InformationProtection.IAuthDelegate gränssnitt och åsidosätta/implementera den IAuthDelegate.AcquireToken() virtuella funktionen. Autentiseringsdelegaten instansieras och används senare av objekten FileProfile och FileEngine .

Högerklicka på projektnamnet i Visual Studio, välj Lägg till och sedan Klass.
Ange "AuthDelegateImplementation" i fältet Namn . Klicka på Lägg till.
Lägg till using-instruktioner för Microsoft Authentication Library (MSAL) och MIP-biblioteket:
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
Ange AuthDelegateImplementation att ärva Microsoft.InformationProtection.IAuthDelegate och implementera en privat variabel för Microsoft.InformationProtection.ApplicationInfo och en konstruktor som accepterar samma typ.
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
Objektet ApplicationInfo innehåller tre egenskaper. _appInfo.ApplicationId Används i AuthDelegateImplementation klassen för att ange klient-ID:t till autentiseringsbiblioteket. ApplicationName och ApplicationVersion visas i Azure Information Protection Analytics-rapporter.

public string AcquireToken() Lägg till metoden. Den här metoden bör acceptera Microsoft.InformationProtection.Identity och tre strängar: utfärdar-URL, resurs-URI och anspråk om det behövs. Dessa strängvariabler skickas till autentiseringsbiblioteket av API:et och bör inte ändras. Ange klientorganisations-GUID från Azure-portalen för din klientorganisation. Om du redigerar andra strängar än klientorganisations-GUID kan det leda till att det inte går att autentisera.

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

Skapa nu en implementering för ett medgivandedelegat genom att utöka SDK:ts Microsoft.InformationProtection.IConsentDelegate gränssnitt och åsidosätta/implementera GetUserConsent(). Medgivandedelegaten instansieras och används senare av objekten Filprofil och Filmotor. Medgivandedelegeringen tillhandahålls med adressen till tjänsten som användaren måste samtycka till att använda i parametern url . Ombudet bör i allmänhet tillhandahålla ett flöde som gör att användaren kan acceptera eller avvisa medgivande för att få åtkomst till tjänsten. För den här snabbstarten hårdkod Consent.Accept.

Med samma Visual Studio-funktion "Lägg till klass" som vi använde tidigare lägger du till en annan klass i projektet. Den här gången anger du "ConsentDelegateImplementation" i fältet Klassnamn .
Uppdatera ConsentDelegateImpl.cs för att implementera din nya medgivandedelegatklass. Lägg till instruktionen using för Microsoft.InformationProtection och ange klassen som ärver IConsentDelegate.
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
Du kan också försöka skapa lösningen för att säkerställa att den kompileras utan fel.

Initiera MIP SDK Managed Wrapper

Öppna .cs-filen i projektet som innehåller implementeringen av Main() metoden från Solution Explorer. Det är som standard samma namn som det projekt som innehåller det, som du angav när projektet skapades.
Ta bort den genererade implementeringen av main().
Den hanterade omslutningen innehåller en statisk klass som Microsoft.InformationProtection.MIP används för initiering, skapar en MipContext, läser in profiler och frigör resurser. Om du vill initiera omslutningen för File SDK-åtgärder anropar MIP.Initialize()du och skickar in MipComponent.File för att läsa in de bibliotek som krävs för filåtgärder.
I Main() Program.cslägger du till följande och ersätter <program-ID> med ID:t för Microsoft Entra-programregistreringen som skapades tidigare.

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

Skapa en filprofil och motor

Som nämnts krävs profil- och motorobjekt för SDK-klienter med hjälp av MIP-API:er. Slutför kodningsdelen av den här snabbstarten genom att lägga till kod för att läsa in de interna DLL:erna och sedan instansiera profil- och motorobjekten.

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

Ersätt platshållarvärdena i källkoden som du klistrade in med hjälp av följande värden:

Platshållare	Värde	Exempel
<application-id>	Microsoft Entra-program-ID:t som tilldelats programmet som registrerats i "MIP SDK-konfiguration" (2 instanser).	0edbblll-8773-44de-b87c-b8c6276d41eb
<friendly-name>	Ett användardefinierat eget namn för ditt program.	AppInitialisering
<Klientorganisations-GUID>	Klientorganisations-ID för din Microsoft Entra-klientorganisation	TenantID

Gör nu en slutlig version av programmet och lös eventuella fel. Koden bör skapas.

Nästa steg

Nu när initieringskoden är klar är du redo för nästa snabbstart, där du börjar uppleva MIP-fil-SDK:erna.

Lista känslighetsetiketter

Dela via

Snabbstart: Initiering av klientprogram (C#)

Förutsättningar

Skapa en Visual Studio-lösning och ett projekt

Implementera en autentiseringsdelegat

Initiera MIP SDK Managed Wrapper

Skapa en filprofil och motor

Nästa steg

Feedback

Ytterligare resurser

Dela via

Snabbstart: Initiering av klientprogram (C#)

Förutsättningar

Skapa en Visual Studio-lösning och ett projekt

Implementera en autentiseringsdelegat

Implementera en medgivandedelegat

Initiera MIP SDK Managed Wrapper

Skapa en filprofil och motor

Nästa steg

Feedback

Ytterligare resurser