Quickstart: Initialisatie van clienttoepassingen (C#)

Artikel
10/18/2023

In deze quickstart ziet u hoe u het initialisatiepatroon van de client implementeert, dat tijdens runtime wordt gebruikt door de MIP SDK .NET-wrapper.

Notitie

De stappen die in deze quickstart worden beschreven, zijn vereist voor elke clienttoepassing die gebruikmaakt van de SDK's bestand, beleid of beveiliging van MIP .NET-wrapper. Hoewel in deze quickstart het gebruik van de bestands-SDK's wordt gedemonstreert, is hetzelfde patroon van toepassing op clients die gebruikmaken van de SDK's voor beleid en beveiliging. Toekomstige quickstarts moeten serieel worden uitgevoerd, omdat elke quickstart voortbouwt op de vorige, waarbij dit de eerste is. Deze code is bedoeld om aan de slag te gaan met de MIP SDK en is niet bedoeld voor productiegebruik.

Vereisten

Als u dat nog niet hebt gedaan, moet u het volgende doen:

Voer de stappen uit in de installatie en configuratie van microsoft Information Protection (MIP) SDK. Deze quickstart voor de initialisatie van clienttoepassingen is afhankelijk van de juiste SDK-installatie en -configuratie.
Optioneel:
- Profiel- en engineobjecten controleren. Het profiel- en engineobject zijn universele concepten die vereist zijn voor clients die gebruikmaken van de MIP File/Policy/Protection SDK's.
- Bekijk de verificatieconcepten om te leren hoe verificatie en toestemming worden geïmplementeerd door de SDK en clienttoepassing.

Een Visual Studio-oplossing en -project maken

Eerst maken en configureren we de eerste Visual Studio-oplossing en -project, waarop de andere quickstarts worden gebouwd.

Open Visual Studio 2019, selecteer het menu Bestand , Nieuw, Project. In het dialoogvenster Nieuw project :
- Selecteer Windows Desktop in het linkerdeelvenster onder Geïnstalleerd, Visual C#.
- Selecteer Console-app (.NET Framework) in het middelste deelvenster
- Werk in het onderste deelvenster de projectnaam, locatie en de naam van de oplossing dienovereenkomstig bij.
- Wanneer u klaar bent, klikt u op de knop OK in de rechterbenedenhoek.
Voeg het Nuget-pakket voor de MIP File SDK toe aan uw project:
- Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt (direct onder het bovenste/oplossingsknooppunt) en selecteer NuGet-pakketten beheren...:
- Wanneer het tabblad NuGet Pakketbeheer wordt geopend in het tabbladen editorgroep:
  - Selecteer Bladeren.
  - Voer 'Microsoft.InformationProtection' in het zoekvak in.
  - Selecteer het pakket Microsoft.InformationProtection.File.
  - Klik op Installeren en klik vervolgens op OK wanneer het bevestigingsvenster voor wijzigingen in het voorbeeld wordt weergegeven.
Herhaal de bovenstaande stappen voor het toevoegen van het MIP File SDK-pakket, maar voeg in plaats daarvan 'Microsoft.Identity.Client' toe aan de toepassing.

Een verificatiedelegatie implementeren

De MIP SDK implementeert verificatie met behulp van klasse-uitbreidbaarheid. Dit biedt een mechanisme voor het delen van verificatie met de clienttoepassing. De client moet een geschikt OAuth2-toegangstoken verkrijgen en tijdens runtime aan de MIP-SDK verstrekken.

Maak nu een implementatie voor een verificatiedelegen door de INTERFACE van Microsoft.InformationProtection.IAuthDelegate de SDK uit te breiden en de IAuthDelegate.AcquireToken() virtuele functie te overschrijven/implementeren. De verificatiedelegatie wordt geïnstantieerd en later gebruikt door de FileProfile en FileEngine objecten.

Klik met de rechtermuisknop op de projectnaam in Visual Studio en selecteer Vervolgens Klasse toevoegen.
Voer 'AuthDelegateImplementation' in het veld Naam in. Klik op Toevoegen.
Gebruiksinstructies toevoegen voor de Microsoft Authentication Library (MSAL) en de MIP-bibliotheek:
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
Ingesteld AuthDelegateImplementation op het overnemen Microsoft.InformationProtection.IAuthDelegate en implementeren van een privévariabele van Microsoft.InformationProtection.ApplicationInfo en een constructor die hetzelfde type accepteert.
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
Het ApplicationInfo object bevat drie eigenschappen. De _appInfo.ApplicationId wordt in de AuthDelegateImplementation klasse gebruikt om de client-id op te geven aan de verificatiebibliotheek. ApplicationName en ApplicationVersion wordt weergegeven in Azure Information Protection Analytics-rapporten.

Voeg de public string AcquireToken() methode toe. Deze methode moet accepteren Microsoft.InformationProtection.Identity en drie tekenreeksen: instantie-URL, resource-URI en claims, indien nodig. Deze tekenreeksvariabelen worden door de API doorgegeven aan de verificatiebibliotheek en mogen niet worden gemanipuleerd. Voer tenant-GUID in vanuit de Azure-portal voor uw tenant. Het bewerken van andere tekenreeksen dan de tenant-GUID kan leiden tot een fout bij het verifiëren.

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

Maak nu een implementatie voor een toestemmingsdelegatie door de INTERFACE van Microsoft.InformationProtection.IConsentDelegate de SDK uit te breiden en overschrijven/implementeren GetUserConsent(). De gemachtigde voor toestemming wordt geïnstantieerd en later gebruikt door de bestandsprofiel- en bestandsengineobjecten. De gedelegeerde voor toestemming wordt geleverd met het adres van de service waarvoor de gebruiker toestemming moet geven voor gebruik in de url parameter. De gedelegeerde moet over het algemeen een stroom opgeven waarmee de gebruiker toestemming kan geven voor toegang tot de service. Voor deze quickstart-hardcode Consent.Accept.

Met dezelfde Visual Studio-functie Klasse toevoegen die we eerder hebben gebruikt, voegt u een andere klasse toe aan uw project. Voer deze keer ConsentDelegateImplementation in het veld Klassenaam in.
Werk consentDelegateImpl.cs nu bij om uw nieuwe klasse toestemmingsdelegatie te implementeren. Voeg de using-instructie voor Microsoft.InformationProtection en stel de klasse in op overnemen IConsentDelegate.
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
Probeer eventueel de oplossing te bouwen om ervoor te zorgen dat deze zonder fouten wordt gecompileerd.

De beheerde wrapper van de MIP SDK initialiseren

Open vanuit Solution Explorer het .cs-bestand in uw project dat de implementatie van de Main() methode bevat. Deze wordt standaard ingesteld op dezelfde naam als het project dat het bevat, die u hebt opgegeven tijdens het maken van het project.
Verwijder de gegenereerde implementatie van main().
De beheerde wrapper bevat een statische klasse die Microsoft.InformationProtection.MIP wordt gebruikt voor initialisatie, het maken van een MipContext, laadprofielen en het vrijgeven van resources. Als u de wrapper voor bestands-SDK-bewerkingen wilt initialiseren, roept u het aan MIP.Initialize()en geeft u door MipComponent.File om de bibliotheken te laden die nodig zijn voor bestandsbewerkingen.
Voeg Main() in Program.cs het volgende toe, waarbij <u de toepassings-id> vervangt door de id van de Microsoft Entra-toepassingsregistratie die u eerder hebt gemaakt.

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

Een bestandsprofiel en -engine maken

Zoals vermeld, zijn profiel- en engineobjecten vereist voor SDK-clients die GEBRUIKMAKEN van MIP-API's. Voltooi het coderingsgedeelte van deze quickstart door code toe te voegen om de systeemeigen DLL's te laden en vervolgens het profiel- en engineobject te instantiëren.

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

Vervang de tijdelijke aanduidingen in de broncode waarin u hebt geplakt, met behulp van de volgende waarden:

Tijdelijke aanduiding	Waarde	voorbeeld
<toepassings-id>	De Microsoft Entra-toepassings-id die is toegewezen aan de toepassing die is geregistreerd in 'MIP SDK setup and configuration' (2 exemplaren).	0edbblll-8773-44de-b87c-b8c6276d41eb
<beschrijvende naam>	Een door de gebruiker gedefinieerde beschrijvende naam voor uw toepassing.	AppInitialization
<Tenant-GUID>	Tenant-id voor uw Microsoft Entra-tenant	TenantID

Voer nu een definitieve build van de toepassing uit en los eventuele fouten op. Uw code moet goed worden gebouwd.

Volgende stappen

Nu uw initialisatiecode is voltooid, bent u klaar voor de volgende quickstart, waar u de MIP-bestands-SDK's gaat ervaren.

Vertrouwelijkheidslabels vermelden

Quickstart: Initialisatie van clienttoepassingen (C#)

Vereisten

Een Visual Studio-oplossing en -project maken

Een verificatiedelegatie implementeren

De beheerde wrapper van de MIP SDK initialiseren

Een bestandsprofiel en -engine maken

Volgende stappen

Feedback

Feedback

Aanvullende resources

Quickstart: Initialisatie van clienttoepassingen (C#)

Vereisten

Een Visual Studio-oplossing en -project maken

Een verificatiedelegatie implementeren

Een gedelegeerde voor toestemming implementeren

De beheerde wrapper van de MIP SDK initialiseren

Een bestandsprofiel en -engine maken

Volgende stappen

Feedback

Feedback

Aanvullende resources