快速入门：客户端应用程序初始化 (C#)

项目
12/20/2023

本快速入门将介绍如何实现 MIP SDK .NET 包装器在运行时使用的客户端初始化模式。

注意

本快速入门中概述的步骤对于使用 MIP .NET 包装器文件、策略或保护 SDK 的任何客户端应用程序都是必需的。尽管本快速入门介绍的是文件 SDK 的用法，但使用策略和保护 SDK 的客户端也适用同样的模式。未来的快速入门应该连续完成，因为其中的每个快速入门都以前一个为基础，下面开始第一个快速入门。此代码旨在演示如何开始使用 MIP SDK，不应将其用于生产目的。

先决条件

如果尚未完成，请确保：

完成 Microsoft 信息保护 (MIP) SDK 安装和配置中的步骤。此“客户端应用程序初始化”快速入门需要先正确安装和配置 SDK。
可选：
- 查看配置文件和引擎对象。配置文件和引擎对象是通用概念，使用 MIP 文件/策略/保护 SDK 的客户端需要用到它们。
- 查看身份验证概念，了解 SDK 和客户端应用程序如何实现身份验证和许可。

创建 Visual Studio 解决方案和项目

首先，创建并配置初始 Visual Studio 解决方案和项目，其他快速入门将以此为基础。

打开 Visual Studio 2019，依次选择“文件”菜单、“新建”、“项目”。在“新建项目”对话框中：
- 在左侧窗格中的“已安装”下的“Visual C#”中，选择“Windows 桌面”。
- 在中间窗格中，选择“控制台应用(.NET Framework)”
- 在底部窗格中，对项目“名称”、“位置”和包含的“解决方案名称”进行相应更新。
- 完成后，单击右下角的“确定”按钮。
将 MIP 文件 SDK 的 Nuget 包添加到项目：
- 在“解决方案资源管理器”中，右键单击项目节点（直接在顶部/解决方案节点下方单击），然后选择“管理 NuGet 包...”：
- 当“NuGet 包管理器”选项卡在编辑器组选项卡区域中打开时：
  - 选择浏览。
  - 在搜索框中输入“Microsoft.InformationProtection”。
  - 选择“Microsoft.InformationProtection.File”包。
  - 单击“安装”，然后在显示“预览更改”确认对话框时，单击“确定”。
重复上述步骤以添加 MIP 文件 SDK 包，但改为将“Microsoft.Identity.Client”添加到应用程序。

实现身份验证委托

MIP SDK 使用类扩展性实现身份验证，它提供了一种与客户端应用程序共享身份验证工作的机制。客户端必须获取合适的 OAuth2 访问令牌，并在运行时提供给 MIP SDK。

现在，通过扩展 SDK 的 Microsoft.InformationProtection.IAuthDelegate 接口，并替代/实现 IAuthDelegate.AcquireToken() 虚函数，为身份验证委托创建一个实现。身份验证委托稍后由 FileProfile 和 FileEngine 对象实例化并使用。

在 Visual Studio 中右键单击项目名称，选择“添加”，然后选择“类”。
在“名称”字段中输入“AuthDelegateImplementation”。单击“添加” 。

为 Microsoft 身份验证库 (MSAL) 和 MIP 库添加 using 语句：

using Microsoft.InformationProtection;
using Microsoft.Identity.Client;

将 AuthDelegateImplementation 设置为继承 Microsoft.InformationProtection.IAuthDelegate，并实现 Microsoft.InformationProtection.ApplicationInfo 的私有变量和接受相同类型的构造函数。
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
ApplicationInfo 对象包含三个属性。 _appInfo.ApplicationId 将在 AuthDelegateImplementation 类中用于向身份验证库提供客户端 ID。 ApplicationName 和 ApplicationVersion 将出现在 Azure 信息保护分析报告中。

添加 public string AcquireToken() 方法。此方法应接受 Microsoft.InformationProtection.Identity 和三个字符串：授权 URL、资源 URI 和声明（如果需要）。这些字符串变量将由 API 传递到身份验证库，不应被操纵。请为租户输入 Azure 门户中的租户 GUID。编辑为租户 GUID 以外的字符串可能会导致身份验证失败。

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

现在，通过扩展 SDK 的 Microsoft.InformationProtection.IConsentDelegate 接口，并替代/实现 GetUserConsent()，为许可委托创建一个实现。许可委托稍后由文件配置文件和文件引擎对象实例化并使用。许可委托在 url 参数中提供了用户必须同意使用的服务的地址。委托通常应提供一些流程，允许用户接受或拒绝同意访问服务。对于本快速入门硬代码 Consent.Accept。

通过在之前使用的相同的 Visual Studio“添加类”功能，将另一个类添加到项目中。这次在“类名”字段中输入“ConsentDelegateImplementation”。
现在更新“ConsentDelegateImpl.cs”以实现新许可委托类。为 Microsoft.InformationProtection 添加 using 语句，并将类设置为继承 IConsentDelegate。
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
或者，尝试生成解决方案以确保其编译时没有错误。

初始化 MIP SDK 托管包装器

从解决方案资源管理器，打开项目中包含 Main() 方法实现的 .cs 文件。该文件默认与包含它的项目同名，该名称在项目创建期间指定。
删除生成的 main() 实现。
托管包装器包括一个静态类 Microsoft.InformationProtection.MIP，用于初始化、创建 MipContext、加载配置文件和释放资源。若要初始化文件 SDK 操作的包装器，请调用 MIP.Initialize()，传入 MipComponent.File 以加载文件操作所需的库。
在 Program.cs 的 Main() 中添加以下内容，将 <application-id> 替换为之前创建的 Microsoft Entra 应用程序注册的 ID。

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

构造文件配置文件和引擎

如前所述，使用 MIP API 的 SDK 客户端需要配置文件和引擎对象。通过添加代码来加载本机 DLL，然后实例化配置文件和引擎对象，完成本快速入门的编码部分。

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

使用以下值替换粘贴的源代码中的占位符值：

占位符	值	示例
<application-id>	分配给在“MIP SDK 安装和配置”中注册的应用程序的 Microsoft Entra 应用程序 ID（2 个实例）。	0edbblll-8773-44de-b87c-b8c6276d41eb
<friendly-name>	应用程序的用户定义的易记名称。	AppInitialization
<Tenant-GUID>	Microsoft Entra 租户的租户 ID	TenantID

现在，对应用程序进行最终生成并解决所有错误。代码应成功生成。

后续步骤

完成初始化代码后，接下来可以开始学习下一个快速入门，你将开始了解 MIP 文件 SDK。

列出敏感度标签

通过

快速入门：客户端应用程序初始化 (C#)

先决条件

创建 Visual Studio 解决方案和项目

实现身份验证委托

初始化 MIP SDK 托管包装器

构造文件配置文件和引擎

后续步骤

反馈

其他资源

通过

快速入门：客户端应用程序初始化 (C#)

先决条件

创建 Visual Studio 解决方案和项目

实现身份验证委托

实现许可委托

初始化 MIP SDK 托管包装器

构造文件配置文件和引擎

后续步骤

反馈

其他资源