ASP.NET Core SignalR JavaScript 用戶端

作者：Rachel Appel

ASP.NET Core SignalR JavaScript 用戶端程式庫可讓開發人員呼叫伺服器端 SignalR 中樞程式碼。

安裝 SignalR 用戶端套件

SignalR JavaScript 用戶端程式庫會以 npm 套件形式傳遞。 下列各節概述不同的用戶端程式庫安裝方式。

使用 npm 安裝

Visual Studio

從 [套件管理員主控台] 中，執行下列命令：

Visual Studio Code

從 [整合式終端] 執行下列命令：

Visual Studio for Mac

從命令視窗中，執行下列命令：

npm init -y
npm install @microsoft/signalr

npm 會在 node_modules\@microsoft\signalr\dist\browser 資料夾中安裝套件內容。 建立 wwwroot/lib/signalr 資料夾。 將 signalr.js 檔案複製至 wwwroot/lib/signalr 資料夾。

參考 <script> 元素中的 SignalR JavaScript 用戶端。 例如：

<script src="~/lib/signalr/signalr.js"></script>

使用內容傳遞網路 (CDN)

若要在沒有 npm 必要條件的情況下使用用戶端程式庫，請參考用戶端程式庫的 CDN 裝載複本。 例如：

<script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft-signalr/6.0.1/signalr.js"></script>

在下列 CDN 上，可以提供用戶端程式庫：

• cdnjs
• jsDelivr
• unpkg

使用 LibMan 安裝

LibMan 可以用來安裝 CDN 裝載用戶端程式庫中的特定用戶端程式庫檔案。 例如，只將縮小的 JavaScript 檔案新增至專案。 如需該方式的詳細資料，請參閱新增 SignalR 用戶端程式庫。

連線至中樞

下列程式碼會建立並啟動連線。 中樞的名稱不區分大小寫：

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

async function start() {
    try {
        await connection.start();
        console.log("SignalR Connected.");
    } catch (err) {
        console.log(err);
        setTimeout(start, 5000);
    }
};

connection.onclose(async () => {
    await start();
});

// Start the connection.
start();

跨原始來源連線 (CORS)

瀏覽器一般會從與所要求頁面相同的網域載入連線。 不過，有時候需要連線至另一個網域。

提出跨網域要求時，用戶端程式碼「必須」使用絕對 URL，而不是相對 URL。 針對跨網域要求，將 .withUrl("/chathub") 變更為 .withUrl("https://{App domain name}/chathub")。

若要防止惡意網站從另一個網站讀取敏感性資料，預設會停用跨原始來源連線。 若要允許跨原始來源要求，請啟用 CORS：

using SignalRChat.Hubs;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(
        builder =>
        {
            builder.WithOrigins("https://example.com")
                .AllowAnyHeader()
                .WithMethods("GET", "POST")
                .AllowCredentials();
        });
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

// UseCors must be called before MapHub.
app.UseCors();

app.MapRazorPages();
app.MapHub<ChatHub>("/chatHub");

app.Run();

必須先呼叫 UseCors，才能呼叫 MapHub。

從用戶端呼叫中樞方法

JavaScript 用戶端會透過 HubConnection 的 invoke 方法來呼叫中樞上的公用方法。 invoke 方法可接受：

• 中樞方法的名稱。
• 中樞方法中所定義的任何引數。

在下列醒目提示的程式碼中，中樞上的方法名稱為 SendMessage。 傳遞至 invoke 的第二個和第三個引數會對應至中樞方法的 user 和 message 引數：

try {
    await connection.invoke("SendMessage", user, message);
} catch (err) {
    console.error(err);
}

只有以預設模式使用 Azure SignalR Service 時，才支援從用戶端呼叫中樞方法。 如需詳細資訊，請參閱常見問題集 (azure-signalr GitHub 存放庫)。

invoke 方法會傳回 JavaScript Promise。 傳回伺服器上的方法時，會使用傳回值來解析 Promise。 如果伺服器上的方法擲回錯誤，則會拒絕 Promise，並顯示錯誤訊息。 使用 async 和 await 或 Promise 的 then 和 catch 方法來處理這些案例。

JavaScript 用戶端也可以透過 HubConnection 的 send 方法，以在中樞上呼叫公用方法。 與 invoke 方法不同，send 方法不會等候來自伺服器的回應。 send 方法會傳回 JavaScript Promise。 已將訊息傳送至伺服器時，會解析 Promise。 如果傳送訊息時發生錯誤，則會拒絕 Promise，並顯示錯誤訊息。 使用 async 和 await 或 Promise 的 then 和 catch 方法來處理這些案例。

使用 send「不」會等到伺服器收到訊息。 因此，無法從伺服器傳回資料或錯誤。

從中樞呼叫用戶端方法

若要從中樞接收訊息，請使用 HubConnection 的 on 方法來定義方法。

• JavaScript 用戶端方法的名稱。
• 中樞傳遞至方法的引數。

在下列範例中，方法名稱為 ReceiveMessage。 引數名稱為 user 和 message：

