Snabbstart: Klientprograminitiering för Skydds-SDK:er (C++)

Artikel
01/30/2024

Den här snabbstarten visar hur du implementerar mönstret för klientinitiering som används av MIP C++ SDK vid körning.

Kommentar

De steg som beskrivs i den här snabbstarten krävs för alla klientprogram som använder MIP Protection SDK:er. Dessa snabbstarter bör utföras seriellt efter programinitiering och implementering av autentiseringsdelegat- och medgivandedelegatklasser.

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.
- Läs Observer-begrepp för att lära dig mer om observatörer och hur de implementeras. MIP SDK använder övervakningsmönstret för att implementera asynkrona händelsemeddelanden.

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 2017, välj menyn Arkiv , Nytt, Projekt. I dialogrutan Nytt projekt:
- I den vänstra rutan, under Installerat, Andra språk, väljer du Visual C++.
- I mittenfönstret väljer du Windows-konsolprogram
- 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 Protection 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.Protection".
  - Klicka på "Installera" och sedan på "OK" när bekräftelsedialogrutan Förhandsgranskningsändringar visas.

Implementera övervakningsklasser för att övervaka skyddsprofilen och motorobjekten

Skapa nu en grundläggande implementering för en skyddsprofilobservatörsklass genom att utöka SDK:ts mip::ProtectionProfile::Observer klass. Observatören instansieras och används senare för att övervaka inläsningen av skyddsprofilobjektet och lägga till motorobjektet i profilen.

Lägg till en ny klass i projektet, som genererar både huvud-/.h- och implementeringsfilerna/.cpp åt dig:
- I Solution Explorer högerklickar du på projektnoden igen, väljer Lägg till och väljer sedan Klass.
- I dialogrutan Lägg till klass:
  - I fältet Klassnamn anger du "profile_observer". Observera att både .h-filen och .cpp-filfälten fylls i automatiskt, baserat på det namn du anger.
  - När du är klar klickar du på ok-knappen .

När du har genererat .h- och .cpp-filerna för klassen öppnas båda filerna på flikarna Redigerargrupp. Uppdatera nu varje fil för att implementera din nya observatörsklass:

Uppdatera "profile_observer.h" genom att välja/ta bort den genererade profile_observer klassen. Ta inte bort de förprocessordirektiv som genererades av föregående steg (#pragma, #include). Kopiera/klistra sedan in följande källa i filen efter befintliga förprocessordirektiv:

#include <memory>
#include "mip/protection/protection_profile.h"
using std::exception_ptr;
using std::shared_ptr;


class ProtectionProfileObserver final : public mip::ProtectionProfile::Observer {
public:
     ProtectionProfileObserver() { }
     void OnLoadSuccess(const std::shared_ptr<mip::ProtectionProfile>& profile, const std::shared_ptr<void>& context) override;
     void OnLoadFailure(const std::exception_ptr& Failure, const std::shared_ptr<void>& context) override;
     void OnAddEngineSuccess(const std::shared_ptr<mip::ProtectionEngine>& engine, const std::shared_ptr<void>& context) override;
     void OnAddEngineFailure(const std::exception_ptr& Failure, const std::shared_ptr<void>& context) override;
};

Uppdatera "profile_observer.cpp" genom att välja/ta bort den genererade profile_observer klassimplementeringen. Ta inte bort de förprocessordirektiv som genererades av föregående steg (#pragma, #include). Kopiera/klistra sedan in följande källa i filen efter befintliga förprocessordirektiv:

#include <future>

using std::promise;
using std::shared_ptr;
using std::static_pointer_cast;
using mip::ProtectionEngine;
using mip::ProtectionProfile;

void ProtectionProfileObserver::OnLoadSuccess(const shared_ptr<ProtectionProfile>& profile, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<ProtectionProfile>>>(context);
     promise->set_value(profile);
}

void ProtectionProfileObserver::OnLoadFailure(const std::exception_ptr& error, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<ProtectionProfile>>>(context);
     promise->set_exception(error);
}

void ProtectionProfileObserver::OnAddEngineSuccess(const shared_ptr<ProtectionEngine>& engine, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<ProtectionEngine>>>(context);
     promise->set_value(engine);
}

void ProtectionProfileObserver::OnAddEngineFailure(const std::exception_ptr& error, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<ProtectionEngine>>>(context);
     promise->set_exception(error);
}

Följande steg i 1. lägg till en ny klass för skyddsmotorns övervakare – "engine_observer" i projektet, vilket genererar både huvud-/.h- och implementerings-/.cpp-filer åt dig.

När du har genererat .h- och .cpp-filerna för klassen öppnas båda filerna på flikarna Redigerargrupp. Uppdatera nu varje fil för att implementera din nya observatörsklass:

Uppdatera "engine_observer.h" genom att välja/ta bort den genererade engine_observer klassen. Ta inte bort de förprocessordirektiv som genererades av föregående steg (#pragma, #include). Kopiera/klistra sedan in följande källa i filen efter befintliga förprocessordirektiv:

#include <memory>
#include "mip/protection/protection_engine.h"
using std::vector;
using std::exception_ptr;
using std::shared_ptr;

class ProtectionEngineObserver final : public mip::ProtectionEngine::Observer {
  public:
  ProtectionEngineObserver() {}
  void OnGetTemplatesSuccess(const vector<std::shared_ptr<mip::TemplateDescriptor>>& templateDescriptors, const shared_ptr<void>& context) override;
  void OnGetTemplatesFailure(const exception_ptr& Failure, const shared_ptr<void>& context) override;

};

Uppdatera "engine_observer.cpp" genom att välja/ta bort den genererade engine_observer klassimplementeringen. Ta inte bort de förprocessordirektiv som genererades av föregående steg (#pragma, #include). Kopiera/klistra sedan in följande källa i filen efter befintliga förprocessordirektiv:

#include "mip/protection/protection_profile.h"
#include "engine_observer.h"

using std::promise;
void ProtectionEngineObserver::OnGetTemplatesSuccess(const vector<shared_ptr<mip::TemplateDescriptor>>& templateDescriptors,const shared_ptr<void>& context) {
    auto loadPromise = static_cast<promise<vector<shared_ptr<mip::TemplateDescriptor>>>*>(context.get());
    loadPromise->set_value(templateDescriptors);
  };

  void ProtectionEngineObserver::OnGetTemplatesFailure(const exception_ptr& Failure, const shared_ptr<void>& context) {
    auto loadPromise = static_cast<promise<shared_ptr<mip::ProtectionProfile>>*>(context.get());
    loadPromise->set_exception(Failure);
  };

Du kan också använda Ctrl+Skift+B (bygglösning) för att köra en testkompilering/länk för din lösning för att se till att den skapas korrekt innan du fortsätter.

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 en implementering för en autentiseringsdelegat genom att utöka SDK:ts mip::AuthDelegate klass och åsidosätta/implementera den mip::AuthDelegate::AcquireOAuth2Token() rena virtuella funktionen. Följ stegen som beskrivs under Snabbstart för fil-SDK-programinitiering. Autentiseringsdelegaten instansieras och används senare av objekten Skyddsprofil och Skyddsmotor.

Skapa nu en implementering för ett medgivandedelegat genom att utöka SDK:ts mip::ConsentDelegate klass och åsidosätta/implementera den mip::AuthDelegate::GetUserConsent() rena virtuella funktionen. Följ stegen som beskrivs under Snabbstart för fil-SDK-programinitiering. Medgivandedelegaten instansieras och används senare av objekten Skyddsprofil och Skyddsmotor.

Skapa en skyddsprofil 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 instansiera profil- och motorobjekten:

Öppna .cpp-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(). Ta inte bort förprocessordirektiv som genereras av Visual Studio när projektet skapas (#pragma, #include). Lägg till följande kod efter eventuella förprocessordirektiv:

#include "mip/mip_init.h"
#include "mip/mip_context.h"  
#include "auth_delegate.h"
#include "consent_delegate.h"
#include "profile_observer.h"
#include"engine_observer.h"

using std::promise;
using std::future;
using std::make_shared;
using std::shared_ptr;
using std::string;
using std::cout;
using mip::ApplicationInfo;
using mip::ProtectionProfile;
using mip::ProtectionEngine;

int main(){

  // Construct/initialize objects required by the application's profile object
  // ApplicationInfo object (App ID, name, version)
  ApplicationInfo appInfo{"<application-id>",                    
                          "<application-name>",
                          "<application-version>"};

  std::shared_ptr<mip::MipConfiguration> mipConfiguration = std::make_shared<mip::MipConfiguration>(mAppInfo,
				                                                                                               "mip_data",
                                                                                      			         mip::LogLevel::Trace,
                                                                                                     false);

  std::shared_ptr<mip::MipContext> mMipContext = mip::MipContext::Create(mipConfiguration);

  auto profileObserver = make_shared<ProtectionProfileObserver>(); // Observer object
  auto authDelegateImpl = make_shared<AuthDelegateImpl>("<application-id>"); // Authentication delegate object (App ID)
  auto consentDelegateImpl = make_shared<ConsentDelegateImpl>(); // Consent delegate object

  // Construct/initialize profile object
  ProtectionProfile::Settings profileSettings(
    mMipContext,
    mip::CacheStorageType::OnDisk,      
    consentDelegateImpl,
    profileObserver);

  // Set up promise/future connection for async profile operations; load profile asynchronously
  auto profilePromise = make_shared<promise<shared_ptr<ProtectionProfile>>>();
  auto profileFuture = profilePromise->get_future();
  try
  {
    mip::ProtectionProfile::LoadAsync(profileSettings, profilePromise);
  }
  catch (const std::exception& e)
  {
    cout << "An exception occurred... are the Settings and ApplicationInfo objects populated correctly?\n\n"
          << e.what() << "'\n";
    system("pause");
    return 1;
  }

  auto profile = profileFuture.get();

  // Construct/initialize engine object
  ProtectionEngine::Settings engineSettings(       
     mip::Identity("<engine-account>"),         // Engine identity (account used for authentication)
     authDelegateImpl,                          // Reference to mip::AuthDelegate implementation
     "",                                        // ClientData field
     "en-US");                                  // Locale (default = en-US)

  // Set the engineId so it can be cached and reused. 
  engineSettings.SetEngineId("<engine-account>");

  // Set up promise/future connection for async engine operations; add engine to profile asynchronously
  auto enginePromise = make_shared<promise<shared_ptr<ProtectionEngine>>>();
  auto engineFuture = enginePromise->get_future();
  profile->AddEngineAsync(engineSettings, enginePromise);
  std::shared_ptr<ProtectionEngine> engine;

  try
  {
    engine = engineFuture.get();
  }
  catch (const std::exception& e)
  {
    cout << "An exception occurred... is the access token incorrect/expired?\n\n"
         << e.what() << "'\n";
    system("pause");
    return 1;
  }

  // Application shutdown. Null out profile and engine, call ReleaseAllResources();
  // Application may crash at shutdown if resources aren't properly released.
  engine = nullptr;
  profile = nullptr;
  mipContext.Shutdown();
  mipContext = nullptr;

  return 0;
}

Ersätt alla platshållarvärden i källkoden som du precis klistrade in med hjälp av strängkonstanter:

Platshållare	Värde	Exempel
<application-id>	Microsoft Entra-program-ID (GUID) som tilldelats programmet som registrerats i steg 2 i artikeln "MIP SDK setup and configuration"(setup-configure-mip.md). Ersätt 2 instanser.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<programnamn>	Ett användardefinierat eget namn för ditt program. Måste innehålla giltiga ASCII-tecken (exklusive ';') och matchar helst det programnamn som du använde i din Microsoft Entra-registrering.	`"AppInitialization"`
<programversion>	Användardefinierad versionsinformation för ditt program. Måste innehålla giltiga ASCII-tecken (exklusive ';').	`"1.1.0.0"`
<engine-account>	Det konto som används för motorns identitet. När du autentiserar med ett användarkonto under tokenförvärvet måste det matcha det här värdet.	`"user1@tenant.onmicrosoft.com"`
<motortillstånd>	Användardefinierat tillstånd som ska associeras med motorn.	`"My App State"`

Gör nu en slutlig version av programmet och lös eventuella fel. Koden bör byggas korrekt, men den kommer inte att köras korrekt förrän du har slutfört nästa snabbstart. Om du kör programmet visas utdata som liknar följande. Programmet skulle konstruera skyddsprofilen och skyddsmotorn korrekt men skulle inte ha utlöst autentiseringsmodulen och du kommer inte att ha någon åtkomsttoken ännu förrän du har slutfört nästa snabbstart.
```
 C:\MIP Sample Apps\ProtectionQS\Debug\ProtectionQS.exe (process 8252) exited with code 0.
 To automatically close the console when debugging stops, enable Tools->Options->Debugging->Automatically close the console when debugging stops.
 Press any key to close this window . . .
```

Nästa steg

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

Lista skyddsmallar

Dela via

Snabbstart: Klientprograminitiering för Skydds-SDK:er (C++)

Förutsättningar

Skapa en Visual Studio-lösning och ett projekt

Implementera övervakningsklasser för att övervaka skyddsprofilen och motorobjekten

Skapa en skyddsprofil och -motor

Nästa steg

Feedback

Ytterligare resurser

Dela via

Snabbstart: Klientprograminitiering för Skydds-SDK:er (C++)

Förutsättningar

Skapa en Visual Studio-lösning och ett projekt

Implementera övervakningsklasser för att övervaka skyddsprofilen och motorobjekten

Implementera en autentiseringsdelegat och ett medgivandedelegat

Implementera en medgivandedelegat

Skapa en skyddsprofil och -motor

Nästa steg

Feedback

Ytterligare resurser