Share via

Azure WebJobs SignalR Service Clientbibliothek für .NET– Version 1.11.2

  • Artikel

Diese Erweiterung bietet Funktionen für den Zugriff auf Azure SignalR Service über eine Azure-Funktion.

Erste Schritte

Installieren des Pakets

Installieren Sie den SignalR Service-Client mit NuGet:

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

Voraussetzungen

  • Azure-Abonnement: Für die Verwendung von Azure-Diensten, einschließlich Azure SignalR Service, benötigen Sie ein Abonnement. Wenn Sie nicht über ein vorhandenes Azure-Konto verfügen, können Sie sich für eine kostenlose Testversion registrieren oder Ihre Visual Studio-Abonnementvorteile nutzen, wenn Sie ein Konto erstellen.

  • Azure SignalR-Ressource: Um SignalR Service Clientbibliothek verwenden zu können, benötigen Sie auch eine Azure SignalR-Ressource. Wenn Sie mit dem Erstellen von Azure-Ressourcen nicht vertraut sind, können Sie die Schritt-für-Schritt-Anleitung zum Erstellen einer SignalR-Ressource mithilfe des Azure-Portal befolgen. Dort finden Sie auch ausführliche Anweisungen zur Verwendung der Azure CLI-, Azure PowerShell- oder Arm-Vorlagen (Azure Resource Manager) zum Erstellen einer SignalR-Ressource.

    Um schnell die erforderliche SignalR-Ressource in Azure zu erstellen und eine Verbindungszeichenfolge für sie zu erhalten, können Sie unsere Beispielvorlage bereitstellen, indem Sie auf Folgendes klicken:

    Bereitstellen in Azure

    Nachdem die Instanz bereitgestellt wurde, öffnen Sie sie im Portal, und navigieren Sie zur Seite „Einstellungen“. Ändern Sie die Einstellung des Dienstmodus in Serverlos.

    Einstellung für den SignalR Service-Modus

Authentifizieren des Clients

Damit SignalR Service Client auf die SignalR-Ressource zugreifen kann, muss er wissen, wie er sich mit ihr authentifiziert. Die einfachste Möglichkeit hierfür ist die Verwendung einer Verbindungszeichenfolge, die im Azure-Portal oder mithilfe der Azure CLI / zu finden ist Azure PowerShell Ausschnitt unten.

Azure CLI-Codeausschnitt:

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

Azure PowerShell Codeausschnitt:

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

Die ConnectionStringSetting -Eigenschaft von SignalR-Bindungen (einschließlich SignalRAttribute, SignalRConnectionInfoAttributeusw SignalRTriggerAttribute .) wird verwendet, um die Konfigurationseigenschaft anzugeben, die die Verbindungszeichenfolge speichert. Wenn nicht angegeben, wird erwartet, dass die -Eigenschaft AzureSignalRConnectionString die Verbindungszeichenfolge enthält.

Verwenden Sie für die lokale Entwicklung die local.settings.json -Datei, um die Verbindungszeichenfolge zu speichern:

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

Verwenden Sie nach der Bereitstellung die Anwendungseinstellungen , um die Verbindungszeichenfolge festzulegen.

Wichtige Begriffe

SignalR Service-Client im Vergleich zu SignalR-Client

SignalR Service-Client : Dies bedeutet diese Bibliothek. Es stellt SignalR-Serverfunktionen in einem serverlosen Stil bereit.

SignalR-Client: Ein entgegengesetztes Konzept des SignalR-Servers. Weitere Informationen finden Sie unter ASP.NET Core SignalR-Clients.

SignalR-Verbindungsinfo-Eingabebindung

SignalRConnectionInfoDie Eingabebindung erleichtert das Generieren des Tokens, das für SignalR-Clients zum Initiieren einer Verbindung mit Azure SignalR Service erforderlich ist.

Befolgen Sie das Tutorial zur Eingabebindung für Azure SignalR-Verbindungsinformationen , um mehr über die SignalR-Verbindungsinfo-Eingabebindung zu erfahren.

SignalR-Ausgabebindung

SignalR Die Ausgabebindung ermöglicht :

  • Senden von Nachrichten an alle Verbindungen, an eine Verbindung, an einen Benutzer, an eine Gruppe.
  • Verbindungen/Benutzer in einer Gruppe hinzufügen/entfernen.

Befolgen Sie die Azure SignalR-Ausgabebindung , um mehr über die SignalR-Ausgabebindung zu erfahren.

SignalR-Trigger

Der SignalR-Trigger ermöglicht die Ausführung einer Funktion, wenn eine Nachricht an Azure SignalR Service gesendet wird.

Befolgen Sie den Azure SignalR-Trigger , um weitere Informationen zum SignalR-Trigger zu erhalten.

Unterstützte Szenarien

  • Verhandeln für einen SignalR-Client.
  • Verwalten Sie eine Gruppe, z. B. hinzufügen/entfernen Sie einen einzelnen Benutzer/eine einzelne Verbindung in einer Gruppe.
  • Senden von Nachrichten an einen einzelnen Benutzer/eine einzelne Verbindung, an eine Gruppe, an alle Benutzer/Verbindungen.
  • Verwenden Sie mehrere Azure SignalR Service Instanzen für Resilienz und Notfallwiederherstellung in Azure Functions. Weitere Informationen finden Sie unter Unterstützung mehrerer Azure SignalR Service-Instanzen in Azure Functions.

Beispiele

Aushandlung für signalR-Client

Damit ein Client eine Verbindung mit SignalR herstellen kann, muss er die SignalR-Clienthub-URL und ein Zugriffstoken abrufen. Wir nennen den Prozess "Aushandlung".

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

Übertragen einzelner Nachrichten

Um Nachrichten von einem einzelnen Azure Function-Aufruf an alle Verbindungen in einem Hub zu übertragen, können Sie das SignalR Attribut auf den Rückgabewert der Funktion anwenden. Der Rückgabewert sollte vom Typ SignalRMessagesein.

[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>" }
    };
}

Sie können auch einen out Parameter vom Typ SignalRMessageverwenden.

[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>" }
    };
}

Übertragen mehrerer Nachrichten

Zum Übertragen mehrerer Nachrichten an alle Verbindungen in einem Hub aus einem einzelnen Azure Function-Aufruf können Sie das SignalR Attribut auf den IAsyncCollector<SignalRMessage> Parameter anwenden.

[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>" }
    });
}

Senden von Nachrichten an eine Verbindung, einen Benutzer oder eine Gruppe

Um Nachrichten an eine Verbindung, einen Benutzer oder eine Gruppe zu senden, ähnelt die Funktion dem Senden von Nachrichten oben, mit der Ausnahme, dass Sie oder GroupNameUserId in den Eigenschaften von SignalRMessageangebenConnectionId.

Hier sehen Sie ein Beispiel zum Senden von Nachrichten an einen Benutzer mithilfe der Rückgabewertbindung.

[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-Clientverbindungstrigger

Um eine Funktion auszulösen, wenn ein SignalR-Client verbunden oder getrennt wird, können Sie das SignalRTrigger -Attribut auf den InvocationContext Parameter anwenden.

Im Folgenden finden Sie ein Beispiel zum Protokollieren der Verbindungs-ID, wenn ein SignalR-Client verbunden ist. Stellen Sie sicher, dass der zweite Paramater des SignalRTrigger Konstruktors ist connections, was für die Kategorie des Triggers Verbindungen steht. Die dritte

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

SignalR-Clientnachrichtentrigger

Um eine Funktion auszulösen, wenn ein SignalR-Client eine Nachricht sendet, können Sie das SignalRTrigger Attribut auf den InvocationContext Parameter anwenden und das SignalRParameter Attribut auf jeden Parameter anwenden, dessen Name mit dem Parameternamen in Ihrer Nachricht übereinstimmt.

Hier sehen Sie ein Beispiel zum Protokollieren des Nachrichteninhalts, wenn ein SignalR-Client eine Nachricht mit dem Ziel "SendMessage" sendet.

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

Problembehandlung

Nächste Schritte

Lesen Sie die Einführung in Azure Functions oder erstellen eines Azure Functions-Handbuchs.

Mitwirken

Weitere Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie in unserem CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. 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. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe