Schnellstart: Initialisieren von Clientanwendungen für Protection SDKs (C++)
In diesem Schnellstart erfahren Sie, wie Sie das Muster für die Clientinitialisierung implementieren, das zur Laufzeit vom MIP SDK für C++ ausgeführt wird.
Notiz
Die in diesem Schnellstart beschriebenen Schritte müssen für sämtliche Clientanwendungen ausgeführt werden, die MIP Protection SDKs verwenden. Diese Schnellstarts sollten nach der Anwendungsinitialisierung und -implementierung von Authentifizierungsdelegat- und Einwilligungsdelegatklassen seriell durchgeführt werden.
Voraussetzungen
Falls noch nicht geschehen, sorgen Sie für Folgendes:
- Führen Sie die Schritte unter Microsoft Information Protection (MIP) SDK: Setup und Konfiguration aus. Dieser Schnellstart „Initialisieren von Clientanwendungen“ basiert auf der ordnungsgemäßen Einrichtung und Konfiguration des SDK.
- Optional:
- Informieren Sie sich über Profil- und Engine-Objekte. Bei Profil- und Engine-Objekten handelt es sich um universelle Konzepte, die von Clients benötigt werden, die das File SDK, das Policy SDK oder das Protection SDK von MIP verwenden.
- Informieren Sie sich über Authentifizierungskonzepte, um zu erfahren, wie die Authentifizierung und die Einwilligung vom SDK und der Clientanwendung implementiert werden.
- Informieren Sie sich über Observer-Konzepte, um mehr über Observer und ihre Implementierung zu erfahren. Das MIP SDK verwendet das Observer-Muster, um asynchrone Ereignisbenachrichtigungen zu implementieren.
Erstellen einer Visual Studio-Projektmappe und eines -Projekts
Zunächst erstellen und konfigurieren Sie die erste Projektmappe und das erste Projekt in Visual Studio. Sie bilden die Grundlage für die anderen Schnellstarts.
Öffnen Sie Visual Studio 2017, und wählen Sie das Menü Datei, anschließend Neu und dann Projekt aus. Geben Sie im Dialogfeld Neues Projekt Folgendes ein:
Wählen Sie im linken Bereich unter Installiert, Andere Sprachen die Option Visual C++ aus.
Wählen Sie im mittleren Bereich Windows-Konsolenanwendung aus
Aktualisieren Sie im unteren Bereich Name, Speicherort und den darin enthaltenen Projektmappennamen des Projekts.
Wenn Sie fertig sind, klicken Sie rechts unten auf die Schaltfläche OK.
Fügen Sie das NuGet-Paket für das MIP Protection SDK Ihrem Projekt hinzu:
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten direkt unter dem obersten Knoten bzw. dem Projektmappenknoten, und wählen Sie NuGet-Pakete verwalten… aus:
Gehen Sie wie folgt vor, wenn im Bereich „Editor-Gruppe“ die Registerkarte NuGet-Paket-Manager geöffnet wird:
- Wählen Sie Durchsuchen aus.
- Geben Sie „Microsoft.InformationProtection“ in das Suchfeld ein.
- Wählen Sie das Paket „Microsoft.InformationProtection.Protection“ aus.
- Klicken Sie auf „Installieren“ und anschließend auf „OK“, wenn das Bestätigungsdialogfeld Vorschau der Änderungen anzeigen angezeigt wird.
Implementieren von Observer-Klassen zum Überwachen des Protection-Profil- und -Engine-Objekte
Erstellen Sie nun eine grundlegende Implementierung für eine Observer-Klasse des Protection-Profils, indem Sie die mip::ProtectionProfile::Observer-Klasse des SDK erweitern. Der Observer wird später instanziiert und verwendet, um den Ladevorgang des Protection-Profilobjekts zu überwachen und dem Profil das Engine-Objekt hinzuzufügen.
Fügen Sie Ihrem Projekt eine neue Klasse hinzu, durch die die Dateien „header/.h“ und „implementation/.cpp“ für Sie generiert werden:
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste erneut auf den Projektknoten, und wählen Sie Hinzufügen und dann Klasse aus.
Gehen Sie im Dialogfeld Klasse hinzufügen folgendermaßen vor:
- Geben Sie im Feld Klassenname „profile_observer“ ein. Die Felder H-Datei und CPP-Datei werden anhand des eingegebenen Namens automatisch ausgefüllt.
- Wenn Sie fertig sind, klicken Sie auf die Schaltfläche OK.
Nach dem Generieren der H- und der CPP-Dateien für die Klasse werden beide Dateien auf Registerkarten in „Editor-Gruppe“ geöffnet. Aktualisieren Sie jetzt jede Datei, um Ihre neue Observer-Klasse zu implementieren:
Aktualisieren Sie „profile_observer.h“, indem Sie die generierte
profile_observer-Klasse auswählen/löschen. Entfernen Sie nicht die im vorherigen Schritt generierten Präprozessoranweisungen (#pragma, #include). Kopieren Sie dann die folgende Quelle, und fügen Sie sie in der Datei nach den vorhandenen Präprozessoranweisungen ein:#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; };Aktualisieren Sie „profile_observer.cpp“, indem Sie die Implementierung der generierten
profile_observer-Klasse auswählen/löschen. Entfernen Sie nicht die im vorherigen Schritt generierten Präprozessoranweisungen (#pragma, #include). Kopieren Sie dann die folgende Quelle, und fügen Sie sie in der Datei nach den vorhandenen Präprozessoranweisungen ein:#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); }
Befolgen Sie die Schritte unter 1. Fügen Sie Ihrem Projekt für den Protection-Engine-Observer (engine_observer) eine neue Klasse hinzu, durch die die Dateien „header/.h“ und „implementation/.cpp“ für Sie generiert werden.
Nach dem Generieren der H- und der CPP-Dateien für die Klasse werden beide Dateien auf Registerkarten in „Editor-Gruppe“ geöffnet. Aktualisieren Sie jetzt jede Datei, um Ihre neue Observer-Klasse zu implementieren:
Aktualisieren Sie „engine_observer.h“, indem Sie die generierte
engine_observer-Klasse auswählen/löschen. Entfernen Sie nicht die im vorherigen Schritt generierten Präprozessoranweisungen (#pragma, #include). Kopieren Sie dann die folgende Quelle, und fügen Sie sie in der Datei nach den vorhandenen Präprozessoranweisungen ein:#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; };Aktualisieren Sie „engine_observer.cpp“, indem Sie die Implementierung der generierten
engine_observer-Klasse auswählen/löschen. Entfernen Sie nicht die im vorherigen Schritt generierten Präprozessoranweisungen (#pragma, #include). Kopieren Sie dann die folgende Quelle, und fügen Sie sie in der Datei nach den vorhandenen Präprozessoranweisungen ein:#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); };
Verwenden Sie optional STRG+UMSCHALT+B (Projektmappe erstellen), um eine Testkompilierung/-verknüpfung Ihrer Projektmappe auszuführen und vor dem Fortfahren sicherzustellen, dass sie erfolgreich erstellt wird.
Implementieren eines Authentifizierungsdelegaten und eines Einwilligungsdelegaten
Das MIP SDK implementiert die Authentifizierung mithilfe der Klassenerweiterbarkeit, die einen Mechanismus zur Freigabe der Authentifizierung für die Clientanwendung bietet. Der Client muss ein geeignetes OAuth2-Zugriffstoken abrufen und dem MIP SDK zur Laufzeit bereitstellen.
Erstellen Sie eine Implementierung für einen Authentifizierungsdelegaten, indem Sie die mip::AuthDelegate-Klasse des SDK erweitern und die rein virtuelle mip::AuthDelegate::AcquireOAuth2Token()-Funktion überschreiben/implementieren. Führen Sie die unter Schnellstart: Initialisieren von File SDK-Anwendungen aufgeführten Schritte aus. Der Authentifizierungsdelegat wird später von den Protection-Profil- und Protection-Engine-Objekten instanziiert und verwendet.
Implementieren eines Einwilligungsdelegaten
Erstellen Sie nun eine Implementierung für einen Einwilligungsdelegaten, indem Sie die mip::ConsentDelegate-Klasse des SDK erweitern und die rein virtuelle mip::AuthDelegate::GetUserConsent()-Funktion überschreiben/implementieren. Führen Sie die unter Schnellstart: Initialisieren von File SDK-Anwendungen aufgeführten Schritte aus. Der Einwilligungsdelegat wird später von den Protection-Profil- und Protection-Engine-Objekten instanziiert und verwendet.
Erstellen eines Protection-Profils und einer Protection-Engine
Wie bereits erwähnt sind für SDK-Clients, die MIP-APIs verwenden, Profil- und Engine-Objekte erforderlich. Vervollständigen Sie den Codierungsabschnitt in diesem Schnellstart, indem Sie Code hinzufügen, um die Profil- und Engine-Objekte zu instanziieren:
Öffnen Sie im Projektmappen-Explorer die CPP-Datei in Ihrem Projekt, die die Implementierung der
main()-Methode enthält. Standardmäßig weist sie denselben Namen wie das Projekt auf, in dem sie enthalten ist. Diesen Namen haben Sie bei der Projekterstellung angegeben.Entfernen Sie die generierte Implementierung von
main(). Entfernen Sie keine Präprozessoranweisungen, die während der Projekterstellung von Visual Studio generiert wurden (#pragma, #include). Fügen Sie folgenden Code hinter den Präprozessoranweisungen an:
#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;
}
Ersetzen Sie alle Platzhalterwerte in dem Quellcode, den Sie gerade eingefügt haben, durch Zeichenfolgenkonstanten:
Platzhalter Wert Beispiel <application-id> Die ID der Azure AD-Anwendung (GUID) wird der Anwendung zugewiesen, die in Schritt 2 des Artikels „MIP SDK: Setup und Konfiguration“(setup-configure-mip.md) registriert wurde. Ersetzen Sie 2 Instanzen. "0edbblll-8773-44de-b87c-b8c6276d41eb"<application-name> Ein benutzerdefinierter Anzeigename für Ihre Anwendung. Dieser muss aus gültigen ASCII-Zeichen (außer „;“) bestehen und im Idealfall mit dem Anwendungsnamen übereinstimmen, den Sie während der Azure AD-Registrierung verwendet haben. "AppInitialization"<application-version> Die benutzerdefinierten Versionsinformationen für Ihre Anwendung. Sie muss aus gültigen ASCII-Zeichen (außer „;“) bestehen. "1.1.0.0"<engine-account> Das Konto, das für die Identität der Engine verwendet wird. Wenn Sie sich während des Tokenabrufs mit einem Benutzerkonto authentifizieren, muss es diesem Wert entsprechen. "user1@tenant.onmicrosoft.com"<engine-state> Der benutzerdefinierte Status, der der Engine zugeordnet werden soll. "My App State"Stellen Sie nun die Anwendung endgültig fertig, und beheben Sie etwaige Fehler. Ihr Code sollte erfolgreich erstellt werden. Er wird jedoch erst ordnungsgemäß ausgeführt, wenn Sie den nächsten Schnellstart abgeschlossen haben. Beim Ausführen der Anwendung wird Ihnen eine ähnliche Ausgabe wie die folgende angezeigt. Die Anwendung würde das Protection-Profil und die Protection-Engine zwar erfolgreich erstellen, aber das Authentifizierungsmodul wird nicht ausgelöst. Außerdem haben Sie noch kein Zugriffstoken, bis Sie den nächsten Schnellstart abgeschlossen haben.
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ächste Schritte
Da Ihr Initialisierungscode nun vollständig ist, können Sie mit dem nächsten Schnellstart fortfahren. Darin erfahren Sie mehr über das MIP Protection SDK.