使用 Azure SignalR Service

發行項
12/12/2024

本文說明當您在應用程式伺服器中使用 SignalR 時，如何在應用程式伺服器端使用 SDK 來連線到 SignalR Service。

重要

原始連接字串只針對示範目的出現在本文中。

連接字串包含應用程式存取 Azure SignalR Service 所需的授權資訊。連接字串內的存取金鑰類似於服務的根密碼。在生產環境中，請一律保護您的存取金鑰。使用 Azure 金鑰保存庫，使用 Microsoft Entra 識別碼安全地管理和輪替您的連接字串，並使用 Microsoft Entra 標識符來授權存取權。

避免將存取金鑰散發給其他使用者、寫入程式碼，或將其以純文字儲存在他人可以存取的位置。如果您認為金鑰可能已遭盜用，請輪替金鑰。

建立 Azure SignalR 服務執行個體

遵循快速入門：使用 ARM 範本來部署 Azure SignalR 來建立 SignalR 服務執行個體。

對於 ASP.NET Core SignalR

安裝 SDK

執行該命令，將 SignalR Service SDK 安裝至您的 ASP.NET Core 專案。

dotnet add package Microsoft.Azure.SignalR

在您的 Startup 類別中，使用 SignalR Service SDK 作為下列程式碼片段。

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR()
            .AddAzureSignalR();
}

public void Configure(IApplicationBuilder app)
{
    app.UseEndpoints(routes =>
    {
        routes.MapHub<YourHubClass>("/path_for_your_hub");
    });
}

設定連接字串

原始連接字串只針對示範目的出現在本文中。在生產環境中，請一律保護您的存取金鑰。使用 Azure 金鑰保存庫，使用 Microsoft Entra 識別碼安全地管理和輪替您的連接字串，並使用 Microsoft Entra 標識符來授權存取權。

有兩種方式可在應用程式中設定 SignalR Service 的連接字串。

設定名稱為 Azure:SignalR:ConnectionString 或 Azure__SignalR__ConnectionString 的環境變數。
- 在 Azure App Service 中，將其放在應用程式設定中。

傳遞連接字串作為 AddAzureSignalR() 的參數。

services.AddSignalR()
        .AddAzureSignalR("<replace with your connection string>");

或

services.AddSignalR()
        .AddAzureSignalR(options => options.ConnectionString = "<replace with your connection string>");

設定選項

使用 Azure SignalR Service SDK 時，可以自訂一些選項。

`ConnectionString`

預設值為 Azure:SignalR:ConnectionString connectionString 或 appSetting 檔案中的 web.config 。
它可以重新設定，但請確定值不是硬式編碼。

`InitialHubServerConnectionCount`

預設值為 5。
此選項可控制應用程式伺服器和 Azure SignalR Service 之間的每個中樞連線的初始連線計數。通常保留預設值已足夠。在執行階段期間，SDK 可能會啟動新的伺服器連線，以進行效能微調或負載平衡。當您有大量的用戶端時，可以為其指定更大的數量以取得更好的輸送量。例如，如果您總共有 100,000 個用戶端，連線計數可以增加為 10 或 15。

`MaxHubServerConnectionCount`

預設值為 null。
此選項可控制應用程式伺服器和 Azure SignalR Service 之間的每個中樞所允許的連線計數上限。在執行階段期間，SDK 可能會啟動新的伺服器連線，以進行效能微調或負載平衡。根據預設，會視需要啟動新的伺服器連線。設定允許的伺服器連線計數上限時，SDK 不會在伺服器連線計數達到上限時啟動新的連線。

`ApplicationName`

預設值為 null。
當您想要為包含相同中樞名稱的不同應用程式伺服器，共用相同的 Azure SignalR 執行個體時，這個選項很有用。如果未設定，所有連線的應用程式伺服器都會被視為相同應用程式的執行個體。

`ClaimsProvider`

預設值為 null。
此選項控制您想要與用戶端連線建立關聯的宣告。當 Service SDK 在用戶端交涉要求中，為用戶端產生存取權杖時使用。根據預設，保留來自交涉要求的 HttpContext.User 所有宣告。可以透過 Hub.Context.User 進行存取。
通常您應該保留此選項不變。請確定您了解在自訂之前會發生什麼事。

`AccessTokenLifetime`

預設值為 1 hour。
此選項控制服務 SDK 為每個用戶端產生的存取權杖的有效存留期。在對用戶端交涉要求的回應中傳回存取權杖。
當使用 ServerSentEvent 或 LongPolling 作為傳輸時，用戶端連線會在過期之後因驗證失敗而關閉。您可以增加此值以避免用戶端中斷連線。

