Rövid útmutató: Ügyfélalkalmazás inicializálása Védelmi SDK-khoz (C++)

Cikk
01/30/2024

Ez a rövid útmutató bemutatja, hogyan implementálhatja az ügyfél inicializálási mintáját, amelyet a MIP C++ SDK használ futásidőben.

Megjegyzés:

Az ebben a rövid útmutatóban ismertetett lépések szükségesek a MIP Protection SDK-t használó ügyfélalkalmazásokhoz. Ezeket a rövid útmutatókat az alkalmazás inicializálása és a hitelesítési delegált és a jóváhagyás delegált osztályainak implementálása után kell elvégezni.

Előfeltételek

Ha még nem tette meg, ügyeljen a következőre:

Hajtsa végre a Microsoft Information Protection (MIP) SDK beállításának és konfigurálásának lépéseit. Ez az "ügyfélalkalmazás inicializálása" rövid útmutató az SDK megfelelő beállítására és konfigurálására támaszkodik.
Tetszés szerint:
- Profil- és motorobjektumok áttekintése. A profil- és motorobjektumok univerzális fogalmak, amelyeket a MIP-fájlokat/szabályzatokat/védelmi SDK-okat használó ügyfelek igényelnek.
- Tekintse át a hitelesítési fogalmakat , és ismerje meg, hogyan valósítja meg a hitelesítést és a hozzájárulást az SDK és az ügyfélalkalmazás.
- Tekintse át a megfigyelői fogalmakat , hogy többet tudjon meg a megfigyelőkről és azok implementálásáról. A MIP SDK a megfigyelői mintát használja az aszinkron eseményértesítések implementálásához.

Visual Studio-megoldás és projekt létrehozása

Először létrehozzuk és konfiguráljuk a Visual Studio kezdeti megoldását és projektét, amelyre a többi rövid útmutató épül.

Nyissa meg a Visual Studio 2017-et, válassza a Fájl menü Új, Projekt parancsát. Az Új projekt párbeszédpanelen:
- A bal oldali panelEn, a Telepített egyéb nyelvek területen válassza a Visual C++ lehetőséget.
- A középső panelen válassza a Windows Konzolalkalmazás lehetőséget
- Az alsó panelen ennek megfelelően frissítse a projekt nevét, helyét és az azt tartalmazó megoldásnevet .
- Ha végzett, kattintson az OK gombra a jobb alsó sarokban.
Adja hozzá a MiP Protection SDK Nuget-csomagját a projekthez:
- A Megoldáskezelő kattintson a jobb gombbal a projektcsomópontra (közvetlenül a felső/megoldáscsomópont alatt), és válassza a NuGet-csomagok kezelése...:
- Amikor megnyílik a NuGet Csomagkezelő lap a Szerkesztőcsoport lapfülek területén:
  - Válassza a Tallózás lehetőséget.
  - Írja be a "Microsoft.InformationProtection" kifejezést a keresőmezőbe.
  - Válassza a "Microsoft.InformationProtection.Protection" csomagot.
  - Kattintson a "Telepítés", majd az "OK" gombra, amikor megjelenik az Előzetes verzió módosításainak megerősítése párbeszédpanel.

Megfigyelőosztályok implementálása a Védelmi profil és a motorobjektumok figyeléséhez

Most hozzon létre egy alapszintű implementációt egy Védelmi profil megfigyelőosztályához az SDK osztályának mip::ProtectionProfile::Observer kibővítésével. A megfigyelő példányosítása és későbbi használata a Védelmi profil objektum betöltésének figyelésére és a motorobjektum profilhoz való hozzáadására szolgál.

Adjon hozzá egy új osztályt a projekthez, amely a fejléc/.h és a implementáció/.cpp fájlokat is létrehozza Önnek:
- A Megoldáskezelő kattintson ismét a jobb gombbal a projektcsomópontra, válassza a Hozzáadás, majd az Osztály lehetőséget.
- Az Osztály hozzáadása párbeszédpanelen:
  - Az Osztálynév mezőben adja meg a "profile_observer" értéket. Figyelje meg, hogy a .h fájl és a .cpp fájlmező is automatikusan ki lesz töltve a megadott név alapján.
  - Ha végzett, kattintson az OK gombra.

Az osztály .h és .cpp fájljainak létrehozása után mindkét fájl megnyílik a Szerkesztőcsoport lapon. Most frissítse az egyes fájlokat az új megfigyelői osztály implementálásához:

Frissítse a "profile_observer.h" értéket a létrehozott profile_observer osztály kiválasztásával/törlésével. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket. Ezután másolja/illessze be a következő forrást a fájlba a meglévő előfeldolgozási irányelvek után:

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

Frissítse a "profile_observer.cpp" fájlt a létrehozott profile_observer osztály implementációjának kiválasztásával/törlésével. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket. Ezután másolja/illessze be a következő forrást a fájlba a meglévő előfeldolgozási irányelvek után:

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

Az 1. lépés lépései. adjon hozzá egy új osztályt a Védelmi motor megfigyelőjéhez – "engine_observer" a projekthez, amely a fejléc/.h és a implementáció/.cpp fájlokat is létrehozza Önnek.

Az osztály .h és .cpp fájljainak létrehozása után mindkét fájl megnyílik a Szerkesztőcsoport lapon. Most frissítse az egyes fájlokat az új megfigyelői osztály implementálásához:

Frissítse a "engine_observer.h" értéket a létrehozott engine_observer osztály kiválasztásával/törlésével. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket. Ezután másolja/illessze be a következő forrást a fájlba a meglévő előfeldolgozási irányelvek után:

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

};

Frissítse a "engine_observer.cpp" fájlt a létrehozott engine_observer osztály implementációjának kiválasztásával/törlésével. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket. Ezután másolja/illessze be a következő forrást a fájlba a meglévő előfeldolgozási irányelvek után:

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

Ha szeretné, a Ctrl+Shift+B (Build Solution) billentyűkombinációval futtathatja a megoldás fordítását/csatolását, hogy a folytatás előtt meggyőződjön arról, hogy a buildelés sikeres.

A MIP SDK az osztály bővíthetőségével valósítja meg a hitelesítést, amely lehetővé teszi a hitelesítés megosztását az ügyfélalkalmazással. Az ügyfélnek be kell szereznie egy megfelelő OAuth2 hozzáférési jogkivonatot, és futásidőben meg kell adnia a MIP SDK-nak.

Hozzon létre egy implementációt egy hitelesítési delegált számára az SDK osztályának mip::AuthDelegate kibővítésével, valamint a mip::AuthDelegate::AcquireOAuth2Token() tiszta virtuális függvény felülbírálásával/implementálásával. Kövesse a Fájl SDK-alkalmazások inicializálásának rövid útmutatójában leírt lépéseket. A hitelesítési delegált példányosítása és használata később történik a Védelmi profil és a Védelmi motor objektumai által.

Most hozzon létre egy implementációt egy hozzájárulási delegált számára az SDK osztályának mip::ConsentDelegate kibővítésével, valamint a mip::AuthDelegate::GetUserConsent() tiszta virtuális függvény felülbírálásával/implementálásával. Kövesse a Fájl SDK-alkalmazások inicializálásának rövid útmutatójában leírt lépéseket. A hozzájárulási delegált példányosítása és használata később történik a Védelmi profil és a Védelmi motor objektumai által.

Védelmi profil és motor létrehozása

Ahogy említettük, profil- és motorobjektumok szükségesek a MIP API-kat használó SDK-ügyfelekhez. Töltse ki a rövid útmutató kódolási részét úgy, hogy kódot ad hozzá a profil és a motorobjektumok példányosításához:

A Megoldáskezelő nyissa meg a metódus implementálását tartalmazó .cpp fájlt a main() projektben. Alapértelmezés szerint ugyanaz a név lesz, mint a projektet tartalmazó projekt, amelyet a projekt létrehozásakor adott meg.
Távolítsa el a generált implementációt.main() Ne távolítsa el a Visual Studio által a projekt létrehozása során létrehozott preprocesszor-irányelveket (#pragma, #include). Az előfeldolgozási irányelvek után fűzze hozzá a következő kódot:

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

Cserélje le az imént beillesztett forráskód összes helyőrző értékét sztringállandók használatával:

Helyőrző	Value	Example
<alkalmazásazonosító>	A Microsoft Entra alkalmazásazonosítója (GUID) a "MIP SDK beállításáról és konfigurációjáról"(setup-configure-mip.md) szóló cikk 2. lépésében regisztrált alkalmazáshoz rendelve. Cserélje le a 2 példányt.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<alkalmazás neve>	Az alkalmazás felhasználó által definiált rövid neve. Érvényes ASCII-karaktereket kell tartalmaznia (a ";" kivételével), és ideális esetben megegyezik a Microsoft Entra-regisztrációban használt alkalmazásnévvel.	`"AppInitialization"`
<alkalmazásverzió>	Felhasználó által megadott verzióadatok az alkalmazáshoz. Érvényes ASCII-karaktereket kell tartalmaznia (a ";" kivételével).	`"1.1.0.0"`
<motorfiók>	A motor identitásához használt fiók. Ha felhasználói fiókkal hitelesít a jogkivonatok beszerzése során, annak meg kell egyeznie ezzel az értékkel.	`"user1@tenant.onmicrosoft.com"`
<motorállapot>	A motorhoz társítandó felhasználó által definiált állapot.	`"My App State"`

Most készítse el az alkalmazás végleges buildjét, és oldja meg a hibákat. A kódnak sikeresnek kell lennie, de a következő rövid útmutató befejezéséig még nem fog megfelelően futni. Az alkalmazás futtatásakor az alábbihoz hasonló kimenet jelenik meg. Az alkalmazás szívósan hozza létre a Védelmi profilt és a Védelmi motort, de nem aktiválta volna a hitelesítési modult, és még nem rendelkezik hozzáférési jogkivonattal, amíg be nem fejezi a következő rövid útmutatót.
```
 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 . . .
```

Következő lépések

Most, hogy elkészült az inicializálási kód, készen áll a következő rövid útmutatóra, ahol megkezdheti a MIP Protection SDK használatát.

Védelmi sablonok listázása

Rövid útmutató: Ügyfélalkalmazás inicializálása Védelmi SDK-khoz (C++)

Előfeltételek

Visual Studio-megoldás és projekt létrehozása

Megfigyelőosztályok implementálása a Védelmi profil és a motorobjektumok figyeléséhez

Védelmi profil és motor létrehozása

Következő lépések

Visszajelzés

Visszajelzés

További források

Rövid útmutató: Ügyfélalkalmazás inicializálása Védelmi SDK-khoz (C++)

Előfeltételek

Visual Studio-megoldás és projekt létrehozása

Megfigyelőosztályok implementálása a Védelmi profil és a motorobjektumok figyeléséhez

Hitelesítési delegált és hozzájárulási meghatalmazott implementálása

Hozzájárulási meghatalmazott implementálása

Védelmi profil és motor létrehozása

Következő lépések

Visszajelzés

Visszajelzés

További források