connection.on("ReceiveMessage", (user, message) => {
    const li = document.createElement("li");
    li.textContent = `${user}: ${message}`;
    document.getElementById("messageList").appendChild(li);
});

connection.on 中的上述程式碼會在伺服器端程式碼使用 SendAsync 方法進行呼叫時執行：

using Microsoft.AspNetCore.SignalR;
namespace SignalRChat.Hubs;

public class ChatHub : Hub
{
    public async Task SendMessage(string user, string message)
    {
        await Clients.All.SendAsync("ReceiveMessage", user, message);
    }
}

SignalR 會比對 SendAsync 和 connection.on 中所定義的方法名稱和引數，來判斷要呼叫的用戶端方法。

「最佳做法」是在 on 後面於 HubConnection 上呼叫 start 方法。 這麼做可確保先在收到任何訊息之前註冊處理常式。

錯誤處理和記錄

用戶端無法連線或傳送訊息時，請使用 console.error 以將錯誤輸出至瀏覽器的主控台：

try {
    await connection.invoke("SendMessage", user, message);
} catch (err) {
    console.error(err);
}

建立連線時，傳遞要記錄之事件的記錄器和類型，以記錄用戶端記錄追蹤。 會以指定的記錄層級和更高層級來記錄訊息。 可用的記錄層級如下：

• signalR.LogLevel.Error：錯誤訊息。 僅記錄 Error 訊息。
• signalR.LogLevel.Warning：潛在錯誤的相關警告訊息。 記錄 Warning 和 Error 訊息。
• signalR.LogLevel.Information：狀態訊息，而且未發生錯誤。 記錄 Information、Warning和 Error 訊息。
• signalR.LogLevel.Trace：追蹤訊息。 記錄所有項目，包括中樞與用戶端之間傳輸的資料。

在 HubConnectionBuilder 上使用 configureLogging 方法，以設定記錄層級。 訊息會記錄至瀏覽器主控台：

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

重新連線用戶端

自動重新連線

SignalR 的 JavaScript 用戶端可以設定為使用 HubConnectionBuilder 上的 WithAutomaticReconnect 方法來自動重新連線。 其預設不會自動重新連線。

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .withAutomaticReconnect()
    .build();

如果不使用任何參數，則 WithAutomaticReconnect 會將用戶端設定為在嘗試每次重新連線嘗試之前分別等待 0、2、10 和 30 秒。 四次嘗試失敗之後，即會停止嘗試重新連線。

開始任何重新連線嘗試之前，HubConnection：

• 轉換至 HubConnectionState.Reconnecting 狀態，並引發其 onreconnecting 回呼。
• 不會轉換至 Disconnected 狀態，並在未設定自動重新連線的情況下觸發其 onclose 回呼 (例如 HubConnection)。

重新連線方式可讓您：

• 向使用者警告已中斷連線。
• 停用 UI 元素。

connection.onreconnecting(error => {
    console.assert(connection.state === signalR.HubConnectionState.Reconnecting);

    document.getElementById("messageInput").disabled = true;

    const li = document.createElement("li");
    li.textContent = `Connection lost due to error "${error}". Reconnecting.`;
    document.getElementById("messageList").appendChild(li);
});

如果用戶端在前四次嘗試中成功重新連線，則 HubConnection 會轉換回 Connected 狀態，並引發其 onreconnected 回呼。 這可讓您向使用者通知已重新建立連線。

因為該連線對伺服器來說是全新的，所以會將新的 connectionId 提供給 onreconnected 回呼。

如果 HubConnection 設定為跳過交涉，則「未定義」onreconnected 回呼的 connectionId 參數。

connection.onreconnected(connectionId => {
    console.assert(connection.state === signalR.HubConnectionState.Connected);

    document.getElementById("messageInput").disabled = false;

    const li = document.createElement("li");
    li.textContent = `Connection reestablished. Connected with connectionId "${connectionId}".`;
    document.getElementById("messageList").appendChild(li);
});

withAutomaticReconnect 不會將 HubConnection 設定為重試初始啟動失敗，因此需要手動進行處理：

async function start() {
    try {
        await connection.start();
        console.assert(connection.state === signalR.HubConnectionState.Connected);
        console.log("SignalR Connected.");
    } catch (err) {
        console.assert(connection.state === signalR.HubConnectionState.Disconnected);
        console.log(err);
        setTimeout(() => start(), 5000);
    }
};

如果用戶端在前四次嘗試中未成功重新連線，則 HubConnection 會轉換至 Disconnected 狀態，並引發其 onclose 回呼。 這可讓您通知使用者：

• 已永久中斷連線。
• 請嘗試重新整理頁面：

connection.onclose(error => {
    console.assert(connection.state === signalR.HubConnectionState.Disconnected);

    document.getElementById("messageInput").disabled = true;

    const li = document.createElement("li");
    li.textContent = `Connection closed due to error "${error}". Try refreshing this page to restart the connection.`;
    document.getElementById("messageList").appendChild(li);
});

