Mulai cepat: Inisialisasi aplikasi klien untuk SDK Perlindungan (C++)

Artikel
01/30/2024

Mulai cepat ini menunjukkan kepada Anda cara menerapkan pola inisialisasi klien, yang digunakan oleh MIP C++ SDK saat runtime.

Catatan

Langkah-langkah yang diuraikan dalam mulai cepat ini diperlukan untuk aplikasi klien apa pun yang menggunakan SDK Perlindungan MIP. Mulai Cepat ini harus dilakukan secara serial setelah Inisialisasi Aplikasi dan implementasi delegasi Autentikasi dan kelas delegasi Persetujuan.

Prasyarat

Jika Anda belum melakukannya, pastikan untuk:

Selesaikan langkah-langkah dalam penyiapan dan konfigurasi SDK Microsoft Information Protection (MIP). Mulai Cepat "Inisialisasi aplikasi klien" ini bergantung pada penyiapan dan konfigurasi SDK yang tepat.
Opsional:
- Tinjau Profil dan objek mesin. Objek profil dan mesin adalah konsep universal, yang diperlukan oleh klien yang menggunakan SDK File/Kebijakan/Perlindungan MIP.
- Tinjau konsep Autentikasi untuk mempelajari bagaimana autentikasi dan persetujuan diterapkan oleh SDK dan aplikasi klien.
- Tinjau konsep Observer untuk mempelajari lebih lanjut tentang pengamat, dan bagaimana penerapannya. MIP SDK menggunakan pola pengamat untuk mengimplementasikan pemberitahuan peristiwa asinkron.

Membuat solusi dan proyek Visual Studio

Pertama, kita membuat dan mengonfigurasi solusi dan proyek Visual Studio awal, di mana Mulai Cepat lainnya dibuat.

Buka Visual Studio 2017, pilih menu File , Baru, Proyek. Dalam dialog Proyek Baru:
- Di panel kiri, di bawah Terinstal, Bahasa Lain, pilih Visual C++.
- Di panel tengah, pilih Aplikasi Konsol Windows
- Di panel bawah, perbarui nama proyek, Lokasi, dan nama Solusi yang berisi yang sesuai.
- Setelah selesai, klik tombol OK di kanan bawah.
Tambahkan paket Nuget untuk SDK Perlindungan MIP ke proyek Anda:
- Di Penjelajah Solusi, klik kanan simpul proyek (langsung di bawah node atas/solusi), dan pilih Kelola paket NuGet...:
- Saat tab Pengelola Paket NuGet terbuka di area tab Grup Editor:
  - Pilih Telusur.
  - Masukkan "Microsoft.InformationProtection" di kotak pencarian.
  - Pilih paket "Microsoft.InformationProtection.Protection".
  - Klik "Instal", lalu klik "OK" saat dialog Konfirmasi perubahan pratinjau ditampilkan.

Menerapkan kelas pengamat untuk memantau profil Perlindungan dan objek mesin

Sekarang buat implementasi dasar untuk kelas pengamat profil Perlindungan, dengan memperluas kelas SDK mip::ProtectionProfile::Observer . Pengamat dibuat dan digunakan nanti, untuk memantau pemuatan objek profil Perlindungan, dan menambahkan objek mesin ke profil.

Tambahkan kelas baru ke proyek Anda, yang menghasilkan file header/.h dan implementasi/.cpp untuk Anda:
- Di Penjelajah Solusi, klik kanan simpul proyek lagi, pilih Tambahkan, lalu pilih Kelas.
- Pada dialog Tambahkan Kelas:
  - Di bidang Nama Kelas, masukkan "profile_observer". Perhatikan bahwa bidang file .h dan file .cpp diisi secara otomatis, berdasarkan nama yang Anda masukkan.
  - Setelah selesai, klik tombol OK .

Setelah membuat file .h dan .cpp untuk kelas , kedua file dibuka di tab Grup Editor. Sekarang perbarui setiap file untuk mengimplementasikan kelas pengamat baru Anda:

Perbarui "profile_observer.h", dengan memilih/menghapus kelas yang dihasilkan profile_observer . Jangan hapus arahan preproscessor yang dihasilkan oleh langkah sebelumnya (#pragma, #include). Kemudian salin/tempel sumber berikut ke dalam file, setelah direktif praprosesor yang ada:

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

Perbarui "profile_observer.cpp", dengan memilih/menghapus implementasi kelas yang dihasilkan profile_observer . Jangan hapus arahan preproscessor yang dihasilkan oleh langkah sebelumnya (#pragma, #include). Kemudian salin/tempel sumber berikut ke dalam file, setelah direktif praprosesor yang ada:

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

Mengikuti langkah-langkah dalam 1. tambahkan kelas baru untuk pengamat mesin Perlindungan - "engine_observer" ke proyek Anda, yang menghasilkan file header/.h dan implementasi/.cpp untuk Anda.

Setelah membuat file .h dan .cpp untuk kelas , kedua file dibuka di tab Grup Editor. Sekarang perbarui setiap file untuk mengimplementasikan kelas pengamat baru Anda:

Perbarui "engine_observer.h", dengan memilih/menghapus kelas yang dihasilkan engine_observer . Jangan hapus arahan preproscessor yang dihasilkan oleh langkah sebelumnya (#pragma, #include). Kemudian salin/tempel sumber berikut ke dalam file, setelah direktif praprosesor yang ada:

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

};

Perbarui "engine_observer.cpp", dengan memilih/menghapus implementasi kelas yang dihasilkan engine_observer . Jangan hapus arahan preproscessor yang dihasilkan oleh langkah sebelumnya (#pragma, #include). Kemudian salin/tempel sumber berikut ke dalam file, setelah direktif praprosesor yang ada:

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

Secara opsional, gunakan Ctrl+Shift+B (Build Solution) untuk menjalankan kompilasi/tautan pengujian solusi Anda, untuk memastikannya berhasil dibangun sebelum melanjutkan.

MIP SDK menerapkan autentikasi menggunakan ekstensibilitas kelas, yang menyediakan mekanisme untuk berbagi pekerjaan autentikasi dengan aplikasi klien. Klien harus memperoleh token akses OAuth2 yang sesuai, dan menyediakan ke MIP SDK saat runtime.

Buat implementasi untuk delegasi autentikasi, dengan memperluas kelas SDK mip::AuthDelegate , dan menimpa/mengimplementasikan mip::AuthDelegate::AcquireOAuth2Token() fungsi virtual murni. Ikuti langkah-langkah yang dirinci di bawah Mulai Cepat Inisialisasi Aplikasi SDK File. Delegasi autentikasi dibuat dan digunakan nanti, oleh profil Perlindungan dan Objek mesin perlindungan.

Sekarang buat implementasi untuk delegasi persetujuan, dengan memperluas kelas SDK mip::ConsentDelegate , dan mengambil alih/menerapkan mip::AuthDelegate::GetUserConsent() fungsi virtual murni. Ikuti langkah-langkah yang dirinci di bawah Mulai Cepat Inisialisasi Aplikasi SDK File. Delegasi persetujuan dibuat dan digunakan nanti, oleh profil Perlindungan dan Objek mesin perlindungan.

Membuat profil dan mesin Perlindungan

Seperti disebutkan, profil dan objek mesin diperlukan untuk klien SDK menggunakan API MIP. Lengkapi bagian pengkodean mulai cepat ini, dengan menambahkan kode untuk membuat instans profil dan objek mesin:

Dari Penjelajah Solusi, buka file .cpp dalam proyek Anda yang berisi implementasi main() metode . Ini default ke nama yang sama dengan proyek yang berisinya, yang Anda tentukan selama pembuatan proyek.
Hapus implementasi yang dihasilkan dari main(). Jangan hapus arahan preproscessor yang dihasilkan oleh Visual Studio selama pembuatan proyek (#pragma, #include). Tambahkan kode berikut setelah direktif praprosesor apa pun:

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

Ganti semua nilai tempat penampung dalam kode sumber yang baru saja Anda tempelkan, menggunakan konstanta string:

Placeholder	Nilai	Contoh
<application-id>	ID Aplikasi Microsoft Entra (GUID) yang ditetapkan ke aplikasi yang terdaftar di langkah #2 dari artikel "Penyiapan dan konfigurasi SDK MIP"(setup-configure-mip.md). Ganti 2 instans.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<nama aplikasi>	Nama ramah yang ditentukan pengguna untuk aplikasi Anda. Harus berisi karakter ASCII yang valid (tidak termasuk ';'), dan idealnya cocok dengan nama aplikasi yang Anda gunakan dalam pendaftaran Microsoft Entra Anda.	`"AppInitialization"`
<versi aplikasi>	Info versi yang ditentukan pengguna untuk aplikasi Anda. Harus berisi karakter ASCII yang valid (tidak termasuk ';').	`"1.1.0.0"`
<akun mesin>	Akun yang digunakan untuk identitas mesin. Saat Anda mengautentikasi dengan akun pengguna selama akuisisi token, itu harus cocok dengan nilai ini.	`"user1@tenant.onmicrosoft.com"`
<status mesin>	Status yang ditentukan pengguna untuk dikaitkan dengan mesin.	`"My App State"`

Sekarang lakukan build akhir aplikasi dan atasi kesalahan apa pun. Kode Anda harus berhasil dibuat, tetapi belum akan berjalan dengan benar sampai Anda menyelesaikan Mulai Cepat berikutnya. Jika Anda menjalankan aplikasi, Anda akan melihat output yang mirip dengan yang berikut ini. Aplikasi akan membuat profil Perlindungan dan mesin Perlindungan dengan susah payah tetapi tidak akan mengaktifkan modul autentikasi dan Anda belum akan memiliki token akses, sampai Anda menyelesaikan Mulai Cepat berikutnya.
```
 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 . . .
```

Langkah berikutnya

Setelah kode inisialisasi selesai, Anda siap untuk mulai cepat berikutnya, tempat Anda akan mulai mengalami SDK Perlindungan MIP.

Mencantumkan templat perlindungan

Bagikan melalui

Mulai cepat: Inisialisasi aplikasi klien untuk SDK Perlindungan (C++)

Prasyarat

Membuat solusi dan proyek Visual Studio

Menerapkan kelas pengamat untuk memantau profil Perlindungan dan objek mesin

Membuat profil dan mesin Perlindungan

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Mulai cepat: Inisialisasi aplikasi klien untuk SDK Perlindungan (C++)

Prasyarat

Membuat solusi dan proyek Visual Studio

Menerapkan kelas pengamat untuk memantau profil Perlindungan dan objek mesin

Menerapkan delegasi autentikasi dan delegasi persetujuan

Menerapkan delegasi persetujuan

Membuat profil dan mesin Perlindungan

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: