Szybki start: inicjowanie aplikacji klienckiej (C++)

W tym przewodniku typu szybki start pokazano, jak zaimplementować wzorzec inicjalizacji klienta używany przez zestaw MIP C++ SDK podczas działania.

Uwaga / Notatka

Kroki opisane w tym quickstart są wymagane dla każdej aplikacji klienckiej, która korzysta z MIP File SDK, MIP Policy SDK lub MIP Protection SDK. Chociaż w tym przewodniku szybki start pokazano użycie File SDK, ten sam wzorzec ma zastosowanie do klientów korzystających z Policy i Protection SDK. Ukończ pozostałe Quickstarty po kolei, ponieważ każdy z nich bazuje na poprzednim, a ten jest pierwszym.

Wymagania wstępne

Jeśli jeszcze tego nie zrobiono, upewnij się, że:

Wykonaj kroki opisane w artykule Konfiguracja i konfiguracja zestawu SDK usługi Microsoft Information Protection (MIP). Ten przewodnik Quickstart "Inicjowanie aplikacji klienckiej" opiera się na właściwym przygotowaniu i konfiguracji zestawu SDK.
Opcjonalnie:
- Przejrzyj obiekty profilu i silnika. Obiekty profilu i silnika są uniwersalnymi pojęciami wymaganymi przez klientów korzystających z zestawów SDK MIP do plików, zasad i ochrony.
- Zapoznaj się z pojęciami dotyczącymi uwierzytelniania , aby dowiedzieć się, jak uwierzytelnianie i zgoda są implementowane przez zestaw SDK i aplikację kliencą.
- Zapoznaj się z pojęciami obserwatora , aby dowiedzieć się więcej na temat obserwatorów i sposobu ich implementacji. Zestaw MIP SDK używa wzorca obserwatora do implementowania asynchronicznych powiadomień o zdarzeniach.

Tworzenie rozwiązania i projektu programu Visual Studio

Najpierw utworzymy i skonfigurujemy początkowe rozwiązanie i projekt w programie Visual Studio, na którym opierają się inne szybkie przewodniki.

Otwórz program Visual Studio 2022 lub nowszy, wybierz menu Plik , Nowy, Projekt. W oknie dialogowym Nowy projekt :
- W okienku po lewej stronie w obszarze Zainstalowaneinne języki wybierz pozycję Visual C++.
- W środkowym okienku wybierz pozycję Aplikacja konsolowa systemu Windows
- W dolnym okienku zaktualizuj odpowiednio nazwę projektu,lokalizację i nazwę rozwiązania zawierającego.
- Po zakończeniu kliknij przycisk OK w prawym dolnym rogu.
Dodaj pakiet NuGet dla zestawu MIP File SDK do projektu:
- W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy węzeł projektu (bezpośrednio w węźle u góry/rozwiązania), a następnie wybierz polecenie Zarządzaj pakietami NuGet...:
- Po otwarciu karty Menedżer pakietów NuGet w obszarze kart grupy edytora:
  - Wybierz przycisk Przeglądaj.
  - Wprowadź ciąg "Microsoft.InformationProtection" w polu wyszukiwania.
  - Wybierz pakiet "Microsoft.InformationProtection.File".
  - Kliknij "Zainstaluj", a następnie kliknij "OK", gdy zostanie wyświetlone okno dialogowe potwierdzenia podglądu zmian.

Zaimplementuj klasę obserwatora do monitorowania profilu pliku i obiektów silnika

Teraz utwórz podstawową implementację klasy obserwatora profilu plików, rozszerzając klasę zestawu SDK mip::FileProfile::Observer . Obserwator jest tworzony i używany później do monitorowania ładowania obiektu profilu pliku i dodawania obiektu silnika do profilu.

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

Po wygenerowaniu plików h i .cpp dla klasy oba pliki są otwierane na kartach Grupy edytora. Teraz zaktualizuj każdy plik, aby zaimplementować nową klasę obserwatora:

Zaktualizuj element "profile_observer.h", wybierając/usuwając wygenerowaną profile_observer klasę. Nie usuwaj dyrektyw preprocesora wygenerowanych w poprzednim kroku (#pragma, #include). Następnie skopiuj/wklej następujące źródło do pliku po istniejących dyrektywach preprocesora:

#include <memory>
#include "mip/file/file_profile.h"

class ProfileObserver final : public mip::FileProfile::Observer {
public:
     ProfileObserver() { }
     void OnLoadSuccess(const std::shared_ptr<mip::FileProfile>& profile, const std::shared_ptr<void>& context) override;
     void OnLoadFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
     void OnAddEngineSuccess(const std::shared_ptr<mip::FileEngine>& engine, const std::shared_ptr<void>& context) override;
     void OnAddEngineFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
};

Zaktualizuj "profile_observer.cpp", wybierając/usuwając wygenerowaną implementację klasy profile_observer. Nie usuwaj dyrektyw preprocesora wygenerowanych w poprzednim kroku (#pragma, #include). Następnie skopiuj/wklej następujące źródło do pliku po istniejących dyrektywach preprocesora:

#include <future>

using std::promise;
using std::shared_ptr;
using std::static_pointer_cast;
using mip::FileEngine;
using mip::FileProfile;

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

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

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

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

Opcjonalnie użyj F6 (Kompiluj rozwiązanie), aby uruchomić kompilowanie/łącze testowe rozwiązania, aby upewnić się, że kompilacja została pomyślnie skompilowana przed kontynuowaniem.

Implementowanie delegata uwierzytelniania

Zestaw MIP SDK implementuje uwierzytelnianie przy użyciu rozszerzalności klas, co zapewnia mechanizm udostępniania pracy uwierzytelniania z aplikacją kliencką. Klient musi uzyskać odpowiedni token dostępu OAuth2 i udostępnić zestaw MIP SDK w czasie wykonywania.

Teraz utwórz implementację dla delegata uwierzytelniania, rozszerzając klasę zestawu SDK mip::AuthDelegate i przesłaniając/implementując czystą funkcję wirtualną mip::AuthDelegate::AcquireOAuth2Token() . Delegat uwierzytelniania jest tworzony i używany później przez obiekty Profil pliku i Silnik plików.

Używając tej samej funkcji "Dodaj klasę" programu Visual Studio, której użyliśmy w kroku 1 poprzedniej sekcji, dodaj kolejną klasę do projektu. Tym razem wprowadź "auth_delegate" w polu Nazwa klasy.

Teraz zaktualizuj każdy plik, aby zaimplementować nową klasę delegata uwierzytelniania:

Zaktualizuj plik "auth_delegate.h", zastępując cały wygenerowany auth_delegate kod klasy przykładowym kodem. Nie usuwaj dyrektyw preprocesora wygenerowanych w poprzednim kroku (#pragma, #include):

#include <string>
#include "mip/common_types.h"

class AuthDelegateImpl final : public mip::AuthDelegate {
public:
     AuthDelegateImpl() = delete;        // Prevents default constructor

     AuthDelegateImpl(
       const std::string& appId)         // AppID for registered AAD app
       : mAppId(appId) {};

     bool AcquireOAuth2Token(            // Called by MIP SDK to get a token
       const mip::Identity& identity,    // Identity of the account to be authenticated, if known
       const OAuth2Challenge& challenge, // Authority (AAD tenant issuing token), and resource (API being accessed; "aud" claim).
       OAuth2Token& token) override;     // Token handed back to MIP SDK

private:
     std::string mAppId;
     std::string mToken;
     std::string mAuthority;
     std::string mResource;
};

Zaktualizuj element "auth_delegate.cpp", zastępując całą implementację wygenerowanej auth_delegate klasy następującym źródłem. Nie usuwaj dyrektyw preprocesora wygenerowanych w poprzednim kroku (#pragma, #include).
Ważne

Poniższy kod pozyskiwania tokenu nie jest odpowiedni do użytku produkcyjnego. W środowisku produkcyjnym musi to zostać zastąpione przez kod, który dynamicznie uzyskuje token przy użyciu:
- appId i URI odpowiedzi/przekierowania określone w rejestracji aplikacji Microsoft Entra (URI odpowiedzi/przekierowania musi być zgodny z rejestracją aplikacji)
- Adres URL autorytetu i zasobu, przekazany przez SDK w argumencie challenge, (adres URL zasobu musi być zgodny z API/uprawnieniami rejestracji aplikacji)
- Prawidłowe poświadczenia aplikacji/użytkownika, w których konto jest zgodne z argumentem identity przekazanym za pomocą SDK. Klienci OAuth2 "wbudowani" powinni prosić o poświadczenia użytkownika i używać przepływu "kodu autoryzacji". Protokół OAuth2 "konfidencjonalni klienci" mogą używać własnych bezpiecznych poświadczeń w przepływie "poświadczeń klienta" (takim jak usługa) lub żądać poświadczeń użytkownika przy użyciu przepływu "kodu autoryzacyjnego" (na przykład aplikacji internetowej).
Pozyskiwanie tokenów OAuth2 jest złożonym protokołem i zwykle odbywa się przy użyciu biblioteki. TokenAcquireOAuth2Token() jest wywoływany tylko przez zestaw MIP SDK, zgodnie z wymaganiami.
```
#include <iostream>
using std::cout;
using std::cin;
using std::string;

bool AuthDelegateImpl::AcquireOAuth2Token(const mip::Identity& identity, const OAuth2Challenge& challenge, OAuth2Token& token) 
{
     // Acquire a token manually, reuse previous token if same authority/resource. In production, replace with token acquisition code.
     string authority = challenge.GetAuthority();
     string resource = challenge.GetResource();
     if (mToken == "" || (authority != mAuthority || resource != mResource))
     {
         cout << "\nRun the PowerShell script to generate an access token using the following values, then copy/paste it below:\n";
         cout << "Set $authority to: " + authority + "\n";
         cout << "Set $resourceUrl to: " + resource + "\n";
         cout << "Sign in with user account: " + identity.GetEmail() + "\n";
         cout << "Enter access token: ";
         cin >> mToken;
         mAuthority = authority;
         mResource = resource;
         system("pause");
     }

     // Pass access token back to MIP SDK
     token.SetAccessToken(mToken);

     // True = successful token acquisition; False = failure
     return true;
}
```

Opcjonalnie użyj F6 (Kompiluj rozwiązanie), aby uruchomić kompilowanie/łącze testowe rozwiązania, aby upewnić się, że kompilacja została pomyślnie skompilowana przed kontynuowaniem.

Teraz utwórz implementację delegata zgody, rozszerzając klasę zestawu SDK mip::ConsentDelegate i przesłaniając/implementując czystą funkcję wirtualną mip::AuthDelegate::GetUserConsent() . Pełnomocnik zgody jest tworzony i używany później przez obiekty Profil plików i Silnik plików.

Korzystając z tej samej funkcji "Dodaj klasę" programu Visual Studio, której użyliśmy wcześniej, dodaj kolejną klasę do projektu. Tym razem wprowadź tekst "consent_delegate" w polu Nazwa klasy.

Teraz zaktualizuj każdy plik, aby zaimplementować nową klasę delegata zgody:

Zaktualizuj "consent_delegate.h", zastępując cały wygenerowany kod klasy consent_delegate następującym kodem źródłowym. Nie usuwaj dyrektyw preprocesora wygenerowanych w poprzednim kroku (#pragma, #include):

#include "mip/common_types.h"
#include <string>

class ConsentDelegateImpl final : public mip::ConsentDelegate {
public:
     ConsentDelegateImpl() = default;
     virtual mip::Consent GetUserConsent(const std::string& url) override;
};

Zaktualizuj plik "consent_delegate.cpp", zastępując całą implementację klasy consent_delegate wygenerowanej kodem następującym. Nie usuwaj dyrektyw preprocesora wygenerowanych w poprzednim kroku (#pragma, #include).

#include <iostream>
using mip::Consent;
using std::string;

Consent ConsentDelegateImpl::GetUserConsent(const string& url) 
{
     // Accept the consent to connect to the url
     std::cout << "SDK will connect to: " << url << std::endl;
     return Consent::AcceptAlways;
}

Opcjonalnie użyj F6 (Kompiluj rozwiązanie), aby uruchomić kompilowanie/łącze testowe rozwiązania, aby upewnić się, że kompilacja została pomyślnie skompilowana przed kontynuowaniem.

Tworzenie profilu pliku i silnika

Jak wspomniano, obiekty profilu i silnika są wymagane dla klientów zestawu SDK przy użyciu API MIP. Ukończ część kodu przewodnika szybkiego startu, dodając kod w celu utworzenia wystąpienia obiektów profilu i silnika:

W Eksploratorze rozwiązań otwórz plik .cpp w projekcie zawierający implementację main() metody . Domyślnie ma taką samą nazwę jak projekt zawierający go, który został określony podczas tworzenia projektu.
Usuń wygenerowaną implementację elementu main(). Nie usuwaj dyrektyw preprocesora generowanych przez program Visual Studio podczas tworzenia projektu (#pragma, #include). Dołącz następujący kod po wszelkich dyrektywach preprocesora:

#include "mip/mip_context.h"  
#include "auth_delegate.h"
#include "consent_delegate.h"
#include "profile_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::FileProfile;
using mip::FileEngine;

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

  // Create MipConfiguration object.
  std::shared_ptr<mip::MipConfiguration> mipConfiguration = std::make_shared<mip::MipConfiguration>(appInfo,    
				                                                                                               "mip_data", 
                                                                                      			         mip::LogLevel::Trace, 
                                                                                                     false);


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

  auto profileObserver = make_shared<ProfileObserver>();                     // 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
  FileProfile::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<FileProfile>>>();
  auto profileFuture = profilePromise->get_future();

  try
	  { 
		  mip::FileProfile::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
  FileEngine::Settings engineSettings(
                                  mip::Identity("<engine-account>"), // Engine identity (account used for authentication)
                                  authDelegateImpl,		       // Token acquisition implementation
				    "<engine-state>",                  // User-defined engine state
                                  "en-US");                          // Locale (default = en-US)
                                  
  // Set the engineId for caching. 
  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<FileEngine>>>();
  auto engineFuture = enginePromise->get_future();
  profile->AddEngineAsync(engineSettings, enginePromise);
  std::shared_ptr<FileEngine> 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.
  // handler = nullptr; // This will be used in later quick starts.
  engine = nullptr;
  profile = nullptr;   
  mMipContext->ShutDown();
  mMipContext = nullptr;

  return 0;
  }

Zastąp wszystkie wartości symboli zastępczych w kodzie źródłowym, który właśnie wkleiłeś, używając stałych napisów:

Placeholder	Wartość	Example
<identyfikator aplikacji>	Identyfikator aplikacji Entra firmy Microsoft (GUID) przypisany do aplikacji zarejestrowanej w kroku 2 artykułu "Konfiguracja i konfiguracja zestawu MIP SDK". Zastąp 2 wystąpienia.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<nazwa aplikacji>	Przyjazna nazwa aplikacji zdefiniowana przez użytkownika. Musi zawierać prawidłowe znaki ASCII (z wyłączeniem znaku ";") i najlepiej odpowiada nazwie aplikacji użytej w rejestracji firmy Microsoft Entra.	`"AppInitialization"`
<wersja aplikacji>	Informacje o wersji zdefiniowanej przez użytkownika dla aplikacji. Musi zawierać prawidłowe znaki ASCII (z wyłączeniem znaku ";").	`"1.1.0.0"`
<konto silnika>	Konto używane dla tożsamości silnika. Podczas uwierzytelniania przy użyciu konta użytkownika podczas pozyskiwania tokenu musi być zgodna z tą wartością.	`"user1@tenant.onmicrosoft.com"`
<stan silnika>	Stan zdefiniowany przez użytkownika do skojarzenia z silnikiem.	`"My App State"`

Teraz wykonaj ostateczną kompilację aplikacji i rozwiąż wszelkie błędy. Kod powinien zostać skompilować pomyślnie, ale nie zostanie jeszcze uruchomiony poprawnie, dopóki nie ukończysz następnego przewodnika Szybki start. Jeśli uruchomisz aplikację, zobaczysz dane wyjściowe podobne do poniższych. Nie będziesz mieć tokenu dostępu, dopóki nie ukończysz następnego Szybkiego Startu.

Dalsze kroki

Teraz, gdy kod inicjowania został ukończony, możesz przystąpić do następnego przewodnika Szybki start, w którym zaczniesz korzystać z zestawów SDK plików MIP.

Lista etykiet poufności

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-20