Быстрый старт: Инициализация клиентского приложения для SDK-библиотек защиты (C++)

В этом кратком руководстве показано, как реализовать шаблон инициализации клиента, который пакет SDK MIP C++ используется во время выполнения.

Примечание.

Для любого клиентского приложения, использующего пакеты SDK для защиты MIP, требуются действия, описанные в этом кратком руководстве. Выполните эти краткие руководства последовательно после инициализации приложения и реализации классов делегата проверки подлинности и делегата согласия.

Предпосылки

Если вы еще не сделали этого, обязательно выполните следующие действия.

Выполните действия, описанные в настройке и конфигурации пакета SDK Microsoft Information Protection (MIP). Это краткое руководство по инициализации клиентского приложения предполагает правильную установку и настройку SDK.
Необязательно:
- Просмотрите объекты профиля и обработчика. Объекты профиля и движка — это универсальные понятия, необходимые клиентам, использующим SDK для MIP-файлов, политик и защиты.
- Ознакомьтесь с концепциями проверки подлинности , чтобы узнать, как проверка подлинности и согласие реализованы пакетом SDK и клиентским приложением.
- Ознакомьтесь с концепциями наблюдателя , чтобы узнать больше о наблюдателях и о том, как они реализуются. Пакет SDK MIP использует шаблон наблюдателя для реализации асинхронных уведомлений о событиях.

Создание решения и проекта Visual Studio

Сначала создайте и настройте начальное решение и проект в Visual Studio, на основе которых строятся другие краткие руководства.

Откройте Visual Studio 2022 или более поздней версии, выберите меню "Файл ", "Создать", " Проект". В диалоговом окне "Новый проект ":
- В области слева в разделе "Установленные", "Другие языки" выберите Visual C++.
- В центральной области выберите консольное приложение Windows.
- В нижней области обновите имя проекта, расположение и соответствующее имя содержащего решения .
- По завершении нажмите кнопку "ОК " в правом нижнем углу.
Добавьте пакет NuGet для пакета SDK для защиты MIP в проект:
- В Обозреватель решений щелкните правой кнопкой мыши узел проекта непосредственно под верхним узлом решения, а затем выберите "Управление пакетами NuGet..."
- Когда откроется вкладка Диспетчер пакетов NuGet в области вкладок группы редакторов:
  - Выберите Обзор.
  - Введите Microsoft.InformationProtection в поле поиска.
  - Microsoft.InformationProtection.Protection Выберите пакет.
  - Нажмите кнопку "Установить", а затем нажмите кнопку "ОК ", когда появится диалоговое окно подтверждения изменений предварительной версии .

Реализуйте классы наблюдателей для мониторинга профиля защиты и объектов движка

Теперь создайте базовую реализацию класса-наблюдателя профиля защиты, расширив класс SDK mip::ProtectionProfile::Observer. SDK создает экземпляр объекта-наблюдателя и впоследствии использует его для отслеживания загрузки объекта профиля Protection и добавления объекта движка в профиль.

Добавьте в свой проект новый класс, который создаст для вас как файл заголовка (.h), так и файл реализации (.cpp):
- В Обозреватель решений снова щелкните узел проекта правой кнопкой мыши, выберите "Добавить" и выберите "Класс".
- В диалоговом окне добавления класса :
  - В поле "Имя класса" введите profile_observer. Обратите внимание, что Visual Studio автоматически заполняет поля файлов H и .cpp на основе введенного имени.
  - По завершении выберите ОК.

После создания файлов H и .cpp для класса Visual Studio открывает оба файла на вкладках "Группа редакторов". Теперь обновите каждый файл, чтобы реализовать новый класс наблюдателя:

Обновите profile_observer.h, выбрав и удалив созданный класс profile_observer. Не удаляйте директивы препроцессора, созданные предыдущим шагом (#pragma, #include). Затем скопируйте и вставьте следующий источник в файл после всех существующих директив препроцессора:

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

Обновите profile_observer.cpp, выбрав и удалив сгенерированную реализацию класса profile_observer. Не удаляйте директивы препроцессора, созданные предыдущим шагом (#pragma, #include). Затем скопируйте и вставьте следующий источник в файл после всех существующих директив препроцессора:

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

Повторите шаг 1, чтобы добавить в проект новый класс для наблюдателя engine_observerподсистемы защиты. Этот класс создает для вас как заголовочный файл (.h), так и файл реализации (.cpp).
После создания файлов H и .cpp для класса Visual Studio открывает оба файла на вкладках "Группа редакторов". Теперь обновите каждый файл, чтобы реализовать новый класс наблюдателя:
- Обновите engine_observer.h, выбрав и удалив созданный класс engine_observer. Не удаляйте директивы препроцессора, созданные предыдущим шагом (#pragma, #include). Затем скопируйте и вставьте следующий источник в файл после всех существующих директив препроцессора:
```
#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;

};
```
- Обновите engine_observer.cpp, выбрав и удалив сгенерированную реализацию класса engine_observer. Не удаляйте директивы препроцессора, созданные предыдущим шагом (#pragma, #include). Затем скопируйте и вставьте следующий источник в файл после всех существующих директив препроцессора:
```
#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<vector<shared_ptr<mip::TemplateDescriptor>>>*>(context.get());
    loadPromise->set_exception(Failure);
  };
```
При необходимости используйте ctrl+SHIFT+B (сборка решения) для запуска тестовой компиляции и ссылки решения, чтобы убедиться, что она успешно выполняет сборку, прежде чем продолжить.

Пакет SDK MIP реализует проверку подлинности через расширяемость класса, которая предоставляет механизм совместного использования проверки подлинности с клиентским приложением. Клиент должен получить подходящий маркер доступа OAuth2 и предоставить его пакету SDK MIP во время выполнения.

Создайте реализацию для делегата проверки подлинности, расширив класс пакета SDK mip::AuthDelegate и переопределяя или реализуя чистую виртуальную mip::AuthDelegate::AcquireOAuth2Token() функцию. Выполните действия, описанные в кратком руководстве по инициализации приложений пакета SDK для файлов. Объекты профиля защиты и механизма защиты создают экземпляр делегата аутентификации и позже используют его.

Теперь создайте реализацию для делегата согласия, расширив класс пакета SDK mip::ConsentDelegate и переопределяя или реализуя чистую виртуальную mip::AuthDelegate::GetUserConsent() функцию. Выполните действия, описанные в кратком руководстве по инициализации приложений пакета SDK для файлов. Объекты профиля защиты и ядра защиты создают экземпляр делегата согласия и впоследствии используют его.

Создайте профиль защиты и движок

Как упоминалось, для клиентов SDK, использующих API MIP, требуются объекты профиля и ядра. Завершите часть этого краткого руководства, связанную с написанием кода, добавив код для создания экземпляров объектов профиля и механизма:

В обозревателе решений откройте файл .cpp в проекте, который содержит реализацию main() метода. По умолчанию используется то же имя, что и проект, содержащий его, указанный во время создания проекта.
Удалите созданную реализацию main(). Не удаляйте директивы препроцессора, созданные Visual Studio во время создания проекта (#pragma, #include). Добавьте следующий код после любых директив препроцессора:

#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>(appInfo,
				                                                                                               "mip_data",
                                                                                      			         mip::LogLevel::Trace,
                                                                                                     false,
                                                                                                     mip::CacheStorageType::OnDisk);

  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;
  mMipContext->ShutDown();
  mMipContext = nullptr;

  return 0;
}

Замените все значения заполнителей в исходном коде, который вы вставили, используя строковые константы:

Замещающее поле	Ценность	Пример
<идентификатор приложения>	Идентификатор приложения Microsoft Entra (GUID), назначенный приложению, зарегистрированным на шаге 2 статьи по настройке и настройке пакета SDK MIP. Замените 2 вхождения.	`"00001111-aaaa-2222-bbbb-3333cccc4444"`
<имя приложения>	Пользовательское понятное имя для вашего приложения. Он должен содержать допустимые символы ASCII (за исключением "; ") и в идеале соответствует имени приложения, которое вы использовали в Microsoft Entra регистрации.	`"AppInitialization"`
<версия приложения>	Определяемые пользователем сведения о версии приложения. Он должен содержать допустимые символы ASCII (за исключением ";").	`"1.1.0.0"`
<учетная запись engine-account>	Учетная запись, используемая для идентификации движка. При проверке подлинности с учетной записью пользователя во время приобретения токена учетная запись должна соответствовать этому значению.	`"user1@tenant.onmicrosoft.com"`
<состояние подсистемы>	Определяемое пользователем состояние для связывания с подсистемой.	`"My App State"`

Теперь выполните окончательную сборку приложения и устраните все ошибки. Ваш код должен успешно собираться, но будет работать некорректно, пока вы не завершите следующее краткое руководство. При запуске приложения вы увидите выходные данные, аналогичные приведенным ниже. Приложение успешно создает профиль защиты и подсистему защиты, но не запускает модуль проверки подлинности и не имеет маркера доступа, пока не завершите следующее краткое руководство.
```
 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 . . .
```

Дальнейшие действия

Теперь, когда написание кода инициализации завершено, вы готовы перейти к следующему краткому руководству, в котором познакомитесь с MIP Protection SDK.

Список шаблонов защиты

Ознакомьтесь с примером MIP Protection SDK для C++ на GitHub.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-09-21