使用 Azure SignalR 服務

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

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

設定 連接字串

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

• 設定名稱 Azure:SignalR:ConnectionString 為 或 Azure__SignalR__ConnectionString的環境變數。

  • 在 Azure App 服務 中，將它放在應用程式設定中。

• 將 連接字串 當做 的參數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:ConnectionStringconnectionString 或 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 為每個客戶端產生的存取令牌有效存留期。 存取令牌會在回應用戶端交涉要求時傳回。
• 當 或 LongPolling 當做傳輸使用時ServerSentEvent，用戶端連線將會因為驗證失敗而關閉，因為到期時間之後。 您可以增加此值，以避免客戶端中斷連線。

AccessTokenAlgorithm

• 預設值是 HS256
• 這個選項會在產生存取權杖時提供 選擇 SecurityAlgorithms 。 現在支援的選擇性值為 HS256 和 HS512。 請注意， HS512 較安全，但產生的令牌比使用 HS256的令牌還要長。

ServerStickyMode

• 預設值為 Disabled。
• 此選項會指定伺服器黏性模式。 當用戶端路由傳送至它第一次交涉的伺服器時，我們會將其稱為 伺服器黏性。
• 在分散式案例中，可以有多個應用程式伺服器連線到一個 Azure SignalR 實例。 如 用戶端連線 的內部所說明，用戶端會先與應用程式伺服器交涉，然後重新導向至 Azure SignalR 以建立持續性連線。 接著，Azure SignalR 會尋找一個應用程式伺服器來提供用戶端，如 客戶端與伺服器 之間的傳輸數據所述。
  • 當 為時 Disabled，用戶端會路由傳送至隨機應用程式伺服器。 一般而言，應用程式伺服器具有與這個模式的平衡用戶端連線。 如果您的案例是 廣播 或 群組傳送，請使用這個預設選項就已足夠。
  • 當 為 時 Preferred，Azure SignalR 會嘗試尋找用戶端第一次交涉的應用程式伺服器，而不需要其他成本或全域路由。 當您的案例傳送至連線*時，此案例可能很有用。*。 當傳送者和接收者路由傳送至相同的應用程式伺服器時，傳送至連線 的效能和較低的延遲。
  • 當 時 Required，Azure SignalR 一律會嘗試尋找用戶端第一次交涉的應用程式伺服器。 從步驟擷 negotiate 取某些客戶端內容並儲存在記憶體中，然後用於 s 時 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 而不是設定傳輸。

範例

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

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:ConnectionStringconnectionString 或 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 為每個客戶端產生的存取令牌有效存留期。 存取令牌會在回應用戶端交涉要求時傳回。
• 當 或 LongPolling 當做傳輸使用時ServerSentEvent，用戶端連線將會因為驗證失敗而關閉，因為到期時間之後。 您可以增加此值，以避免客戶端中斷連線。

AccessTokenAlgorithm

• 預設值是 HS256
• 這個選項會在產生存取權杖時提供 選擇 SecurityAlgorithms 。 現在支援的選擇性值為 HS256 和 HS512。 請注意， HS512 較安全，但產生的令牌比使用 HS256的令牌還要長。

ServerStickyMode

• 預設值為 Disabled。
• 此選項會指定伺服器黏性模式。 當用戶端路由傳送至它第一次交涉的伺服器時，我們會將其稱為 伺服器黏性。
• 在分散式案例中，可以有多個應用程式伺服器連線到一個 Azure SignalR 實例。 如 用戶端連線 的內部所說明，用戶端會先與應用程式伺服器交涉，然後重新導向至 Azure SignalR 以建立持續性連線。 接著，Azure SignalR 會尋找一個應用程式伺服器來提供用戶端，如 客戶端與伺服器 之間的傳輸數據所述。
  • 當 為時 Disabled，用戶端會路由傳送至隨機應用程式伺服器。 一般而言，應用程式伺服器具有與這個模式的平衡用戶端連線。 如果您的案例是 廣播 或 群組傳送，請使用這個預設選項就已足夠。
  • 當 為 時 Preferred，Azure SignalR 會嘗試尋找用戶端第一次交涉的應用程式伺服器，而不需要其他成本或全域路由。 當您的案例傳送至連線*時，此案例可能很有用。*。 當傳送者和接收者路由傳送至相同的應用程式伺服器時，傳送至連線 的效能和較低的延遲。
  • 當 時 Required，Azure SignalR 一律會嘗試尋找用戶端第一次交涉的應用程式伺服器。 從步驟擷 negotiate 取某些客戶端內容並儲存在記憶體中，然後用於 s 時 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 服務建立聊天室