你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 通信通用客户端库 - 版本 1.2.1

项目
04/19/2023

此包包含 Azure 通信服务库的通用代码。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 通信通用客户端库。

dotnet add package Azure.Communication.Common

先决条件

需要 Azure 订阅和通信服务资源才能使用此包。

若要创建新的通信服务，可以使用 Azure 门户、Azure PowerShell或 .NET 管理客户端库。

验证客户端

此模块不包含客户端，而是包含可帮助其他 Azure 通信客户端进行身份验证的库。

关键概念

CommunicationTokenCredential

对象 CommunicationTokenCredential 用于通过通信服务（如聊天或通话）对用户进行身份验证。可以选择性地提供自动刷新机制，以确保在通信期间持续稳定的身份验证状态。

根据你的方案，可能需要使用以下项初始化 CommunicationTokenCredential ：

适用于短期客户端的静态令牌 (，例如) 发送一次性聊天消息或
一个回调函数，可确保持续身份验证状态 (理想状态，例如，对于长时间的调用会话) 。

可以使用 Azure 通信标识库获取通过构造函数或令牌刷新器回调提供给 CommunicationTokenCredential 的令牌。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且相互独立， (准则) 。这可确保重用客户端实例的建议始终是安全的，即使跨线程也是如此。

其他概念

示例

使用静态令牌创建凭据

对于生存期较短的客户端，不需要在过期时刷新令牌，可以使用 CommunicationTokenCredential 静态令牌进行实例化。

string token = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_USER_TOKEN");
using var tokenCredential = new CommunicationTokenCredential(token);

使用回调创建凭据

或者，对于生存期较长的客户端，可以使用回调创建， CommunicationTokenCredential 以便在令牌过期时续订令牌。在这里，我们传递两个想象中的函数，这些函数发出网络请求以检索用户 Bob 的令牌字符串。如果传递回调，则请求 (发送聊天消息) 时， CommunicationTokenCredential 请确保在执行请求之前获取有效的令牌。该方法必须 FetchTokenForUserFromMyServer 返回一个有效的令牌 (，并在将来) 随时设置到期日期。

（可选）可以启用主动令牌刷新，在上一个令牌即将过期后立即获取新令牌。使用此方法时，请求不太可能被阻止来获取新令牌：

using var tokenCredential = new CommunicationTokenCredential(
    new CommunicationTokenRefreshOptions(
        refreshProactively: true, // Indicates if the token should be proactively refreshed in the background or only on-demand
        tokenRefresher: cancellationToken => FetchTokenForUserFromMyServer("bob@contoso.com", cancellationToken))
    {
        AsyncTokenRefresher = cancellationToken => FetchTokenForUserFromMyServerAsync("bob@contoso.com", cancellationToken)
    });

如果已有令牌，可以通过传递该初始令牌来进一步优化令牌刷新：

string initialToken = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_USER_TOKEN");
using var tokenCredential = new CommunicationTokenCredential(
    new CommunicationTokenRefreshOptions(
       refreshProactively: true, // Indicates if the token should be proactively refreshed in the background or only on-demand
       tokenRefresher: cancellationToken => FetchTokenForUserFromMyServer("bob@contoso.com", cancellationToken))
    {
        AsyncTokenRefresher = cancellationToken => FetchTokenForUserFromMyServerAsync("bob@contoso.com", cancellationToken),
        InitialToken = initialToken
    });

疑难解答

主动刷新失败发生在后台线程中，为了避免使应用崩溃，异常将以无提示方式进行处理。使用其他客户端（例如聊天）的请求期间，将发生所有其他故障，你可以在其中使用 RequestFailedException捕获异常。

后续步骤

阅读有关通信用户访问令牌的详细信息

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过