Mulai cepat: Inisialisasi aplikasi klien (C++)

Panduan cepat ini menunjukkan kepada Anda cara menerapkan pola inisialisasi klien yang digunakan oleh MIP C++ SDK selama runtime.

Nota

Langkah-langkah yang diuraikan dalam panduan kilat ini perlu dilakukan untuk aplikasi klien apa pun yang menggunakan SDK MIP untuk File, Kebijakan, atau Perlindungan. Meskipun Panduan Cepat ini menunjukkan penggunaan SDK File, pola yang sama ini juga berlaku untuk pengguna yang menggunakan SDK Kebijakan dan Perlindungan. Selesaikan Quickstarts yang tersisa secara berurutan, karena masing-masing dibangun berdasarkan yang sebelumnya, dengan yang ini sebagai yang pertama.

Prasyarat

Jika Anda belum melakukannya, pastikan untuk:

Selesaikan langkah-langkah dalam penyiapan dan konfigurasi SDK Microsoft Information Protection (MIP). Panduan Cepat: "Inisialisasi Aplikasi Klien" ini bergantung pada penyiapan dan konfigurasi SDK yang tepat.
Secara opsional:
- Tinjau Profil dan objek mesin. Profil dan objek 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, yang menjadi dasar bagi Panduan Cepat lainnya.

Buka Visual Studio 2019 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, klik tombol OK di kanan bawah.
Tambahkan paket NuGet untuk MIP File SDK 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.File".
  - Klik "Instal", lalu klik "OK" saat dialog konfirmasi Pratinjau perubahan ditampilkan.

Menerapkan kelas pengamat untuk memantau profil file dan objek mesin

