Démarrage rapide : Initialisation de l’application cliente pour les sdk Protection (C++)

Ce guide de démarrage rapide vous montre comment implémenter le modèle d’initialisation du client, utilisé par le SDK C++ MIP au moment de l’exécution.

Note

Les étapes décrites dans ce guide de démarrage rapide sont requises pour toute application cliente qui utilise les kits SDK MIP Protection. Ces démarrages rapides doivent être effectués en série après l’initialisation de l’application et l’implémentation des classes délégués d’authentification et de consentement.

Prerequisites

Si ce n’est déjà fait, veillez à :

Effectuez les étapes de configuration et de configuration du Kit de développement logiciel (SDK) Microsoft Information Protection (MIP). Ce guide de démarrage rapide « Initialisation de l’application cliente » s’appuie sur la configuration et l’installation appropriées du Kit de développement logiciel (SDK).
Optionnellement:
- Passez en revue les objets profil et moteur. Les objets de profil et de moteur sont des concepts universels, requis par les clients qui utilisent les kits SDK MIP File/Policy/Protection.
- Passez en revue les concepts d’authentification pour savoir comment l’authentification et le consentement sont implémentés par le Kit de développement logiciel (SDK) et l’application cliente.
- Passez en revue les concepts de l’observateur pour en savoir plus sur les observateurs et comment ils sont implémentés. Le SDK MIP utilise le modèle d’observateur pour implémenter des notifications d’événements asynchrones.

Créer une solution et un projet Visual Studio

Tout d’abord, nous créons et configurons la solution et le projet Visual Studio initiaux, sur lesquels les autres démarrages rapides créent.

Ouvrez Visual Studio 2019 ou version ultérieure, sélectionnez le menu Fichier , Nouveau, Projet. Dans la boîte de dialogue Nouveau projet :
- Dans le volet gauche, sous Installé, Autres langues, sélectionnez Visual C++.
- Dans le volet central, sélectionnez Application console Windows
- Dans le volet inférieur, mettez à jour le nom du projet, l’emplacement et le nom de solution contenant en conséquence.
- Lorsque vous avez terminé, cliquez sur le bouton OK en bas à droite.
Ajoutez le package NuGet pour le Kit de développement logiciel (SDK) MIP Protection à votre projet :
- Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nœud du projet (directement sous le nœud supérieur/solution), puis sélectionnez Gérer les packages NuGet... :
- Lorsque l’onglet Gestionnaire de package NuGet s’ouvre dans la zone onglets Groupe d’éditeurs :
  - Sélectionnez Parcourir.
  - Entrez « Microsoft.InformationProtection » dans la zone de recherche.
  - Sélectionnez le package « Microsoft.InformationProtection.Protection ».
  - Cliquez sur « Installer », puis sur « OK » lorsque la boîte de dialogue de confirmation d’aperçu change s’affiche.

Implémenter des classes d’observateur pour surveiller le profil de protection et les objets moteur

Créez maintenant une implémentation de base pour une classe d’observateur de profil Protection, en étendant la classe du mip::ProtectionProfile::Observer SDK. L’observateur est instancié et utilisé ultérieurement pour surveiller le chargement de l’objet profil Protection et ajouter l’objet moteur au profil.

Ajoutez une nouvelle classe à votre projet, qui génère à la fois les fichiers d’en-tête/.h et d’implémentation/.cpp pour vous :
- Dans l’Explorateur de solutions, cliquez à nouveau avec le bouton droit sur le nœud du projet, sélectionnez Ajouter, puis sélectionnez Classe.
- Dans la boîte de dialogue Ajouter une classe :
  - Dans le champ Nom de la classe , entrez « profile_observer ». Notez que le fichier .h et les champs de fichier .cpp sont automatiquement renseignés en fonction du nom que vous entrez.
  - Lorsque vous avez terminé, cliquez sur le bouton OK .

Après avoir généré les fichiers .h et .cpp pour la classe, les deux fichiers sont ouverts dans les onglets groupe d’éditeurs. À présent, mettez à jour chaque fichier pour implémenter votre nouvelle classe d’observateur :

