快速入门:客户端应用程序初始化 (C#)
本快速入门将介绍如何实现 MIP SDK .NET 包装器在运行时使用的客户端初始化模式。
注意
本快速入门中概述的步骤对于使用 MIP .NET 包装器文件、策略或保护 SDK 的任何客户端应用程序都是必需的。 尽管本快速入门介绍的是文件 SDK 的用法,但使用策略和保护 SDK 的客户端也适用同样的模式。 未来的快速入门应该连续完成,因为其中的每个快速入门都以前一个为基础,下面开始第一个快速入门。 此代码旨在演示如何开始使用 MIP SDK,不应将其用于生产目的。
先决条件
如果尚未完成,请确保:
- 完成 Microsoft 信息保护 (MIP) SDK 安装和配置中的步骤。 此“客户端应用程序初始化”快速入门需要先正确安装和配置 SDK。
- 可选:
创建 Visual Studio 解决方案和项目
首先,创建并配置初始 Visual Studio 解决方案和项目,其他快速入门将以此为基础。
打开 Visual Studio 2019,依次选择“文件”菜单、“新建”、“项目”。 在“新建项目”对话框中:
将 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。