`AccessTokenAlgorithm`

預設值是 HS256
此選項提供產生存取權杖時 SecurityAlgorithms 的選擇。現在支援選擇性的值是 HS256 和 HS512。請注意，HS512 更安全，但相對於使用 HS256 的權杖，產生的權杖較長。

`ServerStickyMode`

預設值為 Disabled。
此選項會指定伺服器黏性的模式。當用戶端路由至其首次交涉的伺服器時，我們會將其稱為伺服器黏性。
在分散式案例中，可以有多個應用程式伺服器連線到一個 Azure SignalR 執行個體。正如用戶端連線內部所述，用戶端首先與應用程式伺服器交涉，然後重新導向至 Azure SignalR 以建立持久連線。接著，Azure SignalR 會找到一個應用程式伺服器來為用戶端提供服務，如用戶端與伺服器之間的傳輸資料所說明的。
- Disabled 時，用戶端會路由傳送至隨機應用程式伺服器。一般而言，應用程式伺服器透過此模式來平衡用戶端連線。如果您的案例是廣播或群組傳送，則使用此預設選項就已足夠。
- Preferred 時，Azure SignalR 嘗試尋找用戶端首次與之交涉的應用程式伺服器，而不需其他成本或全域路由。當您的案例傳送至連線*時，此案例可能很有用。在傳送者與接收者路由傳送至相同的應用程式伺服器時，「傳送至連線」可以有更好的效能和較低的延遲。
- Required 時，Azure SignalR 一律嘗試尋找用戶端首次與之交涉的應用程式伺服器。當從 negotiate 步驟擷取某些用戶端內容並儲存在記憶體中，然後在 Hub 內使用時，這個選項很有用。不過，此選項可能有效能缺點，因為其需要 Azure SignalR 採取其他措施來全域尋找此特定應用程式伺服器，並保持用戶端與伺服器之間的全域路由流量。

`GracefulShutdown`

`GracefulShutdown.Mode`

預設值是 Off
此選項會指定應用程式伺服器收到 SIGINT (CTRL + C) 之後的行為。
當設定為 WaitForClientsClose 時，我們不會立即停止伺服器，而是從 Azure SignalR Service 中移除它，以防止將新的用戶端連線指派給此伺服器。
此外，當設定為 MigrateClients 時，我們也會嘗試將用戶端連線移轉至另一個有效的伺服器。只有在傳遞訊息之後，才會觸發移轉。
- 當連線移入/移出時，會觸發 OnConnected 和 OnDisconnected。
- IConnectionMigrationFeature 可協助您識別連線是否已移入/移出。
- 如需詳細使用方式，請參閱範例程式碼。

`GracefulShutdown.Timeout`

預設值是 30 seconds
此選項會指定等待用戶端關閉/移轉的最長時間。

`ServiceScaleTimeout`

預設值是 5 minutes
此選項會指定動態調整服務端點等待的最長時間，以最小程度影響線上用戶端。一般而言，單一應用程式伺服器與服務端點之間的動態調整可以在幾秒鐘內完成，同時考慮到您是否有多個應用程式伺服器和多個網路抖動的服務端點，並且希望確保用戶端穩定性，您可以據以設定此值。

`MaxPollIntervalInSeconds`

預設值是 5
此選項會定義 Azure SignalR Service 中 LongPolling 連線允許的輪詢間隔上限。如果下一個輪詢要求不在 MaxPollIntervalInSeconds 內，則 Azure SignalR Service 會清除用戶端連線。
此值限制為 [1, 300]。

`TransportTypeDetector`

預設值：所有傳輸都會啟用。
此選項會定義函式，以自訂用戶端可用來傳送 HTTP 要求的傳輸。
使用此選項， HttpConnectionDispatcherOptions.Transports 而不是設定傳輸。

`AllowStatefulReconnects`

預設值是 null
此選項會啟用或停用所有中樞的具狀態重新連線。
如果 null為，SDK 將會讀取中樞設定。
如果 true為，Azure SignalR 服務將會在所有宣告的中樞中啟用具狀態重新連線。用戶端需要啟用用戶端的具狀態重新連線。
如果 false為，Azure SignalR 服務將會停用所有已宣告中樞的具狀態重新連線。

範例

您可以設定上述選項，例如下列範例程式碼。

services.AddSignalR()
        .AddAzureSignalR(options =>
            {
                options.InitialHubServerConnectionCount = 10;
                options.AccessTokenLifetime = TimeSpan.FromDays(1);
                options.ClaimsProvider = context => context.User.Claims;

                options.GracefulShutdown.Mode = GracefulShutdownMode.WaitForClientsClose;
                options.GracefulShutdown.Timeout = TimeSpan.FromSeconds(10);
                options.TransportTypeDetector = httpContext => AspNetCore.Http.Connections.HttpTransportType.WebSockets | AspNetCore.Http.Connections.HttpTransportType.LongPolling;
            });

針對舊版 ASP.NET SignalR

注意

如果您是第一次嘗試 SignalR，建議您使用 ASP.NET Core SignalR，它更簡單、更可靠且更容易使用。

安裝 SDK

使用套件管理員主控台，將 SignalR Service SDK 安裝至 ASP.NET 專案：

Install-Package Microsoft.Azure.SignalR.AspNet

在您的 Startup 類別中，使用 SignalR Service SDK 作為下列程式碼片段，將 MapSignalR() 取代為 MapAzureSignalR({your_applicationName})。將 {YourApplicationName} 取代為應用程式的名稱，這是用來區別此應用程式與其他應用程式的唯一名稱。您可以使用 this.GetType().FullName 做為值。

public void Configuration(IAppBuilder app)
{
    app.MapAzureSignalR(this.GetType().FullName);
}

設定連接字串

將 web.config 檔案中的連接字串設定為 connectionStrings 區段：

<configuration>
    <connectionStrings>
        <add name="Azure:SignalR:ConnectionString" connectionString="Endpoint=...;AccessKey=..."/>
    </connectionStrings>
    ...
</configuration>

設定選項

使用 Azure SignalR Service SDK 時，可以自訂一些選項。

`ConnectionString`

預設值為 Azure:SignalR:ConnectionString connectionString 或 appSetting 檔案中的 web.config 。
它可以重新設定，但請確定值不是硬式編碼。

`InitialHubServerConnectionCount`

預設值為 5。
此選項可控制應用程式伺服器和 Azure SignalR Service 之間的每個中樞連線的初始連線計數。通常保留預設值已足夠。在執行階段期間，SDK 可能會啟動新的伺服器連線，以進行效能微調或負載平衡。當您有大量的用戶端時，可以為其指定更大的數量以取得更好的輸送量。例如，如果您總共有 100,000 個用戶端，連線計數可以增加為 10 或 15。

`MaxHubServerConnectionCount`

預設值為 null。
此選項可控制應用程式伺服器和 Azure SignalR Service 之間的每個中樞所允許的連線計數上限。在執行階段期間，SDK 可能會啟動新的伺服器連線，以進行效能微調或負載平衡。根據預設，會視需要啟動新的伺服器連線。設定允許的伺服器連線計數上限時，SDK 不會在伺服器連線計數達到上限時啟動新的連線。

`ApplicationName`

預設值為 null。
當您想要為包含相同中樞名稱的不同應用程式伺服器，共用相同的 Azure SignalR 執行個體時，這個選項很有用。如果未設定，所有連線的應用程式伺服器都會被視為相同應用程式的執行個體。

`ClaimProvider`

預設值為 null。
此選項控制您想要與用戶端連線建立關聯的宣告。當 Service SDK 在用戶端交涉要求中，為用戶端產生存取權杖時使用。根據預設，保留來自交涉要求的 IOwinContext.Authentication.User 所有宣告。
通常您應該保留此選項不變。請確定您了解在自訂之前會發生什麼事。

`AccessTokenLifetime`

預設值為 1 hour。
此選項控制服務 SDK 為每個用戶端產生的存取權杖的有效存留期。在對用戶端交涉要求的回應中傳回存取權杖。
當使用 ServerSentEvent 或 LongPolling 作為傳輸時，用戶端連線會在過期之後因驗證失敗而關閉。您可以增加此值以避免用戶端中斷連線。

`AccessTokenAlgorithm`

預設值是 HS256
此選項提供產生存取權杖時 SecurityAlgorithms 的選擇。現在支援選擇性的值是 HS256 和 HS512。請注意，HS512 更安全，但相對於使用 HS256 的權杖，產生的權杖較長。

`ServerStickyMode`

預設值為 Disabled。
此選項會指定伺服器黏性的模式。當用戶端路由至其首次交涉的伺服器時，我們會將其稱為伺服器黏性。
在分散式案例中，可以有多個應用程式伺服器連線到一個 Azure SignalR 執行個體。正如用戶端連線內部所述，用戶端首先與應用程式伺服器交涉，然後重新導向至 Azure SignalR 以建立持久連線。接著，Azure SignalR 會找到一個應用程式伺服器來為用戶端提供服務，如用戶端與伺服器之間的傳輸資料所說明的。
- Disabled 時，用戶端會路由傳送至隨機應用程式伺服器。一般而言，應用程式伺服器透過此模式來平衡用戶端連線。如果您的案例是廣播或群組傳送，則使用此預設選項就已足夠。
- Preferred 時，Azure SignalR 嘗試尋找用戶端首次與之交涉的應用程式伺服器，而不需其他成本或全域路由。當您的案例傳送至連線*時，此案例可能很有用。在傳送者與接收者路由傳送至相同的應用程式伺服器時，「傳送至連線」可以有更好的效能和較低的延遲。
- Required 時，Azure SignalR 一律嘗試尋找用戶端首次與之交涉的應用程式伺服器。當從 negotiate 步驟擷取某些用戶端內容並儲存在記憶體中，然後在 Hub 內使用時，這個選項很有用。不過，此選項可能有效能缺點，因為其需要 Azure SignalR 採取其他措施來全域尋找此特定應用程式伺服器，並保持用戶端與伺服器之間的全域路由流量。

`MaxPollIntervalInSeconds`

預設值是 5
此選項會定義 Azure SignalR Service 中非使用中連線允許的閒置時間上限。在 ASP.NET SignalR 中，其會套用至長時間輪詢傳輸類型或重新連線。如果下一個 /reconnect 或 /poll 要求不在 MaxPollIntervalInSeconds 內，則 Azure SignalR Service 會清除用戶端連線。
此值限制為 [1, 300]。

範例

您可以設定上述選項，例如下列範例程式碼。

app.Map("/signalr",subApp => subApp.RunAzureSignalR(this.GetType().FullName, new HubConfiguration(), options =>
{
    options.InitialHubServerConnectionCount = 1;
    options.AccessTokenLifetime = TimeSpan.FromDays(1);
    options.ClaimProvider = context => context.Authentication?.User.Claims;
}));

向外延展應用程式伺服器

使用 Azure SignalR Service 時，持久連線會從應用程式伺服器卸載，讓您可以專注於在中樞類別中實作商業邏輯。但是，當您處理大量用戶端連線時，仍然需要向外延展應用程式伺服器以提升效能。以下是向外延展應用程式伺服器的一些秘訣。

多個應用程式伺服器可以連線到相同的 Azure SignalR Service 執行個體。
如果您想要為包含相同中樞名稱的不同應用程式共用相同的 Azure SignalR 執行個體，請使用不同的 ApplicationName 選項加以設定。如果未設定，所有連線的應用程式伺服器都會被視為相同應用程式的執行個體。
只要 ApplicationName 選項和中樞類別的名稱相同，來自不同應用程式伺服器的連線就會分組在相同的中樞內。
每個用戶端連線僅在其中一個應用程式伺服器中建立，並且來自該用戶端的訊息僅傳送至相同的應用程式伺服器。如果要全域 (來自所有應用程式伺服器) 存取用戶端資訊，則必須使用一些集中式儲存體，儲存來自所有應用程式伺服器的用戶端資訊。

下一步

在本文中，您將了解如何在應用程式中使用 SignalR Service。請參閱下列文章以了解有關 SignalR Service 的更多資訊。

Azure SignalR Service 內部項目

快速入門：使用 SignalR Service 建立聊天室

共用方式為

使用 Azure SignalR Service

建立 Azure SignalR 服務執行個體

對於 ASP.NET Core SignalR

安裝 SDK

設定連接字串

設定選項

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimsProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

GracefulShutdown

GracefulShutdown.Mode

GracefulShutdown.Timeout

ServiceScaleTimeout

MaxPollIntervalInSeconds

TransportTypeDetector

AllowStatefulReconnects

範例

針對舊版 ASP.NET SignalR

安裝 SDK

設定連接字串

設定選項

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

MaxPollIntervalInSeconds

範例

向外延展應用程式伺服器

下一步

意見反應

其他資源

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimsProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`GracefulShutdown`

`GracefulShutdown.Mode`

`GracefulShutdown.Timeout`

`ServiceScaleTimeout`

`MaxPollIntervalInSeconds`

`TransportTypeDetector`

`AllowStatefulReconnects`

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`MaxPollIntervalInSeconds`