Mettez à jour « profile_observer.h », en sélectionnant/supprimant la classe générée profile_observer . Ne supprimez pas les directives de préprocesseur générées par l’étape précédente (#pragma, #include). Copiez/collez ensuite la source suivante dans le fichier, après toutes les directives de préprocesseur existantes :

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

Mettez à jour « profile_observer.cpp », en sélectionnant/supprimant l’implémentation de classe générée profile_observer . Ne supprimez pas les directives de préprocesseur générées par l’étape précédente (#pragma, #include). Copiez/collez ensuite la source suivante dans le fichier, après toutes les directives de préprocesseur existantes :

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

Étapes suivantes dans 1. ajoutez une nouvelle classe pour l’observateur du moteur de protection : « engine_observer » à votre projet, qui génère à la fois les fichiers d’en-tête/.h et d’implémentation/.cpp pour vous.

Mettez à jour « engine_observer.h », en sélectionnant/supprimant la classe générée engine_observer . Ne supprimez pas les directives de préprocesseur générées par l’étape précédente (#pragma, #include). Copiez/collez ensuite la source suivante dans le fichier, après toutes les directives de préprocesseur existantes :

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

};

Mettez à jour « engine_observer.cpp », en sélectionnant/supprimant l’implémentation de classe générée engine_observer . Ne supprimez pas les directives de préprocesseur générées par l’étape précédente (#pragma, #include). Copiez/collez ensuite la source suivante dans le fichier, après toutes les directives de préprocesseur existantes :

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

Si vous le souhaitez, utilisez Ctrl+Maj+B (Solution de génération) pour exécuter une compilation de test/lien de votre solution, pour vous assurer qu’elle s’exécute correctement avant de continuer.

Le SDK MIP implémente l’authentification à l’aide de l’extensibilité de classe, qui fournit un mécanisme permettant de partager l’authentification avec l’application cliente. Le client doit acquérir un jeton d’accès OAuth2 approprié et fournir au SDK MIP au moment de l’exécution.

Créez une implémentation pour un délégué d’authentification, en étendant la classe du Kit de mip::AuthDelegate développement logiciel (SDK) et en remplaçant/implémentant la mip::AuthDelegate::AcquireOAuth2Token() fonction virtuelle pure. Suivez les étapes détaillées dans le guide de démarrage rapide de l’initialisation de l’application du Kit de développement logiciel (SDK) de fichier. Le délégué d’authentification est instancié et utilisé ultérieurement par le profil de protection et les objets du moteur de protection.

À présent, créez une implémentation pour un délégué de consentement, en étendant la classe du Kit de mip::ConsentDelegate développement logiciel (SDK) et en remplaçant/implémentant la mip::AuthDelegate::GetUserConsent() fonction virtuelle pure. Suivez les étapes détaillées dans le guide de démarrage rapide de l’initialisation de l’application du Kit de développement logiciel (SDK) de fichier. Le délégué de consentement est instancié et utilisé ultérieurement par le profil de protection et les objets du moteur de protection.

Construire un profil et un moteur de protection

Comme mentionné, les objets de profil et de moteur sont requis pour les clients sdk utilisant des API MIP. Terminez la partie de codage de ce guide de démarrage rapide en ajoutant du code pour instancier les objets de profil et de moteur :

À partir de l’Explorateur de solutions, ouvrez le fichier .cpp dans votre projet qui contient l’implémentation de la main() méthode. Il a par défaut le même nom que le projet qui le contient, que vous avez spécifié lors de la création du projet.
Supprimez l’implémentation générée de main(). Ne supprimez pas les directives de préprocesseur générées par Visual Studio lors de la création du projet (#pragma, #include). Ajoutez le code suivant après toutes les directives de préprocesseur :

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

Remplacez toutes les valeurs d’espace réservé dans le code source dans lequel vous venez de coller, à l’aide de constantes de chaîne :

Placeholder	Valeur	Example
<id d’application>	L’ID d’application Microsoft Entra (GUID) affecté à l’application inscrite à l’étape 2 de l’article « Configuration et configuration du Kit de développement logiciel (SDK) MIP » (setup-configure-mip.md). Remplacez 2 instances.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<nom de l’application>	Nom convivial défini par l’utilisateur pour votre application. Doit contenir des caractères ASCII valides (à l’exception de « ; »), et correspond idéalement au nom de l’application que vous avez utilisé dans votre inscription Microsoft Entra.	`"AppInitialization"`
<version de l’application>	Informations de version définies par l’utilisateur pour votre application. Doit contenir des caractères ASCII valides (à l’exception de ' ;').	`"1.1.0.0"`
<engine-account>	Compte utilisé pour l’identité du moteur. Lorsque vous vous authentifiez auprès d’un compte d’utilisateur lors de l’acquisition de jetons, il doit correspondre à cette valeur.	`"user1@tenant.onmicrosoft.com"`
<état du moteur>	État défini par l’utilisateur à associer au moteur.	`"My App State"`

Effectuez maintenant une build finale de l’application et résolvez toutes les erreurs. Votre code doit être généré correctement, mais ne s’exécute pas encore correctement tant que vous n’avez pas terminé le prochain démarrage rapide. Si vous exécutez l’application, vous voyez une sortie similaire à ce qui suit. L’application construisait correctement le profil de protection et le moteur de protection, mais n’aurait pas déclenché le module d’authentification et vous n’aurez pas encore de jeton d’accès, tant que vous n’avez pas terminé le prochain démarrage rapide.
```
 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 . . .
```

Étapes suivantes

Maintenant que votre code d’initialisation est terminé, vous êtes prêt pour le prochain guide de démarrage rapide, où vous commencerez à découvrir le KIT SDK de protection MIP.

Répertorier les modèles de protection

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-08-19

Partager via