Azure Web PubSub output binding for Azure Functions

Choose a programming language

C# Java JavaScript PowerShell Python

Use the Web PubSub output binding to invoke Azure Web PubSub service to do something. You can send a message to:

• All connected clients
• Connected clients authenticated to a specific user
• Connected clients joined in a specific group
• A specific client connection

The output binding also allows you to manage clients and groups, and grant/revoke permissions targeting specific connectionId with group.

• Add connection to group
• Add user to group
• Remove connection from a group
• Remove user from a group
• Remove user from all groups
• Close all client connections
• Close a specific client connection
• Close connections in a group
• Grant permission of a connection
• Revoke permission of a connection

For information on setup and configuration details, see the overview.

Example

Isolated worker model

[Function("WebPubSubOutputBinding")]
[WebPubSubOutput(Hub = "<hub>", Connection = "<web_pubsub_connection_name>")]
public static WebPubSubAction Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req)
{
    return new SendToAllAction
    {
        Data = BinaryData.FromString("Hello Web PubSub!"),
        DataType = WebPubSubDataType.Text
    };
}

In-process model

[FunctionName("WebPubSubOutputBinding")]
public static async Task RunAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSub(Hub = "<hub>")] IAsyncCollector<WebPubSubAction> actions)
{
    await actions.AddAsync(WebPubSubAction.CreateSendToAllAction("Hello Web PubSub!", WebPubSubDataType.Text));
}

const { app, output } = require('@azure/functions');
const wpsMsg = output.generic({
    type: 'webPubSub',
    name: 'actions',
    hub: '<hub>',
});

app.http('message', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [wpsMsg],
    handler: async (request, context) => {
        context.extraOutputs.set(wpsMsg, [{
            "actionName": "sendToAll",
            "data": `Hello world`,
            "dataType": `text`
        }]);
    }
});

Define bindings in functions.json.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSub",
      "name": "actions",
      "hub": "<hub>",
      "direction": "out"
    }
  ]
}

Define function in index.js.

module.exports = async function (context) {
  context.bindings.actions = {
    "actionName": "sendToAll",
    "data": "Hello world",
    "dataType": "text"
  };
  context.done();
}

Note

Complete samples for this language are pending

Note

The Web PubSub extensions for Java is not supported yet.

WebPubSubAction

WebPubSubAction is the base abstract type of output bindings. The derived types represent the action server want service to invoke.

In C# language, we provide a few static methods under WebPubSubAction to help discover available actions. For example, user can create the SendToAllAction by call WebPubSubAction.CreateSendToAllAction().

Derived Class	Properties
SendToAllAction	Data, DataType, Excluded
SendToGroupAction	Group, Data, DataType, Excluded
SendToUserAction	UserId, Data, DataType
SendToConnectionAction	ConnectionId, Data, DataType
AddUserToGroupAction	UserId, Group
RemoveUserFromGroupAction	UserId, Group
RemoveUserFromAllGroupsAction	UserId
AddConnectionToGroupAction	ConnectionId, Group
RemoveConnectionFromGroupAction	ConnectionId, Group
CloseAllConnectionsAction	Excluded, Reason
CloseClientConnectionAction	ConnectionId, Reason
CloseGroupConnectionsAction	Group, Excluded, Reason
GrantPermissionAction	ConnectionId, Permission, TargetName
RevokePermissionAction	ConnectionId, Permission, TargetName

actionName is the key parameter to resolve the type. Available actions are listed as follows.

ActionName	Properties
sendToAll	Data, DataType, Excluded
sendToGroup	Group, Data, DataType, Excluded
sendToUser	UserId, Data, DataType
sendToConnection	ConnectionId, Data, DataType
addUserToGroup	UserId, Group
removeUserFromGroup	UserId, Group
removeUserFromAllGroups	UserId
addConnectionToGroup	ConnectionId, Group
removeConnectionFromGroup	ConnectionId, Group
closeAllConnections	Excluded, Reason
closeClientConnection	ConnectionId, Reason
closeGroupConnections	Group, Excluded, Reason
grantPermission	ConnectionId, Permission, TargetName
revokePermission	ConnectionId, Permission, TargetName

Important

The message data property in the sent message related actions must be string if data type is set to json or text to avoid data conversion ambiguity. Please use JSON.stringify() to convert the json object in need. This is applied to any place using message property, for example, UserEventResponse.Data working with WebPubSubTrigger.

When data type is set to binary, it's allowed to leverage binding naturally supported dataType as binary configured in the function.json, see Trigger and binding definitions for details.

Configuration

The following table explains the binding configuration properties that you set in the function.json file and the WebPubSub attribute.

function.json property	Attribute property	Description
type	n/a	Must be set to webPubSub
direction	n/a	Must be set to out
name	n/a	Variable name used in function code for output binding object.
hub	Hub	The value must be set to the name of the Web PubSub hub for the function to be triggered. We support set the value in attribute as higher priority, or it can be set in app settings as a global value.
connection	Connection	The name of the app setting that contains the Web PubSub Service connection string (defaults to "WebPubSubConnectionString").

Important

For optimal security, your function app should use managed idenities when connecting to the Web PubSub service instead of using a connection string, which contains a shared secret key. For more information, see Authorize a managed identity request by using Microsoft Entra ID.

Troubleshooting

Setting up console logging

You can also easily enable console logging if you want to dig deeper into the requests you're making against the service.