Guida introduttiva: Inizializzazione dell'applicazione client (C#)

Questa guida introduttiva illustra come implementare il modello di inizializzazione client usato da MIP SDK .NET wrapper in fase di esecuzione.

Prerequisiti

Se non è già stato fatto, assicurarsi di:

• Completare i passaggi della configurazione e della configurazione di Microsoft Information Protection SDK (MIP). Questa Guida Rapida all'inizializzazione dell'applicazione client si basa sull'installazione e configurazione corrette dell'SDK.
• Facoltativamente:
  • Esaminare gli oggetti profilo e motore. I profili e gli oggetti motore sono concetti universali, richiesti dai client che usano gli SDK di protezione/file/criteri MIP.
  • Vedere Concetti relativi all'autenticazione per informazioni su come l'SDK e l'applicazione client implementano l'autenticazione e il consenso.

Creare una soluzione e un progetto di Visual Studio

Per prima cosa, creare e configurare la soluzione e il progetto iniziali di Visual Studio, su cui si basano le altre guide introduttive.

1. Aprire Visual Studio 2022 o versione successiva, selezionare il menu File , Nuovo, Progetto. Nella finestra di dialogo Nuovo progetto :

   • Nel riquadro sinistro, in Installato, Visual C#, selezionare Desktop di Windows.

   • Nel riquadro centrale selezionare App console (destinazione .NET 8 o versione successiva).

   • Nel riquadro inferiore aggiornare di conseguenza il nome del progetto, il percorso e il nome della soluzione che lo contiene.

   • Al termine, fare clic sul pulsante OK in basso a destra.

     

2. Aggiungere il pacchetto NuGet per MIP File SDK al progetto:

   • In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto (direttamente sotto il nodo superiore/soluzione) e scegliere Gestisci pacchetti NuGet...:
   • Quando si apre la scheda Gestione pacchetti NuGet nell'area schede del gruppo dell'editor:
     • Selezionare Sfoglia.
     • Immettere "Microsoft.InformationProtection" nella casella di ricerca.
     • Selezionare il pacchetto "Microsoft.InformationProtection.File".
     • Fare clic su "Installa", quindi su "OK" quando viene visualizzata la finestra di dialogo di conferma delle modifiche dell'anteprima .

3. Ripetere i passaggi precedenti per aggiungere il pacchetto MIP File SDK, ma aggiungere "Microsoft.Identity.Client" all'applicazione.

Implementare un delegato di autenticazione

MIP SDK implementa l'autenticazione usando l'estendibilità della classe, che fornisce un meccanismo per condividere l'autenticazione con l'applicazione client. Il client deve acquisire un token di accesso OAuth2 appropriato e fornirlo all'SDK MIP in fase di esecuzione.

Creare ora un'implementazione per un delegato di autenticazione estendendo l'interfaccia Microsoft.InformationProtection.IAuthDelegate dell'SDK ed eseguendo l'override della funzione virtuale IAuthDelegate.AcquireToken() o implementandola. Gli oggetti FileProfile e FileEngine istanziano e utilizzano successivamente il delegato di autenticazione.

1. Fare clic con il pulsante destro del mouse sul nome del progetto in Visual Studio, scegliere Aggiungi e quindi Classe.

2. Immettere "AuthDelegateImplementation" nel campo Nome . Fare clic su Aggiungi.

3. Aggiungere istruzioni using per Libreria di Autenticazione Microsoft (MSAL) e la libreria MIP:

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

4. Impostare AuthDelegateImplementation per ereditare Microsoft.InformationProtection.IAuthDelegate e implementare una variabile privata di Microsoft.InformationProtection.ApplicationInfo e un costruttore che accetta lo stesso tipo.

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

   L'oggetto ApplicationInfo contiene tre proprietà. La AuthDelegateImplementation classe usa _appInfo.ApplicationId per fornire l'ID client alla libreria di autenticazione. ApplicationNamee ApplicationVersion vengono visualizzati nei report di controllo Microsoft Purview.

5. Aggiungere il public string AcquireToken() metodo . Questo metodo deve accettare Microsoft.InformationProtection.Identity e tre stringhe: URL dell'autorità, URI della risorsa e attestazioni, se necessario. L'API passa queste variabili stringa alla libreria di autenticazione e non è consigliabile modificarle. Immettere il GUID del tenant dal portale di Azure per il tenant. La modifica di stringhe diverse dal GUID del tenant potrebbe causare un errore di autenticazione.

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

Implementare un delegato di consenso

Creare ora un'implementazione per un delegato del consenso estendendo l'interfaccia Microsoft.InformationProtection.IConsentDelegate dell'SDK e sovrascrivendo o implementando GetUserConsent(). Gli oggetti del profilo File e di File engine istanziano e utilizzano successivamente il delegato per il consenso. Il delegato di consenso riceve l'indirizzo del servizio che l'utente deve fornire il consenso per l'uso nel url parametro . Il delegato deve in genere fornire un flusso che consenta all'utente di accettare o rifiutare il consenso per accedere al servizio. Per questa guida rapida, codifica in modo statico Consent.Accept.

1. Usando la stessa funzionalità "Aggiungi classe" di Visual Studio usata in precedenza, aggiungere un'altra classe al progetto. Questa volta, immetti "ConsentDelegateImplementation" nel campo Nome classe.

2. Aggiornare ConsentDelegateImpl.cs per implementare la nuova classe delegato consenso. Aggiungere l'istruzione using per Microsoft.InformationProtection e impostare la classe per ereditare IConsentDelegate.

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

3. Facoltativamente, tentare di compilare la soluzione per assicurarsi che venga compilata senza errori.

Inizializzare il wrapper gestito di MIP SDK

1. In Esplora soluzioni aprire il file .cs nel progetto che contiene l'implementazione del Main() metodo . Per impostazione predefinita, assume lo stesso nome del progetto che lo contiene, specificato durante la creazione del progetto.

2. Rimuovere l'implementazione generata di main().

3. Il wrapper gestito include una classe statica, Microsoft.InformationProtection.MIP usata per l'inizializzazione, la creazione di un MipContext, il caricamento di profili e il rilascio di risorse. Per inizializzare il wrapper per le operazioni di File SDK, chiamare MIP.Initialize(), passando MipComponent.File per caricare le librerie necessarie per le operazioni sui file.

4. In Main() in Program.cs aggiungere quanto segue, sostituendo <application-id> con l'ID della registrazione dell'applicazione Microsoft Entra creata in precedenza.

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

Creare un profilo di file e un motore

Come accennato, i client dell'SDK che usano le API MIP richiedono oggetti profilo e oggetti motore. Completa la parte relativa al codice di questa guida rapida aggiungendo il codice per caricare le DLL native e quindi istanziare gli oggetti profilo e motore.

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

3. Sostituire i valori segnaposto nel codice sorgente incollato usando i valori seguenti:

   Placeholder	Value	Example
   <application-id>	ID dell'applicazione Microsoft Entra assegnato all'applicazione registrata in "Installazione e configurazione di MIP SDK" (2 istanze).	00001111-aaaa-2222-bbbb-3333cccc44444
   <nome-amichevole>	Nome descrittivo definito dall'utente per l'applicazione.	Inizializzazione dell'App
   <Tenant-GUID>	ID tenant per il tenant Microsoft Entra.	TenantID

4. A questo punto, eseguire una compilazione finale dell'applicazione e risolvere eventuali errori. Il tuo codice dovrà essere compilato con successo.

Passaggi successivi

Ora che il codice di inizializzazione è completo, sei pronto per la prossima guida introduttiva rapida, in cui inizierai a provare i File SDK di MIP.