Hızlı Başlangıç: Koruma SDK'ları için istemci uygulaması başlatma (C++)

Makale
01/30/2024

Bu hızlı başlangıçta, çalışma zamanında MIP C++ SDK'sı tarafından kullanılan istemci başlatma deseninin nasıl uygulandığı gösterilmektedir.

Dekont

Bu hızlı başlangıçta özetlenen adımlar, MIP Koruması SDK'larını kullanan tüm istemci uygulamaları için gereklidir. Bu Hızlı Başlangıçlar, Uygulama Başlatma ve Kimlik Doğrulaması temsilcisi ve Onay temsilcisi sınıflarının uygulanmasından sonra seri olarak yapılmalıdır.

Ön koşullar

Henüz yapmadıysanız şunları yaptığınızdan emin olun:

Microsoft Information Protection (MIP) SDK kurulumu ve yapılandırmasındaki adımları tamamlayın. Bu "İstemci uygulaması başlatma" Hızlı Başlangıcı, doğru SDK kurulumuna ve yapılandırmasına dayanır.
Isteğe bağlı olarak:
- Profil ve altyapı nesnelerini gözden geçirin. Profil ve altyapı nesneleri, MIP Dosya/İlke/Koruma SDK'larını kullanan istemciler için gerekli olan evrensel kavramlardır.
- Kimlik doğrulaması ve onayın SDK ve istemci uygulaması tarafından nasıl uygulandığını öğrenmek için Kimlik doğrulama kavramlarını gözden geçirin.
- Gözlemciler ve bunların nasıl uygulandığı hakkında daha fazla bilgi edinmek için Gözlemci kavramlarını gözden geçirin. MIP SDK'sı zaman uyumsuz olay bildirimleri uygulamak için gözlemci desenini kullanır.

Visual Studio çözümü ve projesi oluşturma

İlk olarak, diğer Hızlı Başlangıçların derlendiği ilk Visual Studio çözümünü ve projesini oluşturup yapılandıracağız.

Visual Studio 2017'yi açın, Dosya menüsünü (Yeni, Proje) seçin. Yeni Proje iletişim kutusunda:
- Sol bölmedeki Yüklü, Diğer Diller'in altında Visual C++ öğesini seçin.
- Orta bölmede Windows Konsol Uygulaması'nı seçin
- Alt bölmede proje Adı, Konum ve içeren Çözüm adını uygun şekilde güncelleştirin.
- bitirdiğinizde, sağ alttaki Tamam düğmesine tıklayın.
MIP Koruması SDK'sı için Nuget paketini projenize ekleyin:
- Çözüm Gezgini proje düğümüne sağ tıklayın (doğrudan üst/çözüm düğümü altında) ve NuGet paketlerini yönet...:
- NuGet Paket Yöneticisi sekmesi Düzenleyici Grubu sekmeleri alanında açıldığında:
  - Göz At'ı seçin.
  - Arama kutusuna "Microsoft.InformationProtection" yazın.
  - "Microsoft.InformationProtection.Protection" paketini seçin.
  - Önizleme değişiklikleri onay iletişim kutusu görüntülendiğinde "Yükle" seçeneğine ve ardından "Tamam"a tıklayın.

Koruma profilini ve altyapı nesnelerini izlemek için gözlemci sınıfları uygulama

Şimdi SDK'nın mip::ProtectionProfile::Observer sınıfını genişleterek Koruma profili gözlemci sınıfı için temel bir uygulama oluşturun. Gözlemci örneği oluşturulur ve daha sonra Koruma profili nesnesinin yüklenmesini izlemek ve altyapı nesnesini profile eklemek için kullanılır.

Projenize, sizin için hem header/.h hem de application/.cpp dosyalarını oluşturan yeni bir sınıf ekleyin:
- Çözüm Gezgini proje düğümüne yeniden sağ tıklayın, Ekle'yi ve ardından Sınıf'ı seçin.
- Sınıf Ekle iletişim kutusunda:
  - Sınıf Adı alanına "profile_observer" girin. Hem .h dosyası hem de .cpp dosya alanlarının, girdiğiniz ada göre otomatik olarak doldurulduğunu fark edin.
  - İşiniz bittiğinde Tamam düğmesine tıklayın.

