Azure Functions 的 SignalR 服務輸出系結

使用 SignalR 輸出系結，使用 Azure SignalR 服務傳送一或多個訊息。 您可以將訊息廣播至：

  • 所有已連線的用戶端
  • 指定群組中的已連線用戶端
  • 將以驗證的用戶端連線至特定使用者

輸出系結也可讓您管理群組，例如將用戶端或使用者新增至群組、從群組中移除客戶端或使用者。

如需安裝和組態詳細數據的詳細資訊，請參閱概 觀。

範例

廣播到所有用戶端

您可以使用下列其中一種 C# 模式來建立 C# 函式：

  • 隔離的背景工作模型：在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 需要隔離的背景工作進程，才能支援在 .NET 和 .NET Framework 的長期支援 （LTS） 和非 LTS 版本上執行的 C# 函式。
  • 同進程模型：在與 Azure Functions 運行時間相同的進程中執行的已編譯 C# 函式。
  • C# 文稿：主要是在 Azure 入口網站 中建立 C# 函式時使用。

重要

內含式模型支援將於 2026 年 11 月 10 日結束。 強烈建議您將應用程式移轉至隔離式背景工作角色模型，以取得完整支援。

下列範例顯示使用輸出系結傳送訊息給所有已連線用戶端的函式。 newMessage 是每個用戶端上要叫用的方法名稱。