Sekarang buat implementasi dasar untuk kelas pengamat profil File, dengan memperluas kelas SDK mip::FileProfile::Observer . Pengamat diinisiasi dan kemudian digunakan untuk memantau pemuatan objek profil File serta menambahkan objek mesin ke dalam 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 file .h dan bidang 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 direktif pra-prosesor yang dihasilkan oleh langkah sebelumnya (#pragma, #include). Kemudian salin/tempel sumber berikut ke dalam file, setelah direktif praprosesor yang ada:

#include <memory>
#include "mip/file/file_profile.h"

class ProfileObserver final : public mip::FileProfile::Observer {
public:
     ProfileObserver() { }
     void OnLoadSuccess(const std::shared_ptr<mip::FileProfile>& profile, const std::shared_ptr<void>& context) override;
     void OnLoadFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
     void OnAddEngineSuccess(const std::shared_ptr<mip::FileEngine>& engine, const std::shared_ptr<void>& context) override;
     void OnAddEngineFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
};

Perbarui "profile_observer.cpp", dengan memilih/menghapus implementasi kelas yang dihasilkan profile_observer . Jangan hapus direktif pra-prosesor 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::FileEngine;
using mip::FileProfile;

void ProfileObserver::OnLoadSuccess(const shared_ptr<FileProfile>& profile, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<FileProfile>>>(context);
     promise->set_value(profile);
}

void ProfileObserver::OnLoadFailure(const std::exception_ptr& error, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<FileProfile>>>(context);
     promise->set_exception(error);
}

void ProfileObserver::OnAddEngineSuccess(const shared_ptr<FileEngine>& engine, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<FileEngine>>>(context);
     promise->set_value(engine);
}

void ProfileObserver::OnAddEngineFailure(const std::exception_ptr& error, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<FileEngine>>>(context);
     promise->set_exception(error);
}

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

Menerapkan delegasi autentikasi

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.

Sekarang buat implementasi untuk delegasi autentikasi, dengan memperluas kelas SDK mip::AuthDelegate , dan menimpa/mengimplementasikan mip::AuthDelegate::AcquireOAuth2Token() fungsi virtual murni. Delegasi autentikasi dibuat dan digunakan nanti, oleh profil File dan objek Mesin file.

Menggunakan fitur "Tambahkan Kelas" Visual Studio yang sama dengan yang kami gunakan di langkah #1 dari bagian sebelumnya, tambahkan kelas lain ke proyek Anda. Kali ini, masukkan "auth_delegate" di bidang Nama Kelas .

Sekarang perbarui setiap file untuk mengimplementasikan kelas delegasi autentikasi baru Anda:

Perbarui "auth_delegate.h", dengan mengganti semua kode kelas yang dihasilkan auth_delegate dengan sumber berikut. Jangan hapus direktif pra-prosesor yang dihasilkan oleh langkah sebelumnya (#pragma, #include):

#include <string>
#include "mip/common_types.h"

class AuthDelegateImpl final : public mip::AuthDelegate {
public:
     AuthDelegateImpl() = delete;        // Prevents default constructor

     AuthDelegateImpl(
       const std::string& appId)         // AppID for registered AAD app
       : mAppId(appId) {};

     bool AcquireOAuth2Token(            // Called by MIP SDK to get a token
       const mip::Identity& identity,    // Identity of the account to be authenticated, if known
       const OAuth2Challenge& challenge, // Authority (AAD tenant issuing token), and resource (API being accessed; "aud" claim).
       OAuth2Token& token) override;     // Token handed back to MIP SDK

private:
     std::string mAppId;
     std::string mToken;
     std::string mAuthority;
     std::string mResource;
};

Perbarui "auth_delegate.cpp", dengan mengganti semua implementasi kelas yang dihasilkan auth_delegate dengan sumber berikut. Jangan hapus direktif pra-prosesor yang dihasilkan oleh langkah sebelumnya (#pragma, #include).
Penting

Kode akuisisi token berikut tidak cocok untuk penggunaan produksi. Dalam produksi, ini harus diganti dengan kode yang secara dinamis memperoleh token, menggunakan:
- URI appId dan balasan/pengalihan yang ditentukan dalam pendaftaran aplikasi Microsoft Entra Anda (URI balasan/pengalihan harus cocok dengan pendaftaran aplikasi Anda)
- URL otoritas dan sumber daya yang diteruskan oleh SDK dalam argumen challenge (URL sumber daya harus sesuai dengan API dan izin pendaftaran aplikasi Anda)
- Kredensial aplikasi/pengguna yang valid, di mana akun cocok dengan argumen identity yang diteruskan oleh SDK. Klien "asli" OAuth2 harus meminta kredensial pengguna dan menggunakan alur "kode otorisasi". "Klien rahasia" OAuth2 dapat menggunakan kredensial aman mereka sendiri dengan alur "kredensial klien" (seperti layanan), atau meminta kredensial pengguna menggunakan alur "kode otorisasi" (seperti aplikasi web).
Akuisisi token OAuth2 adalah protokol yang kompleks, dan biasanya dicapai dengan menggunakan pustaka. TokenAcquireOAuth2Token() hanya dipanggil oleh MIP SDK, sesuai kebutuhan.
```
#include <iostream>
using std::cout;
using std::cin;
using std::string;

bool AuthDelegateImpl::AcquireOAuth2Token(const mip::Identity& identity, const OAuth2Challenge& challenge, OAuth2Token& token) 
{
     // Acquire a token manually, reuse previous token if same authority/resource. In production, replace with token acquisition code.
     string authority = challenge.GetAuthority();
     string resource = challenge.GetResource();
     if (mToken == "" || (authority != mAuthority || resource != mResource))
     {
         cout << "\nRun the PowerShell script to generate an access token using the following values, then copy/paste it below:\n";
         cout << "Set $authority to: " + authority + "\n";
         cout << "Set $resourceUrl to: " + resource + "\n";
         cout << "Sign in with user account: " + identity.GetEmail() + "\n";
         cout << "Enter access token: ";
         cin >> mToken;
         mAuthority = authority;
         mResource = resource;
         system("pause");
     }

     // Pass access token back to MIP SDK
     token.SetAccessToken(mToken);

     // True = successful token acquisition; False = failure
     return true;
}
```

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

Sekarang buat implementasi untuk delegasi persetujuan, dengan memperluas kelas SDK mip::ConsentDelegate, dan meng-override/mengimplementasikan mip::AuthDelegate::GetUserConsent() fungsi virtual murni. Delegasi persetujuan dibuat dan digunakan nanti, oleh profil File dan objek mesin file.

Menggunakan fitur "Tambahkan Kelas" Visual Studio yang sama dengan yang kami gunakan sebelumnya, tambahkan kelas lain ke proyek Anda. Kali ini, masukkan "consent_delegate" di bidang Nama Kelas .
Sekarang perbarui setiap file untuk mengimplementasikan kelas delegasi persetujuan baru Anda:
- Perbarui "consent_delegate.h", dengan mengganti semua kode kelas yang dihasilkan consent_delegate dengan sumber berikut. Jangan hapus direktif pra-prosesor yang dihasilkan oleh langkah sebelumnya (#pragma, #include):
```
#include "mip/common_types.h"
#include <string>

class ConsentDelegateImpl final : public mip::ConsentDelegate {
public:
     ConsentDelegateImpl() = default;
     virtual mip::Consent GetUserConsent(const std::string& url) override;
};
```
- Perbarui "consent_delegate.cpp", dengan mengganti semua implementasi kelas yang dihasilkan consent_delegate dengan sumber berikut. Jangan hapus direktif pra-prosesor yang dihasilkan oleh langkah sebelumnya (#pragma, #include).
```
#include <iostream>
using mip::Consent;
using std::string;

Consent ConsentDelegateImpl::GetUserConsent(const string& url) 
{
     // Accept the consent to connect to the url
     std::cout << "SDK will connect to: " << url << std::endl;
     return Consent::AcceptAlways;
}
```
Secara opsional, gunakan F6 (Build Solution) untuk menjalankan kompilasi/tautan pengujian solusi Anda, untuk memastikannya berhasil dibangun sebelum melanjutkan.

Membuat profil file dan mesin pengolah

Seperti disebutkan, profil dan objek mesin diperlukan untuk klien SDK menggunakan API MIP. Lengkapi bagian pengembangan kode dari Quickstart ini, dengan menambahkan kode untuk membuat instance 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 praprosesor yang dihasilkan oleh Visual Studio selama pembuatan proyek (#pragma, #include). Tambahkan kode berikut setelah direktif praprosesor apa pun:

#include "mip/mip_context.h"  
#include "auth_delegate.h"
#include "consent_delegate.h"
#include "profile_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::FileProfile;
using mip::FileEngine;

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

  // Create MipConfiguration object.
  std::shared_ptr<mip::MipConfiguration> mipConfiguration = std::make_shared<mip::MipConfiguration>(appInfo,    
				                                                                                               "mip_data", 
                                                                                      			         mip::LogLevel::Trace, 
                                                                                                     false);


  std::shared_ptr<mip::MipContext> mMipContext = mip::MipContext::Create(mipConfiguration);

  auto profileObserver = make_shared<ProfileObserver>();                     // 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
  FileProfile::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<FileProfile>>>();
  auto profileFuture = profilePromise->get_future();

  try
	  { 
		  mip::FileProfile::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
  FileEngine::Settings engineSettings(
                                  mip::Identity("<engine-account>"), // Engine identity (account used for authentication)
                                  authDelegateImpl,		       // Token acquisition implementation
				    "<engine-state>",                  // User-defined engine state
                                  "en-US");                          // Locale (default = en-US)
                                  
  // Set the engineId for caching. 
  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<FileEngine>>>();
  auto engineFuture = enginePromise->get_future();
  profile->AddEngineAsync(engineSettings, enginePromise);
  std::shared_ptr<FileEngine> 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.
  // handler = nullptr; // This will be used in later quick starts.
  engine = nullptr;
  profile = nullptr;   
  mMipContext->ShutDown();
  mMipContext = nullptr;

  return 0;
  }

Ganti semua nilai placeholder dalam kode sumber yang baru saja Anda tempel, menggunakan konstanta berbentuk string.

Pengganti sementara	Nilai	Contoh
<application-id>	ID Aplikasi Microsoft Entra (GUID) yang ditetapkan kepada aplikasi yang didaftarkan di langkah #2 dari artikel "Penyiapan dan konfigurasi SDK MIP". 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 seharusnya berhasil dibangun, tetapi belum akan dijalankan dengan benar sampai Anda menyelesaikan Panduan Mulai Cepat berikutnya. Jika Anda menjalankan aplikasi, Anda akan melihat output yang mirip dengan yang berikut ini. Anda tidak akan memiliki token akses untuk disediakan, hingga Anda menyelesaikan Mulai Cepat berikutnya.

Langkah Berikutnya

Setelah kode inisialisasi Anda selesai, Anda siap untuk panduan memulai cepat berikutnya, di mana Anda akan mulai menggunakan SDK MIP File.

Mencantumkan label sensitivitas

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-04-11