Szybki start: inicjowanie aplikacji klienckich dla zestawów SDK ochrony (C++)

Artykuł
11/27/2021
Czas czytania: 7 min

W tym przewodniku Szybki start pokazano, jak wdrożyć wzorzec inicjowania klienta używany przez zestaw SDK MIP C++ w czasie wykonywania.

Uwaga

Kroki opisane w tym przewodniku Szybki start są wymagane dla każdej aplikacji klienckiej, która korzysta z zestawów SDK ochrony MIP. Te szybkie starty należy wykonać szeregowo po zainicjowaniu aplikacji i wdrożeniu klas Pełnomocnik uwierzytelniania i Zgoda pełnomocnika.

Wymagania wstępne

Jeśli jeszcze tego nie zrobić, pamiętaj, aby:

Wykonaj czynności opisane w te Microsoft Information Protection (MIP) SDK konfiguracji. Ten przewodnik Szybki start "Inicjowanie aplikacji klienckich" korzysta z odpowiedniej konfiguracji i konfiguracji zestawu SDK.
Opcjonalnie:
- Przejrzyj obiekty profilów i aparatów. Obiekty profilu i aparatu to uniwersalne koncepcje wymagane przez klientów, którzy korzystają z zestawów SDK plików/zasad/ochrony miP.
- Zapoznaj się z pojęciami uwierzytelniania, aby dowiedzieć się, jak uwierzytelnianie i zgoda są zaimplementowane przez zestaw SDK i aplikację kliencną.
- Przejrzyj koncepcje konceptuu, aby dowiedzieć się więcej na temat obserwatorów i sposobu ich wdrożenia. Zestaw SDK MIP używa wzorca wzorców asynchronicznych powiadomień o zdarzeniach.

Tworzenie Visual Studio i projektu

Najpierw tworzymy i konfigurujemy początkowe Visual Studio rozwiązania i projektu, na podstawie którego są konstruowane inne szybkie starty.

Otwórz Visual Studio 2017, wybierz menu Plik,Nowy, Project. W oknie Project dialogowym Nowe:
- W okienku po lewej stronie w obszarze Zainstalowane, Inne językiwybierz Visual C++.
- W środkowym okienku wybierz pozycję Windows Konsoli
- W dolnym okienku zaktualizuj odpowiednio nazwę projektu,lokalizację i odpowiednio zawierającą nazwę rozwiązania.
- Po zakończeniu kliknij przycisk OK w prawym dolnym rogu.
Dodaj do projektu pakiet Nuget dla zestawu SDK ochrony przed zabezpieczeniami MIP:
- W Eksploratorze rozwiązańkliknij prawym przyciskiem myszy węzeł projektu (bezpośrednio poniżej węzła górnego/węzła rozwiązania) i wybierz pozycję Zarządzaj NuGet pakietami...:
- Gdy karta NuGet Menedżer pakietów zostanie otwarta w obszarze kart Grupy edytorów:
  - Wybierz pozycję Przeglądaj.
  - W polu wyszukiwania wprowadź "Microsoft.InformationProtection".
  - Zaznacz pakiet "Microsoft.InformationProtection.Protection".
  - Kliknij przycisk "Zainstaluj", a następnie kliknij przycisk "OK", gdy zostanie wyświetlone okno dialogowe potwierdzenia zmian w podglądzie.

Implementowanie klas ochrony w celu monitorowania obiektów profilu ochrony i aparatu

Teraz należy utworzyć podstawową implementację klasy profilu ochrony, rozszerzając klasę zestawu mip::ProtectionProfile::Observer SDK. Aby monitorować ładowanie obiektu profilu Ochrony i dodawać obiekt aparatu do profilu, należy utworzyć wystąpienia i korzystać z nich później.

