Azure.Communication.Common 1.3.0

Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Azure.Communication.Common --version 1.3.0                
NuGet\Install-Package Azure.Communication.Common -Version 1.3.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Azure.Communication.Common" Version="1.3.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.Communication.Common --version 1.3.0                
#r "nuget: Azure.Communication.Common, 1.3.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Azure.Communication.Common as a Cake Addin
#addin nuget:?package=Azure.Communication.Common&version=1.3.0

// Install Azure.Communication.Common as a Cake Tool
#tool nuget:?package=Azure.Communication.Common&version=1.3.0                

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

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

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.

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 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.

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (7)

Showing the top 5 NuGet packages that depend on Azure.Communication.Common:

Package Downloads
Azure.Communication.Identity

This client library enables working with the Microsoft Azure Communication Identity service. For this release, see notes - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Identity/README.md and https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Identity/CHANGELOG.md. Microsoft Azure Communication Identity quickstart - https://docs.microsoft.com/azure/communication-services/quickstarts/access-tokens?pivots=programming-language-csharp

Azure.Communication.Chat

This client library enables working with the Microsoft Azure Communication Chat service. For this release, see notes - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Chat/README.md and https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Chat/CHANGELOG.md. Microsoft Azure Communication Chat quickstart - https://docs.microsoft.com/azure/communication-services/quickstarts/chat/get-started?pivots=programming-language-csharp

Azure.Communication.NetworkTraversal

This client library enables working with the Microsoft Azure Communication Network Traversal service. For this release, see notes - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.NetworkTraversal/README.md and https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.NetworkTraversal/CHANGELOG.md.

Azure.Communication.Rooms

This Client library enables working with the Microsoft Azure Communication Rooms Service.

Azure.Communication.CallingServer

This client library enables working with the Microsoft Azure Communication CallingServer service. For this release, see notes - https://github.com/Azure/azure-sdk-for-net-pr/blob/main/sdk/communication/Azure.Communication.ServerCalling/README.md and https://github.com/Azure/azure-sdk-for-net-pr/blob/main/sdk/communication/Azure.Communication.ServerCalling/CHANGELOG.md.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Azure.Communication.Common:

Repository Stars
Azure/azure-sdk-for-net
This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.
Version Downloads Last updated
2.0.0-beta.1 3,161 3/29/2023
1.3.0 120,869 2/13/2024
1.2.1 287,491 11/1/2022
1.2.0 386,790 9/2/2022
1.1.0 117,673 2/23/2022
1.0.1 363,969 5/25/2021
1.0.0 367,751 3/29/2021
1.0.0-beta.5 2,889 3/10/2021
1.0.0-beta.4 4,409 2/10/2021
1.0.0-beta.3 56,493 11/16/2020
1.0.0-beta.2 160,162 10/6/2020
1.0.0-beta.1 14,567 9/22/2020