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

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

注意

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

先决条件

如果尚未完成,请确保:

创建 Visual Studio 解决方案和项目

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

  1. 打开 Visual Studio 2019,依次选择“文件”菜单、“新建”、“项目”。 在“新建项目”对话框中:

    • 在左侧窗格中的“已安装”下的“Visual C#”中,选择“Windows 桌面”。

    • 在中间窗格中,选择“控制台应用(.NET Framework)”

    • 在底部窗格中,对项目“名称”、“位置”和包含的“解决方案名称”进行相应更新。

    • 完成后,单击右下角的“确定”按钮。

      Visual Studio solution creation

  2. 将 MIP 文件 SDK 的 Nuget 包添加到项目:

    • 在“解决方案资源管理器”中,右键单击项目节点(直接在顶部/解决方案节点下方单击),然后选择“管理 NuGet 包...”
    • 当“NuGet 包管理器”选项卡在编辑器组选项卡区域中打开时:
      • 选择浏览
      • 在搜索框中输入“Microsoft.InformationProtection”。
      • 选择“Microsoft.InformationProtection.File”包。
      • 单击“安装”,然后在显示“预览更改”确认对话框时,单击“确定”。
  3. 重复上述步骤以添加 MIP 文件 SDK 包,但改为将“Microsoft.Identity.Client”添加到应用程序。

实现身份验证委托

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

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

  1. 在 Visual Studio 中右键单击项目名称,选择“添加”,然后选择“类”。

  2. 在“名称”字段中输入“AuthDelegateImplementation”。 单击“添加” 。

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

    using Microsoft.InformationProtection;
    using Microsoft.Identity.Client;
    
  4. 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。 ApplicationNameApplicationVersion 将出现在 Azure 信息保护分析报告中。

  5. 添加 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

  1. 通过在之前使用的相同的 Visual Studio“添加类”功能,将另一个类添加到项目中。 这次在“类名”字段中输入“ConsentDelegateImplementation”

  2. 现在更新“ConsentDelegateImpl.cs”以实现新许可委托类。Microsoft.InformationProtection 添加 using 语句,并将类设置为继承 IConsentDelegate

    class ConsentDelegateImplementation : IConsentDelegate
    {
         public Consent GetUserConsent(string url)
         {
              return Consent.Accept;
         }
    }
    
  3. 或者,尝试生成解决方案以确保其编译时没有错误。

初始化 MIP SDK 托管包装器

  1. 从解决方案资源管理器,打开项目中包含 Main() 方法实现的 .cs 文件。 该文件默认与包含它的项目同名,该名称在项目创建期间指定。

  2. 删除生成的 main() 实现。

  3. 托管包装器包括一个静态类 Microsoft.InformationProtection.MIP,用于初始化、创建 MipContext、加载配置文件和释放资源。 若要初始化文件 SDK 操作的包装器,请调用 MIP.Initialize(),传入 MipComponent.File 以加载文件操作所需的库。

  4. Program.csMain() 中添加以下内容,将 <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;
       }
  }
}
  1. 使用以下值替换粘贴的源代码中的占位符值:

    占位符 示例
    <application-id> 分配给在“MIP SDK 安装和配置”中注册的应用程序的 Microsoft Entra 应用程序 ID(2 个实例)。 0edbblll-8773-44de-b87c-b8c6276d41eb
    <friendly-name> 应用程序的用户定义的易记名称。 AppInitialization
    <Tenant-GUID> Microsoft Entra 租户的租户 ID TenantID
  2. 现在,对应用程序进行最终生成并解决所有错误。 代码应成功生成。

后续步骤

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