Mulai cepat: Inisialisasi aplikasi klien (C#)

Panduan memulai cepat ini akan memandu Anda tentang cara menerapkan pola inisialisasi klien yang digunakan oleh pembungkus MIP SDK .NET saat runtime.

Nota

Langkah-langkah yang diuraikan dalam panduan cepat ini diperlukan untuk aplikasi klien apa pun yang menggunakan wrapper MIP .NET SDK File, Kebijakan, atau Perlindungan. Meskipun Panduan Cepat ini menunjukkan penggunaan SDK File, pola yang sama berlaku untuk klien yang menggunakan SDK Kebijakan dan Perlindungan. Quickstart Mendatang harus dilakukan secara serial, karena masing-masing dibangun berdasarkan yang sebelumnya, dan Quickstart ini adalah yang pertama. Kode ini dimaksudkan untuk menunjukkan cara memulai SDK MIP dan tidak dimaksudkan untuk penggunaan produksi.

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.
Opsional:
- Tinjau Profil dan objek mesin. Objek profil dan mesin adalah konsep universal yang diperlukan oleh klien yang menggunakan Kit Pengembangan Perangkat Lunak (SDKs) MIP untuk File/Kebijakan/Perlindungan.
- Tinjau konsep Autentikasi untuk mempelajari bagaimana autentikasi dan persetujuan diterapkan oleh SDK dan aplikasi klien.

Membuat solusi dan proyek Visual Studio

Pertama, kita membuat dan mengonfigurasi solusi dan proyek awal Visual Studio, yang menjadi dasar pembangunan Quickstart lainnya.

Buka Visual Studio 2022 atau yang lebih baru, pilih menu File , Baru, Proyek. Dalam dialog Proyek Baru :
- Di panel kiri, di bawah Terinstal, Visual C#, pilih Windows Desktop.
- Di panel tengah, pilih Aplikasi Konsol (menargetkan .NET 8 atau yang lebih baru)
- 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 pada 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 perubahan pratinjau ditampilkan.
Ulangi langkah-langkah di atas untuk menambahkan paket MIP File SDK, tetapi sebagai gantinya tambahkan "Microsoft.Identity.Client" ke aplikasi.

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 antarmuka SDK Microsoft.InformationProtection.IAuthDelegate, dan menimpa/mengimplementasikan fungsi virtual IAuthDelegate.AcquireToken(). Delegasi autentikasi dibuat dan digunakan nanti oleh objek FileProfile dan FileEngine.

Klik kanan nama proyek di Visual Studio, pilih Tambahkan lalu Kelas.
Masukkan "AuthDelegateImplementation" di bidang Nama . Klik Tambahkan.
Tambahkan menggunakan pernyataan untuk Microsoft Authentication Library (MSAL) dan pustaka MIP:
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
Atur AuthDelegateImplementation agar mewarisi Microsoft.InformationProtection.IAuthDelegate serta mengimplementasikan variabel anggota privat dari Microsoft.InformationProtection.ApplicationInfo dan konstruktor yang menerima parameter dengan jenis yang sama.
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
Objek ApplicationInfo berisi tiga properti. _appInfo.ApplicationId akan digunakan di AuthDelegateImplementation kelas untuk memberikan ID klien ke pustaka autentikasi. ApplicationName dan ApplicationVersion akan muncul dalam laporan audit Microsoft Purview.

Tambahkan metode public string AcquireToken(). Metode ini harus menerima Microsoft.InformationProtection.Identity dan tiga string: URL otoritas, URI sumber daya, dan klaim, jika diperlukan. Variabel string ini akan diteruskan ke pustaka autentikasi oleh API dan tidak boleh dimanipulasi. Masukkan GUID Penyewa dari portal Microsoft Azure untuk penyewa Anda. Mengedit string selain GUID Penyewa dapat mengakibatkan kegagalan untuk mengautentikasi.

public string AcquireToken(Identity identity, string authority, string resource, string claims)
{
   var authorityUri = new Uri(authority);
   authority = String.Format("https://{0}/{1}", authorityUri.Host, "<Tenant-GUID>");

   _app = PublicClientApplicationBuilder.Create(_appInfo.ApplicationId).WithAuthority(authority).WithDefaultRedirectUri().Build();
   var accounts = (_app.GetAccountsAsync()).GetAwaiter().GetResult();

   // Append .default to the resource passed in to AcquireToken().
   string[] scopes = new string[] { resource[resource.Length - 1].Equals('/') ? $"{resource}.default" : $"{resource}/.default" };
   var result = _app.AcquireTokenInteractive(scopes).WithAccount(accounts.FirstOrDefault()).WithPrompt(Prompt.SelectAccount)
              .ExecuteAsync().ConfigureAwait(false).GetAwaiter().GetResult();

   return result.AccessToken;
}

Sekarang buat implementasi untuk delegasi persetujuan, dengan memperluas antarmuka SDK Microsoft.InformationProtection.IConsentDelegate , dan mengambil alih/menerapkan GetUserConsent(). Objek delegasi persetujuan dibuat dan kemudian digunakan oleh profil File dan mesin File. Delegasi persetujuan diberikan alamat layanan yang harus disetujui pengguna untuk digunakan dalam parameter url. Delegasi umumnya harus memberikan beberapa alur yang memungkinkan pengguna untuk menerima atau menolak persetujuan untuk mengakses layanan. Untuk quickstart ini gunakan kode hard Consent.Accept.

Menggunakan fitur "Tambahkan Kelas" Visual Studio yang sama dengan yang kami gunakan sebelumnya, tambahkan kelas lain ke proyek Anda. Kali ini, masukkan "ConsentDelegateImplementation" di bidang Nama Kelas .
Sekarang perbarui ConsentDelegateImpl.cs untuk menerapkan kelas delegasi persetujuan baru Anda. Tambahkan pernyataan penggunaan untuk Microsoft.InformationProtection dan atur kelas untuk mewarisi IConsentDelegate.
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
Secara opsional, coba bangun solusi untuk memastikan bahwa solusi dikompilasi tanpa kesalahan.

Menginisialisasi Pembungkus Terkelola MIP SDK

Dari Penjelajah Solusi, buka file .cs dalam proyek Anda yang berisi implementasi Main() metode . Secara default, ini menggunakan nama yang sama dengan proyek tempatnya berada, yang Anda tentukan pada saat pembuatan proyek.
Hapus implementasi yang dihasilkan dari main().
Pembungkus terkelola mencakup kelas statis, Microsoft.InformationProtection.MIP digunakan untuk inisialisasi, membuat MipContext, memuat profil, dan merilis sumber daya. Untuk menginisialisasi pembungkus untuk operasi File SDK, panggil MIP.Initialize(), lalu gunakan MipComponent.File untuk memuat library yang diperlukan untuk operasi file.
Di Main()Program.cs tambahkan yang berikut ini, ganti <id> aplikasi dengan ID Pendaftaran Aplikasi Microsoft Entra yang dibuat sebelumnya.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.Exceptions;
using Microsoft.InformationProtection.File;
using Microsoft.InformationProtection.Protection;

namespace mip_sdk_dotnet_quickstart
{
    class Program
    {
        private const string clientId = "<application-id>";
        private const string appName = "<friendly-name>";

        static void Main(string[] args)
        {
            //Initialize Wrapper for File SDK operations
            MIP.Initialize(MipComponent.File);
            
        }
    }
}

Membangun Profil File dan Mesin Pemrosesan

Seperti disebutkan, profil dan objek mesin diperlukan untuk klien SDK menggunakan API MIP. Lengkapi bagian pengkodean Quickstart ini, dengan menambahkan kode untuk memuat DLL asli lalu menginstansiasi objek profil dan mesin.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.File;

namespace mip_sdk_dotnet_quickstart
{
  class Program
  {
       private const string clientId = "<application-id>";
       private const string appName = "<friendly-name>";

       static void Main(string[] args)
       {
            // Initialize Wrapper for File SDK operations.
            MIP.Initialize(MipComponent.File);

            // Create ApplicationInfo, setting the clientID from Microsoft Entra App Registration as the ApplicationId.
            ApplicationInfo appInfo = new ApplicationInfo()
            {
                 ApplicationId = clientId,
                 ApplicationName = appName,
                 ApplicationVersion = "1.0.0"
            };

            // Instantiate the AuthDelegateImpl object, passing in AppInfo.
            AuthDelegateImplementation authDelegate = new AuthDelegateImplementation(appInfo);

            // Create MipConfiguration Object
            MipConfiguration mipConfiguration = new MipConfiguration(appInfo, "mip_data", LogLevel.Trace, false);

            // Create MipContext using Configuration
            MipContext mipContext = MIP.CreateMipContext(mipConfiguration);

            // Initialize and instantiate the File Profile.
            // Create the FileProfileSettings object.
            // Initialize file profile settings to create/use local state.
            var profileSettings = new FileProfileSettings(mipContext,
                                     CacheStorageType.OnDiskEncrypted,
                                     new ConsentDelegateImplementation());

            // Load the Profile async and wait for the result.
            var fileProfile = Task.Run(async () => await MIP.LoadFileProfileAsync(profileSettings)).Result;

            // Create a FileEngineSettings object, then use that to add an engine to the profile.
            // This pattern sets the engine ID to user1@tenant.com, then sets the identity used to create the engine.
            var engineSettings = new FileEngineSettings("user1@tenant.com", authDelegate, "", "en-US");
            engineSettings.Identity = new Identity("user1@tenant.com");

            var fileEngine = Task.Run(async () => await fileProfile.AddEngineAsync(engineSettings)).Result;

            // Application Shutdown
            // handler = null; // This will be used in later quick starts.
            fileEngine = null;
            fileProfile = null;
            mipContext.ShutDown();
            mipContext = null;
       }
  }
}

Ganti nilai placeholder dalam kode sumber yang telah Anda tempelkan, menggunakan nilai berikut:

Placeholder	Nilai	Example
<application-id>	ID Aplikasi Microsoft Entra yang ditetapkan ke aplikasi yang terdaftar dalam "penyiapan dan konfigurasi MIP SDK" (2 instans).	0edbblll-8773-44de-b87c-b8c6276d41eb
<nama ramah>	Nama ramah yang ditentukan pengguna untuk aplikasi Anda.	InisialisasiAplikasi
<Tenant-GUID>	Tenant-ID untuk penyewa Microsoft Entra Anda	TenantID

Sekarang lakukan build akhir aplikasi dan atasi kesalahan apa pun. Kode Anda harus berhasil dikompilasi.

Langkah Selanjutnya

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

Mencantumkan label sensitivitas

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-20