This library provides base types for other Microsoft Azure Communication client libraries.
For this release, see notes - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Common/README.md and https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Common/CHANGELOG.md.
This module does not contain a client and instead libraries that help other Azure Communication clients authenticate.
Key concepts
CommunicationTokenCredential
The CommunicationTokenCredential object is used to authenticate 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.
Depending on your scenario, you may want to initialize the CommunicationTokenCredential with:
a static token (suitable for short-lived clients used to e.g. send one-off Chat messages) or
a callback function that ensures a continuous authentication state (ideal e.g. for long Calling sessions).
The tokens supplied to the CommunicationTokenCredential either through the constructor or via the token refresher callback can be obtained using the Azure Communication Identity library.
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.
For short-lived clients, refreshing the token upon expiry is not necessary and CommunicationTokenCredential may be instantiated with a static token.
string token = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_USER_TOKEN");
using var tokenCredential = new CommunicationTokenCredential(token);
Create a credential with a callback
Alternatively, for long-lived clients, you can create a CommunicationTokenCredential with a 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.
It's necessary that the FetchTokenForUserFromMyServer method returns a valid token (with an expiration date set in the future) at all times.
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 = 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.
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.