Dodaj do projektu nową klasę, która wygeneruje dla Ciebie zarówno pliki nagłówka/.h, jak i implementacji/.cpp:
- W Eksploratorze rozwiązańkliknij ponownie prawym przyciskiem myszy węzeł projektu, wybierz pozycję Dodaj, a następnie wybierz pozycję Klasa.
- W oknie dialogowym Dodawanie zajęć:
  - W polu Nazwa zajęć wprowadź "profile_observer". Zwróć uwagę, że zarówno pola pliku h, jak i pola pliku cpp są automatycznie wypełniane na podstawie wprowadzeniu nazwy.
  - Po zakończeniu kliknij przycisk OK.

Po wygenerowaniu plików h i cpp dla zajęć oba pliki są otwierane na kartach Grupy Redaktora. Teraz zaktualizuj każdy plik, aby wdrożyć swoją nową klasę obserwatorów:

Zaktualizuj "profile_observer.h", zaznaczając/usuwając wygenerowaną profile_observer klasę. Nie usuwaj użytkowników przedprocesowych wygenerowanych w poprzednim kroku (na przykład #pragma, #include). Następnie skopiuj/wklej do pliku następujące źródło po jakiejkolwiek istniejącej zaraz przedprocesorowi.

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

Zaktualizuj "profile_observer.cpp", wybierając/usuwając wygenerowaną profile_observer implementację klasy. Nie usuwaj użytkowników przedprocesowych wygenerowanych w poprzednim kroku (na przykład #pragma, #include). Następnie skopiuj/wklej do pliku następujące źródło po jakiejkolwiek istniejącej zaraz przedprocesorowi.

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

Poniżej 1. dodaj do projektu nową klasę aparatu ochrony — "engine_observer", która generuje dla Ciebie zarówno pliki nagłówka/.h, jak i implementacji/.cpp.

Po wygenerowaniu plików h i cpp dla zajęć oba pliki są otwierane na kartach Grupy Redaktora. Teraz zaktualizuj każdy plik, aby wdrożyć swoją nową klasę obserwatorów:

Zaktualizuj "engine_observer.h", zaznaczając/usuwając wygenerowaną engine_observer klasę. Nie usuwaj użytkowników przedprocesowych wygenerowanych w poprzednim kroku (na przykład #pragma, #include). Następnie skopiuj/wklej do pliku następujące źródło po jakiejkolwiek istniejącej zaraz przedprocesorowi.

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

};

Zaktualizuj "engine_observer.cpp", wybierając/usuwając wygenerowaną engine_observer implementację klasy. Nie usuwaj użytkowników przedprocesowych wygenerowanych w poprzednim kroku (na przykład #pragma, #include). Następnie skopiuj/wklej do pliku następujące źródło po jakiejkolwiek istniejącej zaraz przedprocesorowi.

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

Opcjonalnie użyj klawiszy Ctrl+Shift+B(kompilacjarozwiązania), aby uruchomić testowe zestawienie/link do rozwiązania, aby upewnić się, że przed kontynuowaniem będzie ono pomyślnie tworzyć.

Zestaw SDK protokołu MIP implementuje uwierzytelnianie za pomocą rozszerzalności klasy, który udostępnia mechanizm udostępniania uwierzytelniania podczas pracy z aplikacją kliencową. Klient musi uzyskać odpowiedni token dostępu OAuth2 i podać zestaw SDK MIP w czasie wykonywania.

Utwórz implementację pełnomocnika uwierzytelniania, rozszerzając klasę zestawu SDK mip::AuthDelegate i zastępując/implementując funkcję mip::AuthDelegate::AcquireOAuth2Token() wyłącznie wirtualną. Postępuj zgodnie z instrukcjami w obszarze Inicjowanie inicjowania obsługizestawu SDK plików Szybki start. Pełnomocnik uwierzytelniania jest wy wystąpienia i używany później przez obiekty Profil ochrony i Aparat ochrony.

Teraz utwórz implementację pełnomocnika zgody, rozszerzając klasę zestawu SDK mip::ConsentDelegate i zastępując/implementując funkcję mip::AuthDelegate::GetUserConsent() wyłącznie wirtualną. Postępuj zgodnie z instrukcjami w obszarze Inicjowanie inicjowania obsługizestawu SDK plików Szybki start. Pełnomocnik zgody jest wystąpienia i używany później przez obiekty profil ochrony i aparat ochrony.

Konstruowanie profilu i aparatu ochrony

Jak wspomniano, obiekty profilu i aparatu są wymagane dla klientów zestawu SDK korzystających z interfejsów API miP. Ukończ kodowanie tej funkcji Szybki start, dodając kod w celu wystąpienia obiektów profilu i aparatu:

W Eksploratorze rozwiązańotwórz plik cpp w projekcie, który zawiera implementację metody. Domyślna nazwa jest taka sama jak nazwa projektu zawierającego projekt, która jest określona podczas tworzenia projektu.
Usuń wygenerowaną implementację main() programu . Nie usuwaj procesu wstępnego wygenerowanego przez Visual Studio podczas tworzenia projektu (na przykład #pragma, #include). Dołącz następujący kod po wszystkich przedprocesowych danych źródłowych:

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

Zamień wszystkie wartości zastępcze w właśnie wklejonym kodzie źródłowym, używając stałych ciągów:

Symbol zastępczy	Wartość	Przykład
<application-id>	Identyfikator aplikacji usługi Azure AD (GUID) przypisany do aplikacji zarejestrowanej w kroku 2 artykułu "Konfiguracja i konfiguracja zestawu SDK MIP" (setup-configure-mip.md). Zamień 2 wystąpienia.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<nazwa aplikacji>	Zdefiniowana przez użytkownika przyjazna nazwa aplikacji. Musi zawierać prawidłowe znaki ASCII (z wyjątkiem znaków ';') i najlepiej pasuje do nazwy aplikacji użytej podczas rejestracji w usłudze Azure AD.	`"AppInitialization"`
<application-version>	Informacje o wersji zdefiniowanej przez użytkownika dla aplikacji. Musi zawierać prawidłowe znaki ASCII (z wyjątkiem znaków ';').	`"1.1.0.0"`
<engine-account>	Konto używane na celu tożsamości aparatu. Uwierzytelnianie przy użyciu konta użytkownika podczas pozyskiwania tokenu musi być zgodne z tą wartością.	`"user1@tenant.onmicrosoft.com"`
<stan-aparat>	Stan zdefiniowany przez użytkownika, który ma zostać skojarzony z aparatem.	`"My App State"`

Teraz wykonaj ostateczną kompilację aplikacji i rozwiąż wszelkie błędy. Kod powinien zostać pomyślnie skompilowany, ale nie będzie działał poprawnie do momentu ukończenia następnego przewodnika Szybki start. Po uruchomieniu aplikacji zobaczysz dane wyjściowe podobne do poniższych. Aplikacja pomyślnie skonstruowała profil ochrony i aparat ochrony, ale moduł uwierzytelniania nie zostałby odpalony i nie masz jeszcze tokenu dostępu do momentu ukończenia następnego przewodnika Szybki start.
```
 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 . . .
```

Następne kroki

Teraz, gdy kod inicjowania został ukończony, możesz rozpocząć proces tworzenia zestawu SDK ochrony przed mip.

Szablony ochrony listy

Szybki start: inicjowanie aplikacji klienckich dla zestawów SDK ochrony (C++)

Oceń swoje doświadczenia

Wymagania wstępne

Tworzenie Visual Studio i projektu

Implementowanie klas ochrony w celu monitorowania obiektów profilu ochrony i aparatu

Implementowanie pełnomocnika uwierzytelniania i pełnomocnika zgody

Implementowanie pełnomocnika zgody

Konstruowanie profilu i aparatu ochrony

Następne kroki