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

Panduan singkat ini menjelaskan cara mengimplementasikan pola inisialisasi klien yang digunakan oleh MIP C++ SDK pada waktu proses.

Nota

Setiap aplikasi klien yang menggunakan SDK Perlindungan MIP memerlukan langkah-langkah dalam panduan mulai cepat ini. Selesaikan panduan mulai cepat ini secara berurutan setelah aplikasi diinisialisasi serta kelas delegasi otentikasi dan delegasi persetujuan diimplementasikan.

Prasyarat

Jika Anda belum melakukannya, pastikan untuk:

Selesaikan langkah-langkah dalam penyiapan dan konfigurasi SDK Microsoft Information Protection (MIP). Panduan singkat "Inisialisasi aplikasi klien" ini memerlukan penyiapan dan konfigurasi SDK yang benar.
Opsional:
- Tinjau Profil dan objek mesin. Objek profil dan engine adalah konsep universal yang diperlukan oleh klien yang menggunakan SDK MIP File/Kebijakan/Perlindungan.
- 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, buat dan konfigurasikan solusi dan proyek Visual Studio awal yang menjadi dasar bagi panduan mulai cepat lainnya.

Buka Visual Studio 2022 atau yang lebih baru, 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, pilih OK di sudut kanan bawah.
Tambahkan paket NuGet untuk SDK Perlindungan MIP ke proyek Anda:
- Di Penjelajah Solusi, klik kanan simpul proyek langsung di bawah node solusi teratas, lalu 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.
  - Pilih Instal, lalu pilih OK saat dialog Konfirmasi perubahan pratinjau muncul.

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 . SDK membuat instans pengamat dan menggunakannya 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 Visual Studio secara otomatis mengisi file .h dan bidang file .cpp berdasarkan nama yang Anda masukkan.
  - Setelah selesai, pilih OK.

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

Perbarui profile_observer.h dengan memilih dan menghapus kelas yang dihasilkan profile_observer . Jangan hapus direktif pra-prosesor yang dihasilkan langkah sebelumnya (#pragma, #include). Kemudian salin dan tempel sumber berikut ke dalam file setelah arahan 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 dan menghapus implementasi kelas yang dihasilkan profile_observer . Jangan hapus direktif pra-prosesor yang dihasilkan langkah sebelumnya (#pragma, #include). Kemudian salin dan tempel sumber berikut ke dalam file setelah arahan 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);
}

Ulangi langkah 1 untuk menambahkan kelas baru untuk pengamat mesin perlindungan, engine_observer, ke proyek Anda. Kelas ini menghasilkan file header (.h) dan implementasi (.cpp) untuk Anda.

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

Perbarui engine_observer.h dengan memilih dan menghapus kelas yang dihasilkan engine_observer . Jangan hapus direktif pra-prosesor yang dihasilkan langkah sebelumnya (#pragma, #include). Kemudian salin dan tempel sumber berikut ke dalam file setelah arahan 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 dan menghapus implementasi kelas yang dihasilkan engine_observer . Jangan hapus direktif pra-prosesor yang dihasilkan langkah sebelumnya (#pragma, #include). Kemudian salin dan tempel sumber berikut ke dalam file setelah arahan 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 pengujian dan tautan solusi Anda untuk memverifikasi bahwa solusi berhasil dibuat sebelum melanjutkan.

MIP SDK menerapkan autentikasi melalui ekstensibilitas kelas, yang menyediakan mekanisme untuk berbagi pekerjaan autentikasi dengan aplikasi klien. Klien harus memperoleh token akses OAuth2 yang sesuai dan memberikannya 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 File SDK. Profil perlindungan dan objek mesin perlindungan membuat instans dan menggunakan delegat autentikasi di kemudian hari.

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 File SDK. Profil perlindungan dan objek mesin perlindungan membuat instance dan kemudian menggunakan delegasi persetujuan.

Membangun profil perlindungan dan mesin

Seperti disebutkan, klien SDK yang menggunakan API MIP memerlukan objek profil dan mesin. 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 secara otomatis menggunakan nama yang sama dengan proyek yang mengandungnya, yang Anda tentukan selama pembuatan proyek.
Hapus implementasi yang dihasilkan dari main(). Jangan hapus arahan praprosesor 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 placeholder dalam kode sumber yang Anda tempelkan dengan menggunakan konstanta string:

Placeholder	Nilai	Example
<application-id>	ID Aplikasi Microsoft Entra (GUID) yang ditetapkan ke aplikasi yang Anda daftarkan di langkah #2 dari artikel penyiapan dan konfigurasi MIP SDK. Ganti 2 instans.	`"00001111-aaaa-2222-bbbb-3333cccc4444"`
<nama aplikasi>	Nama ramah yang ditentukan pengguna untuk aplikasi Anda. Ini 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. Ini harus berisi karakter ASCII yang valid (tidak termasuk ';').	`"1.1.0.0"`
<akun mesin>	Akun yang digunakan untuk identitas mesin penggerak. 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 seharusnya berhasil dikompilasi, tetapi belum akan berjalan dengan benar sampai Anda menyelesaikan panduan memulai cepat berikutnya. Jika Anda menjalankan aplikasi, Anda akan melihat output yang mirip dengan yang berikut ini. Aplikasi ini berhasil membangun profil Perlindungan dan mesin Perlindungan, tetapi tidak mengaktifkan modul autentikasi dan Anda tidak memiliki token akses hingga 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

Sekarang setelah kode inisialisasi Anda selesai, Anda siap untuk panduan memulai cepat berikutnya, di mana Anda akan mulai menggunakan SDK Perlindungan MIP.

Mencantumkan templat perlindungan

Jelajahi sampel MIP Protection SDK C++ pada GitHub.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-09-21