若要在中斷連線或變更重新連線時間之前設定自訂重新連線嘗試次數，withAutomaticReconnect 接受一個數字陣列，表示在開始每次重新連線嘗試之前要等待的延遲時間 (以毫秒為單位)。

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .withAutomaticReconnect([0, 0, 10000])
    .build();

    // .withAutomaticReconnect([0, 2000, 10000, 30000]) yields the default behavior

上述範例會將 HubConnection 設定為在連線遺失後立即開始嘗試重新連線。 預設設定也會等待零秒，以嘗試重新連線。

如果第一次重新連線嘗試失敗，則第二次重新連線嘗試也會立即啟動，而不是使用預設設定來等待 2 秒。

如果第二次重新連線嘗試失敗，則第三次重新連線嘗試會在 10 秒內開始，而這與預設設定相同。

所設定的重新連線時間與預設行為不同，原因是在第三次重新連線嘗試失敗後停止，而不是在另一個 30 秒內再嘗試一次重新連線嘗試。

為了更充分掌控自動重新連線嘗試的時間和次數，withAutomaticReconnect 接受一個實作 IRetryPolicy 介面的物件，該介面有名為 nextRetryDelayInMilliseconds 的單一方法。

nextRetryDelayInMilliseconds 會採用類型為 RetryContext 的單一引數。 RetryContext 有三個屬性：previousRetryCount、elapsedMilliseconds 和 retryReason，分別是 number、number 和 Error。 在第一次重新連線嘗試之前，previousRetryCount 和 elapsedMilliseconds 都會是零，而 retryReason 會是造成連線中斷的「錯誤」。 每次重試失敗之後，previousRetryCount 將會遞增一次，elapsedMilliseconds 將會更新以反映到目前為止重新連線所花費的時間量 (毫秒)，而 retryReason 會是造成上次重新連線嘗試失敗的「錯誤」。

nextRetryDelayInMilliseconds 必須傳回一個數字，代表下一次重新連線嘗試之前所要等待的毫秒數，或者，如果 HubConnection 應該停止重新連線，則傳回 null。

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .withAutomaticReconnect({
        nextRetryDelayInMilliseconds: retryContext => {
            if (retryContext.elapsedMilliseconds < 60000) {
                // If we've been reconnecting for less than 60 seconds so far,
                // wait between 0 and 10 seconds before the next reconnect attempt.
                return Math.random() * 10000;
            } else {
                // If we've been reconnecting for more than 60 seconds so far, stop reconnecting.
                return null;
            }
        }
    })
    .build();

或者，您可以撰寫程式碼，以手動重新連線用戶端，如下節所示範。

手動重新連線

下列程式碼示範一般手動重新連線方式：

1. 會建立函數 (在此案例中，為 start 函數) 來啟動連線。
2. 在連線的 onclose 事件處理常式中，呼叫 start 函數。

async function start() {
    try {
        await connection.start();
        console.log("SignalR Connected.");
    } catch (err) {
        console.log(err);
        setTimeout(start, 5000);
    }
};

connection.onclose(async () => {
    await start();
});

生產實作通常會使用指數輪詢，或重試指定的次數。

瀏覽器睡眠索引標籤

某些瀏覽器具有索引標籤凍結或睡眠功能，以減少非使用中索引標籤的電腦資源使用量。 這可能會導致關閉 SignalR 連線，而且可能會導致不必要的使用者體驗。 瀏覽器會使用啟發學習法來找出索引標籤是否應該進入睡眠狀態，例如：

• 播放音訊
• 保留 Web 鎖定
• 保留 IndexedDB 鎖定
• 連線至 USB 裝置
• 擷取視訊或音訊
• 進行鏡像
• 擷取視窗或顯示

瀏覽器啟發學習法可能會隨著時間而變更，而且瀏覽器之間可能會不同。 請檢查支援矩陣，並找出最適合您案例的方法。

為了避免讓應用程式進入睡眠狀態，應用程式應該觸發瀏覽器所使用的其中一種啟發學習法。

下列程式碼範例顯示如何使用 Web 鎖定，以讓索引標籤保持喚醒狀態，並避免非預期的連線關閉。

var lockResolver;
if (navigator && navigator.locks && navigator.locks.request) {
    const promise = new Promise((res) => {
        lockResolver = res;
    });

    navigator.locks.request('unique_lock_name', { mode: "shared" }, () => {
        return promise;
    });
}

針對上述程式碼範例：

• Web 鎖定是實驗性項目。 條件式檢查會確認瀏覽器支援 Web 鎖定。
• 會儲存 Promise 解析程式 lockResolver，以在可接受索引標籤進入睡眠狀態時釋放鎖定。
• 關閉連線時，會呼叫 lockResolver() 來釋放鎖定。 釋放鎖定時，允許索引標籤進入睡眠狀態。

其他資源

• 檢視或下載範例程式碼 \(英文\) (如何下載)
• JavaScript API 參考
• JavaScript 教學課程
• WebPack 和 TypeScript 教學課程
• 中樞
• .NET 用戶端
• 發佈至 Azure
• 跨原始來源要求 (CORS)
• Azure SignalR Service 無伺服器文件
• 針對連線錯誤進行疑難排解