Azure Communication Common client library for .NET
This package contains common code for Azure Communication Service libraries.
Source code | Package (NuGet) | Product documentation
Getting started
Install the package
Install the Azure Communication Common client library for .NET with NuGet.
dotnet add package Azure.Communication.Common --version 1.0.0-beta.4
Prerequisites
You need an Azure subscription and a Communication Service Resource to use this package.
To create a new Communication Service, you can use the Azure Portal, the Azure PowerShell, or the .NET management client library.
Authenticate the client
This module does not contain a client and instead libraries that help other Azure Communication clients authenticate.
Key concepts
CommunicationTokenCredential
CommunicationTokenCredential
authenticates a user with Communication Services, such as Chat or Calling. It optionally provides an auto-refresh mechanism to ensure a continuously stable authentication state during communications.
It is up to you the developer to first create valid user tokens with the Communication Administration SDK. Then you use these tokens with the CommunicationTokenCredential
.
Thread safety
We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.
Additional concepts
Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime
Examples
Create a credential with a static token
For a short-lived clents when refreshing token upon expiry is not needed, CommunicationTokenCredential
can be instantited with a static token.
string token = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_USER_TOKEN");
using var tokenCredential = new CommunicationTokenCredential(token);
Alternatively, you can create a CommunicationTokenCredential
with callback to renew tokens if expired.
Here we pass two imagined functions that make network requests to retrieve token strings for user Bob.
If callbacks are passed, upon requests (sending a chat message), CommunicationTokenCredential
ensures
that a valid token is acquired prior to executing the request.
Optionally, you can enable proactive token refreshing where a fresh token will be acquired as soon as the previous token approaches expiry. Using this method, your requests are less likely to be blocked to acquire a fresh 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)
)
);
If you already have a token, you can optimize the token refreshing even further by passing that initial token:
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)
);
Troubleshooting
The proactive refreshing failures happen in a background thread and to avoid crashing your app the exceptions will be silently handled.
All the other failures will happen during your request using other clients such as chat where you can catch the exception using RequestFailedException
.
Next steps
Read more about Communication user access tokens
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.