Microsoft.Azure.WebJobs.Extensions.SignalRService 1.7.0-beta.1

Prefix Reserved
This is a prerelease version of Microsoft.Azure.WebJobs.Extensions.SignalRService.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Microsoft.Azure.WebJobs.Extensions.SignalRService --version 1.7.0-beta.1                
NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.SignalRService -Version 1.7.0-beta.1                
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="Microsoft.Azure.WebJobs.Extensions.SignalRService" Version="1.7.0-beta.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Microsoft.Azure.WebJobs.Extensions.SignalRService --version 1.7.0-beta.1                
#r "nuget: Microsoft.Azure.WebJobs.Extensions.SignalRService, 1.7.0-beta.1"                
#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 Microsoft.Azure.WebJobs.Extensions.SignalRService as a Cake Addin
#addin nuget:?package=Microsoft.Azure.WebJobs.Extensions.SignalRService&version=1.7.0-beta.1&prerelease

// Install Microsoft.Azure.WebJobs.Extensions.SignalRService as a Cake Tool
#tool nuget:?package=Microsoft.Azure.WebJobs.Extensions.SignalRService&version=1.7.0-beta.1&prerelease                

Azure WebJobs SignalR Service client library for .NET

This extension provides functionality for accessing Azure SignalR Service from an Azure Function.

Getting started

Install the package

Install the SignalR Service client with NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.SignalRService

Prerequisites

  • Azure Subscription: To use Azure services, including Azure SignalR Service, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a free trial or use your Visual Studio Subscription benefits when you create an account.

  • Azure SignalR resource: To use SignalR Service client library you'll also need a Azure SignalR resource. If you are not familiar with creating Azure resources, you may wish to follow the step-by-step guide for creating a SignalR resource using the Azure portal. There, you can also find detailed instructions for using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM) templates to create a SignalR resource.

    To quickly create the needed SignalR resource in Azure and to receive a connection string for them, you can deploy our sample template by clicking:

    Deploy to Azure

    After the instance is deployed, open it in the portal and locate its Settings page. Change the Service Mode setting to Serverless.

    SignalR Service mode setting

Authenticate the client

In order for SignalR Service client to access SignalR resource, it will need to understand how to authenticate with it. The easiest means for doing so is to use a connection string which can be found in the Azure Portal or by using the Azure CLI / Azure PowerShell snippet below.

Azure CLI snippet:

az signalr key list -n <your-resource-name> -g <your-resource-group-name> --query primaryKey -o tsv

Azure PowerShell snippet:

Get-AzSignalRKey -ResourceGroupName <your-resource-name> -Name <your-resource-name>

The ConnectionStringSetting property of SignalR bindings (including SignalRAttribute, SignalRConnectionInfoAttribute, SignalRTriggerAttribute etc.) is used to specify the configuration property that stores the connection string. If not specified, the property AzureSignalRConnectionString is expected to contain the connection string.

For local development, use the local.settings.json file to store the connection string:

{
  "Values": {
    "<connection_name>": "<connection-string>"
  }
}

When deployed, use the application settings to set the connection string.

Key concepts

SignalR Service client vs SignalR client

SignalR Service client : It means this library. It provides SignalR server functionalities in a serverless style.

SignalR client : An opposite concept of SignalR server. See ASP.NET Core SignalR clients for more information.

SignalR connection info input binding

SignalRConnectionInfo input binding makes it easy to generate the token required for SignalR clients to initiate a connection to Azure SignalR Service.

Please follow the Azure SignalR Connection Info input binding tutorial to learn more about SignalR Connection Info input binding.

SignalR output binding

SignalR output binding allows :

  • send messages to all connections, to a connection, to a user, to a group.
  • add/remove connections/users in a group.

Please follow the Azure SignalR output binding to learn more about SignalR output binding.

SignalR trigger

The SignalR trigger allows a function to be executed when a message is sent to Azure SignalR Service.

Please follow the Azure SignalR trigger to learn more about SignalR trigger.

Supported scenarios

  • Negotiate for a SignalR client.
  • Manage group like add/remove a single user/connection in a group.
  • Send messages to a single user/connection, to a group, to all users/connections.
  • Use multiple Azure SignalR Service instances for resiliency and disaster recovery in Azure Functions. See details in Multiple Azure SignalR Service Instances Support in Azure Functions.

Examples

Negotiation for SignalR client

In order for a client to connect to SignalR, it needs to obtain the SignalR client hub URL and an access token. We call the process as "negotiation".

[FunctionName("Negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req,
    [SignalRConnectionInfo(HubName = "<hub_name>", UserId = "<user_id>")] SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

Broadcast individual messages

To broadcast messages to all the connections in a hub from a single Azure Function invocation you can apply the SignalR attribute to the function return value. The return value should be of type SignalRMessage.

[FunctionName("sendOneMessageWithReturnValueBinding")]
[return: SignalR(HubName = "<hub_name>")]
public static SignalRMessage SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req)
{
    return new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

You can also use an out parameter of type SignalRMessage.

[FunctionName("messages")]
public static void SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req, [SignalR(HubName = "<hub_name>")] out SignalRMessage message)
{
    message = new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

Broadcast multiple messages

To broadcast multiple messages to all the connections in a hub from a single Azure Function invocation you can apply the SignalR attribute to the IAsyncCollector<SignalRMessage> parameter.

[FunctionName("messages")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req,
    [SignalR(HubName = "<hub_name>")] IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
    new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    });
}

