Início Rápido: Inicialização do aplicativo cliente para SDKs de Proteção (C++)

Este início rápido mostra como implementar o padrão de inicialização do cliente que o SDK do C++ da MIP usa em runtime.

Observação

Qualquer aplicativo cliente que use os SDKs de Proteção do MIP requer seguir as etapas deste guia de início rápido. Conclua estes guias de início rápido em sequência após a inicialização do aplicativo e a implementação das classes de delegado de autenticação e de consentimento.

Pré-requisitos

Caso ainda não tenha feito isso, certifique-se de:

Conclua as etapas na configuração e configuração do SDK da Proteção de Informações da Microsoft (MIP). Este início rápido de "inicialização de aplicativo cliente" depende da configuração e da configuração adequadas do SDK.
Opcionalmente:
- Examine o perfil e os objetos do mecanismo. Os objetos de perfil e motor são conceitos universais, necessários para clientes que usam os SDKs de Arquivo/Política/Proteção da MIP.
- Examine os conceitos de Autenticação para saber como a autenticação e o consentimento são implementados pelo SDK e pelo aplicativo cliente.
- Examine os conceitos do Observer para saber mais sobre observadores e como eles são implementados. O SDK do MIP usa o padrão de observador para implementar notificações de evento assíncronas.

Criar uma solução e um projeto do Visual Studio

Primeiro, crie e configure a solução e o projeto de Visual Studio iniciais nos quais os outros inícios rápidos se baseiam.

Abra o Visual Studio 2022 ou posterior, selecione o menu Arquivo , Novo, Projeto. Na caixa de diálogo Novo Projeto :
- No painel esquerdo, em Instalado, Outros Idiomas, selecione Visual C++.
- No painel central, selecione Aplicativo de Console do Windows.
- No painel inferior, atualize o nome do projeto, o local e o nome da solução que contém adequadamente.
- Quando terminar, selecione OK no canto inferior direito.
Adicione o pacote NuGet para o SDK da Proteção MIP ao seu projeto:
- Em Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto diretamente no nó superior da solução e selecione Gerenciar pacotes NuGet...:
- Quando a guia Gerenciador de Pacotes NuGet é aberta na área de guias Grupo do Editor:
  - Selecione Procurar.
  - Digite Microsoft.InformationProtection na caixa de pesquisa.
  - Selecione o Microsoft.InformationProtection.Protection pacote.
  - Selecione Instalar e, em seguida, selecione OK quando a caixa de diálogo de confirmação de alterações de visualização for exibida.

Implementar classes observadoras para monitorar os objetos de proteção Perfil e Mecanismo

Agora, crie uma implementação básica para uma classe de observador de perfil de proteção estendendo a classe do mip::ProtectionProfile::Observer SDK. O SDK instancia o observador e o usa posteriormente para monitorar o carregamento do objeto de perfil de Protection e adicionar o objeto do mecanismo ao perfil.

Adicione uma nova classe ao projeto, que gera os arquivos de cabeçalho (.h) e implementação (.cpp) para você:
- Em Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto novamente, selecione Adicionar e selecione Classe.
- Na caixa de diálogo Adicionar Classe :
  - No campo Nome da Classe , insira profile_observer. Observe que Visual Studio preenche automaticamente os campos de arquivo .h e .cpp com base no nome inserido.
  - Ao terminar, selecione OK.

Depois de gerar os arquivos .h e .cpp para a classe, Visual Studio abre os dois arquivos nas guias Grupo do Editor. Agora atualize cada arquivo para implementar sua nova classe de observador:

Atualize profile_observer.h selecionando e excluindo a classe gerada profile_observer . Não remova as diretivas de pré-processador que a etapa anterior gerou (#pragma, #include). Em seguida, copie e cole a seguinte fonte no arquivo após quaisquer diretivas de pré-processador existentes:

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

Atualize profile_observer.cpp selecionando e excluindo a implementação de classe gerada profile_observer . Não remova as diretivas de pré-processador que a etapa anterior gerou (#pragma, #include). Em seguida, copie e cole a seguinte fonte no arquivo após quaisquer diretivas de pré-processador existentes:

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

Repita a etapa 1 para adicionar uma nova classe para o observador engine_observerdo mecanismo de proteção ao seu projeto. Essa classe gera os arquivos de cabeçalho (.h) e implementação (.cpp) para você.

Depois de gerar os arquivos .h e .cpp para a classe, Visual Studio abre os dois arquivos nas guias Grupo do Editor. Agora atualize cada arquivo para implementar sua nova classe de observador:

Atualize engine_observer.h selecionando e excluindo a classe gerada engine_observer . Não remova as diretivas de pré-processador que a etapa anterior gerou (#pragma, #include). Em seguida, copie e cole a seguinte fonte no arquivo após quaisquer diretivas de pré-processador existentes:

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

};

Atualize engine_observer.cpp selecionando e excluindo a implementação de classe gerada engine_observer . Não remova as diretivas de pré-processador que a etapa anterior gerou (#pragma, #include). Em seguida, copie e cole a seguinte fonte no arquivo após quaisquer diretivas de pré-processador existentes:

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

Opcionalmente, use Ctrl+Shift+B (Build Solution) para executar uma compilação de teste e um link de sua solução para verificar se ela é compilada com êxito antes de continuar.

O SDK do MIP implementa a autenticação por meio da extensibilidade de classe, que fornece um mecanismo para compartilhar o trabalho de autenticação com o aplicativo cliente. O cliente deve adquirir um token de acesso OAuth2 adequado e fornecê-lo ao SDK do MIP em runtime.

Crie uma implementação para um delegado de autenticação estendendo a classe do mip::AuthDelegate SDK e substituindo/implementando a mip::AuthDelegate::AcquireOAuth2Token() função virtual pura. Siga as etapas detalhadas em guia de início rápido para inicialização do aplicativo File SDK. O perfil de proteção e os objetos do mecanismo de proteção instanciam e usam o delegado de autenticação mais tarde.

Agora, crie uma implementação para um delegado de consentimento estendendo a classe do mip::ConsentDelegate SDK e substituindo/implementando a mip::AuthDelegate::GetUserConsent() função virtual pura. Siga as etapas detalhadas em guia de início rápido para inicialização do aplicativo File SDK. O perfil de proteção e os objetos do mecanismo de proteção instanciam e usam o delegado de consentimento mais tarde.

Criar um perfil e um mecanismo de Proteção

Como mencionado, os clientes do SDK que usam APIs de MIP exigem objetos de perfil e de mecanismo. Conclua a parte de codificação deste início rápido adicionando código para instanciar o perfil e os objetos do mecanismo:

No Gerenciador de Soluções, abra o arquivo .cpp em seu projeto que contém a implementação do main() método. Ele usa como padrão o mesmo nome do projeto que o contém, que você especificou durante a criação do projeto.
Remova a implementação gerada de main(). Não remova as diretivas de pré-processador geradas pelo Visual Studio durante a criação do projeto (#pragma, #include). Acrescente o seguinte código após quaisquer diretivas de pré-processador:

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

Substitua todos os valores de marcador de posição no código-fonte que você colou usando constantes de string:

Espaço reservado	Valor	Exemplo
<application-id>	O GUID (ID do Aplicativo Microsoft Entra) atribuído ao aplicativo que você registrou na etapa nº 2 do artigo de configuração e configuração do SDK do MIP. Substitua duas instâncias.	`"00001111-aaaa-2222-bbbb-3333cccc4444"`
<nome do aplicativo>	Um nome amigável definido pelo usuário para seu aplicativo. Ele deve conter caracteres ASCII válidos (excluindo '; ') e, idealmente, corresponde ao nome do aplicativo usado em seu registro de Microsoft Entra.	`"AppInitialization"`
<versão do aplicativo>	Informações de versão definidas pelo usuário para seu aplicativo. Ele deve conter caracteres ASCII válidos (excluindo ';').	`"1.1.0.0"`
<engine-account>	Conta usada para a identidade do mecanismo. Quando você se autentica com uma conta de usuário durante a aquisição do token, ele deve corresponder a esse valor.	`"user1@tenant.onmicrosoft.com"`
<estado do mecanismo>	Estado definido pelo usuário a ser associado ao mecanismo.	`"My App State"`

Agora, faça um build final do aplicativo e resolva quaisquer erros. Seu código deve ser compilado com êxito, mas não é executado corretamente até que você conclua o próximo início rápido. Se você executar o aplicativo, verá uma saída semelhante à seguinte. O aplicativo constrói o perfil de proteção e o mecanismo de proteção com êxito, mas ele não aciona o módulo de autenticação e você não tem um token de acesso até concluir o próximo início rápido.
```
 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 . . .
```

Próximas Etapas

Agora que o código de inicialização está concluído, você está pronto para o próximo início rápido, no qual você começa a experimentar o SDK de Proteção MIP.

Listar modelos de proteção

Explore o exemplo em C++ do SDK do MIP Protection no GitHub.

Comentários

Esta página foi útil?

Last updated on 2026-09-21