sınıfı için .h ve .cpp dosyaları üretildikten sonra, her iki dosya da Düzenleyici Grubu sekmelerinde açılır. Şimdi her dosyayı yeni gözlemci sınıfınızı uygulayacak şekilde güncelleştirin:

Oluşturulan profile_observer sınıfı seçerek/silerek "profile_observer.h" dosyasını güncelleştirin. Önceki adım (#pragma, #include) tarafından oluşturulan önişlemci yönergelerini kaldırmayın . Ardından, var olan önişlemci yönergelerinden sonra aşağıdaki kaynağı kopyalayıp dosyaya yapıştırın:

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

Oluşturulan profile_observer sınıf uygulamasını seçerek/silerek "profile_observer.cpp" dosyasını güncelleştirin. Önceki adım (#pragma, #include) tarafından oluşturulan önişlemci yönergelerini kaldırmayın . Ardından, var olan önişlemci yönergelerinden sonra aşağıdaki kaynağı kopyalayıp dosyaya yapıştırın:

#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. adımlarda aşağıdaki adımlar. Koruma altyapısı gözlemcisi için yeni bir sınıf ekleyin - projenize "engine_observer", bu da sizin için hem üst bilgi/.h hem de uygulama/.cpp dosyalarını oluşturur.

Oluşturulan engine_observer sınıfı seçerek/silerek "engine_observer.h" dosyasını güncelleştirin. Önceki adım (#pragma, #include) tarafından oluşturulan önişlemci yönergelerini kaldırmayın . Ardından, var olan önişlemci yönergelerinden sonra aşağıdaki kaynağı kopyalayıp dosyaya yapıştırın:

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

};

Oluşturulan engine_observer sınıf uygulamasını seçerek/silerek "engine_observer.cpp" dosyasını güncelleştirin. Önceki adım (#pragma, #include) tarafından oluşturulan önişlemci yönergelerini kaldırmayın . Ardından, var olan önişlemci yönergelerinden sonra aşağıdaki kaynağı kopyalayıp dosyaya yapıştırın:

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

İsteğe bağlı olarak, devam etmeden önce başarılı bir şekilde derlendiğinden emin olmak için çözümünüzün test derlemesini/bağlantısını çalıştırmak için Ctrl+Shift+B (Çözüm Derleme) tuşlarını kullanın.

MIP SDK' sı, istemci uygulamasıyla kimlik doğrulama çalışmasını paylaşmak için bir mekanizma sağlayan sınıf genişletilebilirliğini kullanarak kimlik doğrulamasını uygular. İstemcinin uygun bir OAuth2 erişim belirteci alması ve çalışma zamanında MIP SDK'sına sağlaması gerekir.

SDK'nın mip::AuthDelegate sınıfını genişleterek ve saf sanal işlevi geçersiz kılarak/uygulayarak mip::AuthDelegate::AcquireOAuth2Token() kimlik doğrulama temsilcisi için bir uygulama oluşturun. Dosya SDK'sı Uygulama Başlatma Hızlı Başlangıcı altında ayrıntılı adımları izleyin. Kimlik doğrulama temsilcisi örneği oluşturulur ve daha sonra Koruma profili ve Koruma altyapısı nesneleri tarafından kullanılır.

Şimdi SDK'nın mip::ConsentDelegate sınıfını genişleterek ve saf sanal işlevi geçersiz kılarak/uygulayarak mip::AuthDelegate::GetUserConsent() onay temsilcisi için bir uygulama oluşturun. Dosya SDK'sı Uygulama Başlatma Hızlı Başlangıcı altında ayrıntılı adımları izleyin. Onay temsilcisi örneği oluşturulur ve daha sonra Koruma profili ve Koruma altyapısı nesneleri tarafından kullanılır.

Koruma profili ve altyapısı oluşturma

Belirtildiği gibi, MIP API'lerini kullanan SDK istemcileri için profil ve altyapı nesneleri gereklidir. Profil ve altyapı nesnelerinin örneğini oluşturacak kod ekleyerek bu Hızlı Başlangıcın kodlama bölümünü tamamlayın:

Çözüm Gezgini, yönteminin uygulanmasını main() içeren projenizde .cpp dosyasını açın. Varsayılan olarak, proje oluşturma sırasında belirttiğiniz, onu içeren projeyle aynı ada sahiptir.
oluşturulan uygulamasını main()kaldırın. Proje oluşturma sırasında Visual Studio tarafından oluşturulan önişlemci yönergelerini kaldırmayın (#pragma, #include). Önişlemci yönergelerinden sonra aşağıdaki kodu ekleyin:

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

Dize sabitlerini kullanarak, yeni yapıştırdığınız kaynak koddaki tüm yer tutucu değerleri değiştirin:

Yer tutucu	Değer	Örnek
<uygulama kimliği>	"MIP SDK kurulumu ve yapılandırması"(setup-configure-mip.md) makalesinin 2. adımında kaydedilen uygulamaya atanan Microsoft Entra Uygulama Kimliği (GUID). 2 örneği değiştirin.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<uygulama adı>	Uygulamanız için kullanıcı tanımlı kolay ad. Geçerli ASCII karakterleri içermelidir (';' hariç) ve ideal olarak Microsoft Entra kaydınızda kullandığınız uygulama adıyla eşleşmelidir.	`"AppInitialization"`
<uygulama sürümü>	Uygulamanız için kullanıcı tanımlı sürüm bilgileri. Geçerli ASCII karakterleri içermelidir (';' hariç).	`"1.1.0.0"`
<altyapı hesabı>	Altyapının kimliği için kullanılan hesap. Belirteç alma sırasında bir kullanıcı hesabıyla kimlik doğrulaması yaptığınızda bu değerle eşleşmesi gerekir.	`"user1@tenant.onmicrosoft.com"`
<altyapı durumu>	Altyapıyla ilişkilendirilecek kullanıcı tanımlı durum.	`"My App State"`

Şimdi uygulamanın son derlemesini yapın ve hataları çözün. Kodunuz başarıyla derlenmelidir, ancak sonraki Hızlı Başlangıcı tamamlayana kadar henüz doğru çalışmayacaktır. Uygulamayı çalıştırırsanız aşağıdakine benzer bir çıkış görürsünüz. Uygulama Koruma profilini ve Koruma altyapısını başarılı bir şekilde oluşturur ancak kimlik doğrulama modülünü tetikleyemezdi ve bir sonraki Hızlı Başlangıcı tamamlayana kadar henüz erişim belirteciniz olmayacaktır.
```
 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 . . .
```

Sonraki Adımlar

Başlatma kodunuz tamamlandıktan sonra, MIP Koruması SDK'sını kullanmaya başlayacağınız sonraki hızlı başlangıç için hazırsınız.

Koruma şablonlarını listeleme

Hızlı Başlangıç: Koruma SDK'ları için istemci uygulaması başlatma (C++)

Ön koşullar

Visual Studio çözümü ve projesi oluşturma

Koruma profilini ve altyapı nesnelerini izlemek için gözlemci sınıfları uygulama

Koruma profili ve altyapısı oluşturma

Sonraki Adımlar

Geri Bildirim

Geri Bildirim

Ek kaynaklar

Hızlı Başlangıç: Koruma SDK'ları için istemci uygulaması başlatma (C++)

Ön koşullar

Visual Studio çözümü ve projesi oluşturma

Koruma profilini ve altyapı nesnelerini izlemek için gözlemci sınıfları uygulama

Kimlik doğrulama temsilcisi ve onay temsilcisi uygulama

Onay temsilcisi uygulama

Koruma profili ve altyapısı oluşturma

Sonraki Adımlar

Geri Bildirim

Geri Bildirim

Ek kaynaklar