[Function(nameof(BroadcastToAll))]
[SignalROutput(HubName = "chat", ConnectionStringSetting = "SignalRConnection")]
public static SignalRMessageAction BroadcastToAll([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req)
{
    using var bodyReader = new StreamReader(req.Body);
    return new SignalRMessageAction("newMessage")
    {
        // broadcast to all the connected clients without specifying any connection, user or group.
        Arguments = new[] { bodyReader.ReadToEnd() },
    };
}

以下是 function.json 檔案中的繫結資料：

function.json 範例：

{
  "type": "signalR",
  "name": "signalROutput",
  "hubName": "hubName1",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

const { app, output } = require('@azure/functions');

const signalR = output.generic({
    type: 'signalR',
    name: 'signalR',
    hubName: 'hub',
    connectionStringSetting: 'AzureSignalRConnectionString',
});

// You can use any other trigger type instead.
app.http('broadcast', {
    methods: ['GET'],
    authLevel: 'anonymous',
    extraOutputs: [signalR],
    handler: (request, context) => {
        context.extraOutputs.set(signalR, {
            "target": "newMessage",
            "arguments": [request.body]
        });
    }
});

完整的 PowerShell 範例擱置中。

以下是 Python 程式碼：

def main(req: func.HttpRequest, signalROutput: func.Out[str]) -> func.HttpResponse:
    message = req.get_json()
    signalROutput.set(json.dumps({
        'target': 'newMessage',
        'arguments': [ message ]
    }))

@FunctionName("sendMessage")
@SignalROutput(name = "$return", HubName = "hubName1")
public SignalRMessage sendMessage(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req) {

    SignalRMessage message = new SignalRMessage();
    message.target = "newMessage";
    message.arguments.add(req.getBody());
    return message;
}

傳送給使用者

您可以藉由設定 SignalR Service 訊息的使用者識別碼，僅將訊息傳送給已對使用者驗證的連線。

[Function(nameof(SendToUser))]
[SignalROutput(HubName = "chat", ConnectionStringSetting = "SignalRConnection")]
public static SignalRMessageAction SendToUser([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req)
{
    using var bodyReader = new StreamReader(req.Body);
    return new SignalRMessageAction("newMessage")
    {
        Arguments = new[] { bodyReader.ReadToEnd() },
        UserId = "userToSend",
    };
}

以下是 function.json 檔案中的繫結資料：

function.json 範例：

{
  "type": "signalR",
  "name": "signalROutput",
  "hubName": "hubName1",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

完整的 PowerShell 範例擱置中。

以下是 Python 程式碼：

def main(req: func.HttpRequest, signalROutput: func.Out[str]) -> func.HttpResponse:
    message = req.get_json()
    signalROutput.set(json.dumps({
        #message will only be sent to this user ID
        'userId': 'userId1',
        'target': 'newMessage',
        'arguments': [ message ]
    }))

@FunctionName("sendMessage")
@SignalROutput(name = "$return", HubName = "hubName1")
public SignalRMessage sendMessage(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req) {

    SignalRMessage message = new SignalRMessage();
    message.userId = "userId1";
    message.target = "newMessage";
    message.arguments.add(req.getBody());
    return message;
}

const { app, output } = require('@azure/functions');

const signalR = output.generic({
    type: 'signalR',
    name: 'signalR',
    hubName: 'hub',
    connectionStringSetting: 'AzureSignalRConnectionString',
});

app.http('sendToUser', {
    methods: ['GET'],
    authLevel: 'anonymous',
    extraOutputs: [signalR],
    handler: (request, context) => {
        context.extraOutputs.set(signalR, {
            "target": "newMessage",
            "arguments": [request.body],
            "userId": "userId1",
        });
    }
});

傳送至群組

您可以藉由設定 SignalR Service 訊息的群組名稱，僅將訊息傳送給已新增至群組的連線。

[Function(nameof(SendToGroup))]
[SignalROutput(HubName = "chat", ConnectionStringSetting = "SignalRConnection")]
public static SignalRMessageAction SendToGroup([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req)
{
    using var bodyReader = new StreamReader(req.Body);
    return new SignalRMessageAction("newMessage")
    {
        Arguments = new[] { bodyReader.ReadToEnd() },
        GroupName = "groupToSend"
    };
}

以下是 function.json 檔案中的繫結資料：

function.json 範例：

{
  "type": "signalR",
  "name": "signalROutput",
  "hubName": "hubName1",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

const { app, output } = require('@azure/functions');

const signalR = output.generic({
    type: 'signalR',
    name: 'signalR',
    hubName: 'hub',
    connectionStringSetting: 'AzureSignalRConnectionString',
});

app.http('sendToGroup', {
    methods: ['GET'],
    authLevel: 'anonymous',
    extraOutputs: [signalR],
    handler: (request, context) => {
        context.extraOutputs.set(signalR, {
            "target": "newMessage",
            "arguments": [request.body],
            "groupName": "myGroup",
        });
    }
});

完整的 PowerShell 範例擱置中。

以下是 Python 程式碼：

def main(req: func.HttpRequest, signalROutput: func.Out[str]) -> func.HttpResponse:
    message = req.get_json()
    signalROutput.set(json.dumps({
        #message will only be sent to this group
        'groupName': 'myGroup',
        'target': 'newMessage',
        'arguments': [ message ]
    }))

@FunctionName("sendMessage")
@SignalROutput(name = "$return", HubName = "hubName1")
public SignalRMessage sendMessage(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req) {

    SignalRMessage message = new SignalRMessage();
    message.groupName = "myGroup";
    message.target = "newMessage";
    message.arguments.add(req.getBody());
    return message;
}

群組管理

SignalR Service 允許使用者或連線新增至群組。 訊息可以接著傳送至群組。 您可以使用 SignalR 輸出繫結來管理群組。

指定 SignalRGroupActionType 以新增或移除成員。 下列範例會從群組中移除使用者。

[Function(nameof(RemoveFromGroup))]
[SignalROutput(HubName = "chat", ConnectionStringSetting = "SignalRConnection")]
public static SignalRGroupAction RemoveFromGroup([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req)
{
    return new SignalRGroupAction(SignalRGroupActionType.Remove)
    {
        GroupName = "group1",
        UserId = "user1"
    };
}

注意

若要正確 ClaimsPrincipal 系結，您必須已在 Azure Functions 中設定驗證設定。

以下是 function.json 檔案中的繫結資料：

function.json 範例：

{
  "type": "signalR",
  "name": "signalROutput",
  "hubName": "hubName1",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

const { app, output } = require('@azure/functions');

const signalR = output.generic({
    type: 'signalR',
    name: 'signalR',
    hubName: 'hub',
    connectionStringSetting: 'AzureSignalRConnectionString',
});

// The following function adds a user to a group
app.http('addUserToGroup', {
    methods: ['POST'],
    authLevel: 'anonymous',
    extraOutputs: [signalR],
    handler: (request, context) => {
        context.extraOutputs.set(signalR, {
            "userId": req.query.userId,
            "groupName": "myGroup",
            "action": "add"
        });
    }
});

// The following function removes a user from a group
app.http('removeUserFromGroup', {
    methods: ['POST'],
    authLevel: 'anonymous',
    extraOutputs: [signalR],
    handler: (request, context) => {
        context.extraOutputs.set(signalR, {
            "userId": req.query.userId,
            "groupName": "myGroup",
            "action": "remove"
        });
    }
});

完整的 PowerShell 範例擱置中。

下列範例會將使用者新增至群組。

def main(req: func.HttpRequest, signalROutput: func.Out[str]) -> func.HttpResponse:
    signalROutput.set(json.dumps({
        'userId': 'userId1',
        'groupName': 'myGroup',
        'action': 'add'
    }))

下列範例會從群組中移除使用者。

def main(req: func.HttpRequest, signalROutput: func.Out[str]) -> func.HttpResponse:
    signalROutput.set(json.dumps({
        'userId': 'userId1',
        'groupName': 'myGroup',
        'action': 'remove'
    }))

下列範例會將使用者新增至群組。

@FunctionName("addToGroup")
@SignalROutput(name = "$return", HubName = "hubName1")
public SignalRGroupAction addToGroup(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req,
        @BindingName("userId") String userId) {

    SignalRGroupAction groupAction = new SignalRGroupAction();
    groupAction.action = "add";
    groupAction.userId = userId;
    groupAction.groupName = "myGroup";
    return action;
}

下列範例會從群組中移除使用者。

@FunctionName("removeFromGroup")
@SignalROutput(name = "$return", HubName = "hubName1")
public SignalRGroupAction removeFromGroup(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req,
        @BindingName("userId") String userId) {

    SignalRGroupAction groupAction = new SignalRGroupAction();
    groupAction.action = "remove";
    groupAction.userId = userId;
    groupAction.groupName = "myGroup";
    return action;
}

屬性

進程內和隔離的背景工作進程 C# 連結庫都會使用 屬性來定義函式。 C# 文稿會改用 function.json組態檔。

下表說明 屬性的屬性 SignalROutput 。

屬性內容 描述
HubName 此值必須設定為產生連接資訊的 SignalR 中樞名稱。
ConnectionStringSetting 包含 SignalR Service 連接字串 的應用程式設定或設定集合名稱，預設為 AzureSignalRConnectionString。

註釋

下表說明批注支持的設定 SignalROutput 。

設定 描述
名字 用於連接資訊物件的函式程式代碼中的變數名稱。
hubName 此值必須設定為產生連接資訊的 SignalR 中樞名稱。
connectionStringSetting 包含 SignalR Service 連接字串 的應用程式設定或設定集合名稱，預設為 AzureSignalRConnectionString。

組態

下表說明您在 function.json 檔案中設定的繫結設定屬性。

function.json 屬性 描述
類型 必須設定為 signalR。
方向 必須設定為 out。
名字 用於連接資訊物件的函式程式代碼中的變數名稱。
hubName 此值必須設定為產生連接資訊的 SignalR 中樞名稱。
connectionStringSetting 包含 SignalR Service 連接字串 的應用程式設定或設定集合名稱，預設為 AzureSignalRConnectionString。

當您在本機開發時，請在集合中的 local.settings.json 檔案Values中新增應用程式設定。

使用方式

連結

該connectionStringSetting屬性在應用程式設定中被設定為一個鍵，回傳一個由 Functions 執行時用來連接 Azure SignalR Service 實例的值。 此連接屬性設定的值取決於連接類型：

  • 管理身份連線：此 connectionStringSetting 屬性是由 <CONNECTION_NAME_PREFIX> 一組設定共享，這些設定共同定義了與服務端點的身份基礎連線。 欲了解更多資訊，請參閱定義身份連結。
  • 金鑰保存庫 參考：connectionStringSetting屬性設定會回傳一個 Azure Key Vault 的參考，指向該 連接字串 集中維護的位置。 欲了解更多資訊，請參閱定義 金鑰保存庫 連接。
  • App Configuration 參考：connectionStringSetting屬性設定回傳一個 Azure 應用程式組態 參考，該參考會回傳一個 連接字串 或 金鑰保存庫 參考。 欲了解更多資訊，請參閱連接條目中的 Azure 應用程式組態。
  • Connection string：屬性設定回connectionStringSetting傳實際的 SignalR 服務 連接字串。 由於 連接字串 包含共享的秘密金鑰，建議在可能的情況下使用管理身份連線。 欲了解更多資訊，請參閱定義連結。

想了解更多關於綁定連接的資訊，請參閱 Azure Functions 中的「管理連線」。 要取得 連接字串，請依照 How to get 連接字串s 中的步驟操作。

功能主機在連接 SignalR 服務時會尋找一個金鑰或金 AzureSignalRConnectionString 鑰前綴。 否則，它會利用設定在 中的 connectionStringSetting 鍵值來取得所需的連接資訊。

下一步

  • 上次更新時間：