Sending messages to a connection, user or group

To send messages to a connection, user or group, the function is similar to broadcasting messages above, except that you specify ConnectionId, UserId or GroupName in the properties of SignalRMessage.

Here is an example to send messages to a user using return value binding.

[FunctionName("messages")]
[return: SignalR(HubName = "<hub_name>")]
public static SignalRMessage SendMessageToUser(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req)
{
    return new SignalRMessage
    {
        UserId = "<user_id>",
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

SignalR client connection trigger

To trigger a function when a SignalR client gets connected or disconnected, you can apply the SignalRTrigger attribute to the InvocationContext parameter.

Here is an example to log the connection ID when a SignalR client is connected. Make sure the second paramater of SignalRTrigger constructor is connections, which stands for the category of the trigger is connections. The third

[FunctionName("SignalRTest")]
public static void Run([SignalRTrigger("<hubName>", "connections", "connected")] InvocationContext invocationContext, ILogger logger)
{
    logger.LogInformation($"{invocationContext.ConnectionId} was connected.");
}

SignalR client message trigger

To trigger a function when a SignalR client sends a message, you can apply the SignalRTrigger attribute to the InvocationContext parameter, apply the SignalRParameter attribute to each parameter whose name matches the parameter name in your message.

Here is an example to log the message content when a SignalR client sends a message with target "SendMessage".

[FunctionName("SignalRTest")]
public static void Run([SignalRTrigger("SignalRTest", "messages", "SendMessage")] InvocationContext invocationContext, [SignalRParameter] string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

Troubleshooting

Next steps

Read the introduction to Azure Functions or creating an Azure Function guide

Contributing

See our CONTRIBUTING.md for details on building, testing, and contributing to this library.

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 is compatible.  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 is compatible. 
.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 (4)

Showing the top 4 NuGet packages that depend on Microsoft.Azure.WebJobs.Extensions.SignalRService:

Package Downloads
Fathym.LCU.Services.StateAPIs.Durable

The Fathym LCU Services StateAPIs projects provide the foundation for building Fathym's dotnet applications.

FunctionMonkey.SignalR

Package Description

FunctionMonkey.SignalR.Cgo

Package Description

Tzn.Operations.Executor

Operations SDK functions

GitHub repositories (8)

Showing the top 5 popular GitHub repositories that depend on Microsoft.Azure.WebJobs.Extensions.SignalRService:

Repository Stars
Azure-Samples/Serverless-microservices-reference-architecture
This reference architecture walks you through the decision-making process involved in designing, developing, and delivering a serverless application using a microservices architecture through hands-on instructions for configuring and deploying all of the architecture's components along the way. The goal is to provide practical hands-on experience in working with several Azure services and the technologies that effectively use them in a cohesive and unified way to build a serverless-based microservices architecture.
rstropek/Samples
JamesRandall/FunctionMonkey
Write more elegant Azure Functions with less boilerplate, more consistency, and support for REST APIs. Docs can be found at https://functionmonkey.azurefromthetrenches.com
ProfessionalCSharp/MoreSamples
Additional code samples the book series Professional C#, Wrox Press
PlayFab/PlayFab-Samples
This repository contains Sample code, Recipes and Video Tutorials demonstrating how to integrate various PlayFab features
Version Downloads Last updated
1.14.0 193,830 5/31/2024
1.13.0 283,936 2/4/2024
1.12.0 206,721 11/15/2023
1.11.2 132,612 9/15/2023
1.11.1 14,535 9/12/2023
1.11.0 145,770 6/21/2023
1.10.0 172,745 4/11/2023
1.9.0 220,042 1/12/2023
1.8.0 897,856 4/7/2022
1.7.0 404,552 2/22/2022
1.7.0-beta.2 1,531 2/14/2022
1.7.0-beta.1 16,109 12/7/2021
1.6.0 222,938 9/16/2021
1.5.0 162,720 7/16/2021
1.4.2 59,041 6/16/2021
1.4.1 41,173 5/25/2021
1.4.0 35,770 5/12/2021
1.3.0 90,697 3/23/2021
1.2.2 738,703 9/29/2020
1.2.1 13,841 9/18/2020
1.2.0 326,503 6/2/2020
1.1.0 166,138 3/17/2020
1.0.2 238,355 11/4/2019
1.0.1 79,276 7/31/2019
1.0.1-preview1-10095 1,015 6/11/2019
1.0.0 190,460 2/27/2019
1.0.0-preview1-10025 67,821 11/19/2018
1.0.0-preview1-10002 11,649 9/17/2018