ASP.NET SignalR 中樞 API 指南 - JavaScript 用戶端

發行項
07/13/2023

警告

本檔不適用於最新版的 SignalR。看看ASP.NET Core SignalR。

本檔提供在 JavaScript 用戶端中使用 SignalR 第 2 版中樞 API 的簡介，例如瀏覽器和 Windows 市集 (WinJS) 應用程式。

SignalR Hubs API 可讓您 (RPC 進行遠端過程呼叫，) 從伺服器連線到用戶端，以及從用戶端到伺服器。在伺服器程式碼中，您會定義可由用戶端呼叫的方法，以及呼叫在用戶端上執行的方法。在用戶端程式代碼中，您會定義可從伺服器呼叫的方法，以及呼叫在伺服器上執行的方法。 SignalR 會為您處理所有用戶端對伺服器管線。

SignalR 也提供稱為持續性連線的較低層級 API。如需 SignalR、中樞和持續性連線的簡介，請參閱 SignalR 簡介。

本主題中使用的軟體版本

Visual Studio 2017

.NET 4.5

SignalR 第 2 版

本主題的舊版

如需舊版 SignalR 的相關資訊，請參閱 SignalR 舊版。

問題和批註

請留下您喜歡本教學課程的意見反應，以及我們可以在頁面底部的批註中改善的內容。如果您有與教學課程不直接相關的問題，您可以將問題張貼至 ASP.NET SignalR 論壇或 StackOverflow.com。

概觀

本文件包含下列章節：

產生的 Proxy 及其用途
- 使用產生的 Proxy 的時機
用戶端設定
- 如何參考動態產生的 Proxy
- 如何為 SignalR 產生的 Proxy 建立實體檔案
如何建立連線
- $.connection.hub 與 $.hubConnection () 所建立的物件相同
- 啟動方法的非同步執行
如何建立跨網域連線
如何設定連線
- 如何指定查詢字串參數
- 如何指定傳輸方法
如何取得中樞類別的 Proxy
如何在伺服器可以呼叫的用戶端上定義方法
如何從用戶端呼叫伺服器方法
如何處理連線存留期事件
如何處理錯誤
如何啟用用戶端記錄

如需如何設計伺服器或 .NET 用戶端的檔，請參閱下列資源：

SignalR 2 伺服器元件僅適用于 .NET 4.5 (但 .NET 4.0) 上有適用于 SignalR 2 的 .NET 用戶端。

產生的 Proxy 及其用途

您可以程式設計 JavaScript 用戶端，以與 SignalR 服務進行通訊，或是沒有 SignalR 為您產生的 Proxy。 Proxy 會為您簡化用來連接的程式碼語法、撰寫伺服器呼叫的方法，以及在伺服器上呼叫方法。

當您撰寫程式碼來呼叫伺服器方法時，產生的 Proxy 可讓您使用類似您執行本機函式的語法：您可以撰寫 serverMethod(arg1, arg2) 而不是 invoke('serverMethod', arg1, arg2) 。如果您輸入伺服器方法名稱錯誤，產生的 Proxy 語法也會啟用立即且可辨識的用戶端錯誤。而且，如果您手動建立定義 Proxy 的檔案，您也可以取得 IntelliSense 支援撰寫呼叫伺服器方法的程式碼。

例如，假設您在伺服器上有下列 Hub 類別：

public class ContosoChatHub : Hub
{
    public void NewContosoChatMessage(string name, string message)
    {
        Clients.All.addContosoChatMessageToPage(name, message);
    }
}

下列程式碼範例顯示 JavaScript 程式碼的外觀，可用來 NewContosoChatMessage 叫用伺服器上的方法，以及從伺服器接收方法的調用 addContosoChatMessageToPage 。

使用產生的 Proxy

var contosoChatHubProxy = $.connection.contosoChatHub;
contosoChatHubProxy.client.addContosoChatMessageToPage = function (name, message) {
    console.log(name + ' ' + message);
};
$.connection.hub.start().done(function () {
    // Wire up Send button to call NewContosoChatMessage on the server.
    $('#newContosoChatMessage').click(function () {
         contosoChatHubProxy.server.newContosoChatMessage($('#displayname').val(), $('#message').val());
         $('#message').val('').focus();
     });
});

沒有產生的 Proxy

var connection = $.hubConnection();
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
contosoChatHubProxy.on('addContosoChatMessageToPage', function(name, message) {
    console.log(name + ' ' + message);
});
connection.start().done(function() {
    // Wire up Send button to call NewContosoChatMessage on the server.
    $('#newContosoChatMessage').click(function () {
        contosoChatHubProxy.invoke('newContosoChatMessage', $('#displayname').val(), $('#message').val());
        $('#message').val('').focus();
                });
    });

使用產生的 Proxy 的時機

如果您想要為伺服器呼叫的用戶端方法註冊多個事件處理常式，則無法使用產生的 Proxy。否則，您可以選擇根據程式碼喜好設定使用產生的 Proxy。如果您選擇不要使用它，就不需要在用戶端程式代碼的元素中 script 參考「signalr/hubs」 URL。

用戶端設定

JavaScript 用戶端需要 jQuery 和 SignalR 核心 JavaScript 檔案的參考。 jQuery 版本必須是 1.6.4 或更新版本，例如 1.7.2、1.8.2 或 1.9.1。如果您決定使用產生的 Proxy，您也需要 SignalR 產生的 Proxy JavaScript 檔案的參考。下列範例顯示使用所產生 Proxy 的 HTML 頁面中，參考看起來可能的樣子。

<script src="Scripts/jquery-1.10.2.min.js"></script>
<script src="Scripts/jquery.signalR-2.1.0.min.js"></script>
<script src="signalr/hubs"></script>

這些參考必須依此順序包含：jQuery 首先、SignalR 核心之後，以及最後一個 SignalR Proxy。

如何參考動態產生的 Proxy

在上述範例中，SignalR 產生的 Proxy 參考是動態產生的 JavaScript 程式碼，而不是實體檔案。 SignalR 會即時建立 Proxy 的 JavaScript 程式碼，並將它提供給用戶端以回應「/signalr/hubs」 URL。如果您在方法的伺服器上 MapSignalR 為 SignalR 連線指定了不同的基底 URL，動態產生的 Proxy 檔案的 URL 是附加「/hubs」的自訂 URL。

注意

針對 Windows 8 (Windows 市集) JavaScript 用戶端，請使用實體 Proxy 檔案，而不是動態產生的 Proxy 檔案。如需詳細資訊，請參閱本主題稍後如何為 SignalR 產生的 Proxy 建立實體檔案。

在 ASP.NET MVC 4 或 5 Razor 檢視中，使用磚來參考 Proxy 檔案參考中的應用程式根目錄：

<script src="~/signalr/hubs"></script>

如需在 MVC 5 中使用 SignalR 的詳細資訊，請參閱搭配 SignalR 和 MVC 5 消費者入門。

在 ASP.NET MVC 3 Razor 檢視中，用於 Url.Content Proxy 檔案參考：

<script src="@Url.Content("~/signalr/hubs")"></script>

在 ASP.NET Web Forms應用程式中，使用 ResolveClientUrl Proxy 檔案參考，或使用應用程式根相對路徑 (從波浪) 開始，透過 ScriptManager 進行註冊：

<script src='<%: ResolveClientUrl("~/signalr/hubs") %>'></script>

一般規則是使用相同的方法來指定您用於 CSS 或 JavaScript 檔案的「/signalr/hubs」 URL。如果您指定 URL 而不使用波浪圖，在某些情況下，當您使用 IIS Express 在 Visual Studio 中測試時，您的應用程式會正常運作，但在部署至完整 IIS 時會發生 404 錯誤。如需詳細資訊，請參閱解析 MSDN 網站上 Web 專案的 Web 服務器中 ASP.NET Web 專案的參考Root-Level資源。

當您以偵錯模式在 Visual Studio 2017 中執行 Web 專案時，如果您使用 Internet Explorer 作為瀏覽器，您可以在 [腳本] 底下看到方案總管中的 Proxy 檔案。

若要查看檔案的內容，請按兩下中樞。如果您未使用 Visual Studio 2012 或 2013 和 Internet Explorer，或者您不在偵錯模式中，您也可以流覽至「/signalR/hubs」 URL 來取得檔案的內容。例如，如果您的網站在執行中 http://localhost:56699 ，請移至 http://localhost:56699/SignalR/hubs 瀏覽器中。

如何為 SignalR 產生的 Proxy 建立實體檔案

除了動態產生的 Proxy，您也可以建立具有 Proxy 程式碼的實體檔案，並參考該檔案。您可能想要這樣做以控制快取或統合行為，或在撰寫伺服器方法的呼叫時取得 IntelliSense。

若要建立 Proxy 檔案，請執行下列步驟：

安裝 Microsoft.AspNet.SignalR.Utils NuGet 套件。
開啟命令提示字元並流覽至包含SignalR.exe檔案 的工具 資料夾。工具資料夾位於下列位置：

[your solution folder]\packages\Microsoft.AspNet.SignalR.Utils.2.1.0\tools
輸入下列命令：

signalr ghp /path:[path to the .dll that contains your Hub class]

.dll的路徑通常是專案資料夾中的bin資料夾。

此命令會在與signalr.exe相同的資料夾中建立名為server.js的檔案。
將 server.js 檔案放在您專案的適當資料夾中，針對您的應用程式重新命名，並新增參考以取代「signalr/hubs」參考。

如何建立連線

您必須先建立連線物件、建立 Proxy，以及註冊可從伺服器呼叫之方法的事件處理常式，才能建立連接。設定 Proxy 和事件處理常式時，請呼叫 start 方法來建立連線。

如果您使用產生的 Proxy，就不需要在自己的程式碼中建立連線物件，因為產生的 Proxy 程式碼會為您執行此動作。

使用產生的 Proxy) 建立連線 (

var contosoChatHubProxy = $.connection.contosoChatHub;
contosoChatHubProxy.client.addContosoChatMessageToPage = function (name, message) {
    console.log(userName + ' ' + message);
};
$.connection.hub.start()
    .done(function(){ console.log('Now connected, connection ID=' + $.connection.hub.id); })
    .fail(function(){ console.log('Could not Connect!'); });

在沒有產生的 Proxy) 的情況下建立連線 (

var connection = $.hubConnection();
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
contosoChatHubProxy.on('addContosoChatMessageToPage', function(userName, message) {
    console.log(userName + ' ' + message);
});
connection.start()
    .done(function(){ console.log('Now connected, connection ID=' + connection.id); })
    .fail(function(){ console.log('Could not connect'); });

範例程式碼會使用預設的「/signalr」 URL 來連線到您的 SignalR 服務。如需如何指定不同基底 URL 的資訊，請參閱 ASP.NET SignalR 中樞 API 指南 - 伺服器 - /signalr URL。

根據預設，中樞位置是目前的伺服器;如果您要連線到不同的伺服器，請在呼叫 start 方法之前指定 URL，如下列範例所示：

$.connection.hub.url = '<yourbackendurl>;

注意

您通常會先註冊事件處理常式，再呼叫 start 方法來建立連接。如果您想要在建立連接之後註冊某些事件處理常式，可以這麼做，但您必須在呼叫 start 方法之前，先至少註冊其中一個事件處理常式 () 。其中一個原因是應用程式中可能會有許多中樞，但如果您只想使用其中一個中樞，您就不想觸發 OnConnected 每個中樞上的事件。建立連線時，中樞 Proxy 上是否有用戶端方法，就是告知 SignalR 觸發事件的內容 OnConnected 。如果您在呼叫 start 方法之前未註冊任何事件處理常式，您將能夠在中樞上叫用方法，但不會呼叫中樞 OnConnected 的方法，而且不會從伺服器叫用任何用戶端方法。

$.connection.hub 與 $.hubConnection () 建立的物件相同

如您在範例中所見，當您使用產生的 Proxy 時， $.connection.hub 會參考連線物件。當您未使用產生的 Proxy 時，呼叫時，這是您取得 $.hubConnection() 的相同物件。產生的 Proxy 程式碼會執行下列語句，為您建立連線：

在產生的 Proxy 檔案中建立連線

當您使用產生的 Proxy 時，您可以使用任何與連線物件一起 $.connection.hub 執行的動作，但當您未使用產生的 Proxy 時。

啟動方法的非同步執行

方法會 start 以非同步方式執行。它會傳回jQuery Deferred 物件，這表示您可以藉由呼叫、 done 和 fail 等 pipe 方法來新增回呼函式。如果您在建立連接之後想要執行的程式碼，例如呼叫伺服器方法，請將該程式碼放在回呼函式中，或從回呼函式呼叫它。回 .done 呼方法會在連接建立之後執行，並在伺服器上事件處理常式方法中的任何 OnConnected 程式碼完成執行之後執行。

如果您將上述範例中的「Now connected」語句放在方法呼叫之後的下一行程式碼 start ， (不在 .done 回呼) 中，則會在建立連接之前執行該 console.log 行，如下列範例所示：

撰寫建立連線之後所執行程式碼的方式錯誤

如何建立跨網域連線

通常，如果瀏覽器從 http://contoso.com 載入頁面，則 SignalR 連線位於位於的相同網域 http://contoso.com/signalr 中。如果中的 http://contoso.com 頁面與建立連接 http://fabrikam.com/signalr ，即為跨網域連線。基於安全性考慮，預設會停用跨網域連線。

在 SignalR 1.x 中，跨網域要求是由單一 EnableCrossDomain 旗標所控制。此旗標同時控制 JSONP 和 CORS 要求。為了獲得更大的彈性，如果偵測到瀏覽器支援它) ，則所有 CORS 支援都已從 SignalR (JavaScript 用戶端的伺服器元件中移除，而且已提供新的 OWIN 中介軟體來支援這些案例。

如果用戶端 (需要 JSONP 才能在舊版瀏覽器中支援跨網域要求) ，則必須在物件上 HubConfiguration 將設定 EnableJSONP 為 true 來明確啟用，如下所示。預設會停用 JSONP，因為它比 CORS 不安全。

將 Microsoft.Owin.Cors 新增至您的專案： 若要安裝此程式庫，請在套件管理員主控台中執行下列命令：

Install-Package Microsoft.Owin.Cors

此命令會將 2.1.0 版的套件新增至您的專案。

呼叫 UseCors

下列程式碼片段示範如何在 SignalR 2 中實作跨網域連線。

在 SignalR 2 中實作跨網域要求

下列程式碼示範如何在 SignalR 2 專案中啟用 CORS 或 JSONP。此程式碼範例會使用 Map 和 RunSignalR 而非 MapSignalR ，因此 CORS 中介軟體只會針對需要 CORS 支援 (的 SignalR 要求執行，而不是針對 .) Map 中指定的 MapSignalR 路徑上的所有流量，也可以用於任何其他需要針對特定 URL 前置詞執行的中介軟體，而不是針對整個應用程式執行。

using Microsoft.AspNet.SignalR;
using Microsoft.Owin.Cors;
using Owin;
namespace MyWebApplication
{
    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            // Branch the pipeline here for requests that start with "/signalr"
            app.Map("/signalr", map =>
            {
                // Setup the CORS middleware to run before SignalR.
                // By default this will allow all origins. You can 
                // configure the set of origins and/or http verbs by
                // providing a cors options with a different policy.
                map.UseCors(CorsOptions.AllowAll);
                var hubConfiguration = new HubConfiguration 
                {
                    // You can enable JSONP by uncommenting line below.
                    // JSONP requests are insecure but some older browsers (and some
                    // versions of IE) require JSONP to work cross domain
                    // EnableJSONP = true
                };
                // Run the SignalR pipeline. We're not using MapSignalR
                // since this branch already runs under the "/signalr"
                // path.
                map.RunSignalR(hubConfiguration);
            });
        }
    }
}

注意

請勿在程式碼中設定 jQuery.support.cors 為 true。

SignalR 會處理 CORS 的使用。將設定 jQuery.support.cors 為 true 會停用 JSONP，因為它會導致 SignalR 假設瀏覽器支援 CORS。
當您連線到 localhost URL 時，Internet Explorer 10 不會將其視為跨網域連線，因此即使您尚未在伺服器上啟用跨網域連線，應用程式仍會在本機使用 IE 10。
如需搭配 Internet Explorer 9 使用跨網域連線的相關資訊，請參閱此 StackOverflow 執行緒。
如需搭配 Chrome 使用跨網域連線的相關資訊，請參閱此 StackOverflow 執行緒。
範例程式碼會使用預設的「/signalr」 URL 來連線到您的 SignalR 服務。如需如何指定不同基底 URL 的資訊，請參閱 ASP.NET SignalR 中樞 API 指南 - 伺服器 - /signalr URL。

如何設定連線

建立連接之前，您可以指定查詢字串參數或指定傳輸方法。

如何指定查詢字串參數

如果您想要在用戶端連接時將資料傳送至伺服器，您可以將查詢字串參數新增至連線物件。下列範例示範如何在用戶端程式代碼中設定查詢字串參數。

使用產生的 Proxy (呼叫 start 方法之前，請先設定查詢字串值)

$.connection.hub.qs = { 'version' : '1.0' };

在呼叫 start 方法之前先設定查詢字串值， (而不產生 Proxy)

var connection = $.hubConnection();
connection.qs = { 'version' : '1.0' };

下列範例示範如何在伺服器程式碼中讀取查詢字串參數。

public class ContosoChatHub : Hub
{
    public override Task OnConnected()
    {
        var version = Context.QueryString['version'];
        if (version != '1.0')
        {
            Clients.Caller.notifyWrongVersion();
        }
        return base.OnConnected();
    }
}

如何指定傳輸方法

在連線過程中，SignalR 用戶端通常會與伺服器交涉，以判斷伺服器和用戶端所支援的最佳傳輸。如果您已經知道要使用哪個傳輸，您可以在呼叫 start 方法時指定傳輸方法，以略過此交涉程式。

用戶端程式代碼，這個程式碼會使用產生的 Proxy (來指定傳輸方法)

$.connection.hub.start( { transport: 'longPolling' });

指定傳輸方法的用戶端程式代碼 (，而不需產生 Proxy)

var connection = $.hubConnection();
connection.start({ transport: 'longPolling' });

或者，您可以依您希望 SignalR 嘗試的順序來指定多個傳輸方法：

指定自訂傳輸後援配置的用戶端程式代碼， (產生的 Proxy)

$.connection.hub.start( { transport: ['webSockets', 'longPolling'] });

用戶端程式代碼，指定自訂傳輸後援配置 (，而不需產生 Proxy)

var connection = $.hubConnection();
connection.start({ transport: ['webSockets', 'longPolling'] });

您可以使用下列值來指定傳輸方法：

「webSockets」
「foreverFrame」
「serverSentEvents」
「longPolling」

下列範例示範如何找出連接所使用的傳輸方法。

用戶端程式代碼，顯示連接 (所產生 Proxy 所使用的傳輸方法)

$.connection.hub.start().done(function () {
    console.log("Connected, transport = " + $.connection.hub.transport.name);
});

用戶端程式代碼，顯示連接所使用的傳輸方法 (，而不需產生 Proxy)

var connection = $.hubConnection();
connection.hub.start().done(function () {
    console.log("Connected, transport = " + connection.transport.name);
});

如需如何在伺服器程式碼中檢查傳輸方法的資訊，請參閱 ASP.NET SignalR Hubs API 指南 - 伺服器 - 如何從 CoNtext 屬性取得用戶端的相關資訊。如需傳輸和後援的詳細資訊，請參閱 SignalR 簡介 - 傳輸和後援。

如何取得中樞類別的 Proxy

您建立的每個連線物件都會封裝與包含一或多個中樞類別之 SignalR 服務的連線相關資訊。若要與 Hub 類別通訊，如果您使用 Proxy 物件，如果您未使用產生的 Proxy) 或為您產生，則會使用您自己建立的 proxy 物件 (。

在用戶端上，Proxy 名稱是中樞類別名稱的 Camel 大小寫版本。 SignalR 會自動進行這項變更，讓 JavaScript 程式碼符合 JavaScript 慣例。

伺服器上的中樞類別

public class ContosoChatHub : Hub

取得中樞所產生用戶端 Proxy 的參考

var myHubProxy = $.connection.contosoChatHub

建立中樞類別的用戶端 Proxy (而不產生 Proxy)

var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');

如果您使用屬性裝飾 Hub 類別 HubName ，請使用確切的名稱而不變更大小寫。

伺服器上具有 HubName 屬性的中樞類別

[HubName("ContosoChatHub")]
public class ChatHub : Hub

取得中樞所產生用戶端 Proxy 的參考

var contosoChatHubProxy = $.connection.ContosoChatHub

建立中樞類別的用戶端 Proxy (而不產生 Proxy)

var contosoChatHubProxy = connection.createHubProxy('ContosoChatHub');

如何在用戶端上定義伺服器可以呼叫的方法

若要定義伺服器可以從中樞呼叫的方法，請使用 client 所產生 Proxy 的屬性將事件處理常式新增至中樞 Proxy，或者如果您未使用產生的 Proxy，請呼叫 on 方法。參數可以是複雜的物件。

在您呼叫方法來建立連接之前， start 請先新增事件處理常式。 (如果您想要在呼叫 start 方法之後新增事件處理常式，請參閱本檔稍早如何建立連線中的附注，並使用未使用產生的 Proxy 來定義方法的語法。)

方法名稱比對不區分大小寫。例如， Clients.All.addContosoChatMessageToPage 伺服器上的將會在用戶端上執行 AddContosoChatMessageToPage 、 addContosoChatMessageToPage 或 addcontosochatmessagetopage 。

使用產生的 Proxy 在用戶端 (上定義方法)

var contosoChatHubProxy = $.connection.contosoChatHub;
contosoChatHubProxy.client.addContosoChatMessageToPage = function (userName, message) {
    console.log(userName + ' ' + message);
};
$.connection.hub.start()
    .done(function(){ console.log('Now connected, connection ID=' + $.connection.hub.id); })
    .fail(function(){ console.log('Could not Connect!'); });

使用產生的 Proxy 在用戶端 (上定義方法的替代方式)

$.extend(contosoChatHubProxy.client, {
    addContosoChatMessageToPage: function(userName, message) {
    console.log(userName + ' ' + message);
    };
});

在未產生 Proxy 的用戶端 (上定義方法，或在呼叫 start 方法之後新增時)

var connection = $.hubConnection();
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
contosoChatHubProxy.on('addContosoChatMessageToPage', function(userName, message) {
    console.log(userName + ' ' + message);
});
connection.start()
    .done(function(){ console.log('Now connected, connection ID=' + connection.id); })
    .fail(function(){ console.log('Could not connect'); });

呼叫用戶端方法的伺服器程式碼

public class ContosoChatHub : Hub
{
    public void NewContosoChatMessage(string name, string message)
    {
        Clients.All.addContosoChatMessageToPage(name, message);
    }
}

下列範例包含複雜物件做為方法參數。

在用戶端上定義方法，這個方法會使用產生的 Proxy ()

var contosoChatHubProxy = $.connection.contosoChatHub;
contosoChatHubProxy.client.addMessageToPage = function (message) {
    console.log(message.UserName + ' ' + message.Message);
});

在用戶端上定義方法，這個方法會接受複雜的物件 (，而不需產生 Proxy)

var connection = $.hubConnection();
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
chatHubProxy.on('addMessageToPage', function (message) {
    console.log(message.UserName + ' ' + message.Message);
});

定義複雜物件的伺服器程式碼

public class ContosoChatMessage
{
    public string UserName { get; set; }
    public string Message { get; set; }
}

使用複雜物件呼叫用戶端方法的伺服器程式碼

public void SendMessage(string name, string message)
{
    Clients.All.addContosoChatMessageToPage(new ContosoChatMessage() { UserName = name, Message = message });
}

如何從用戶端呼叫伺服器方法

若要從用戶端呼叫伺服器方法，如果您未使用產生的 Proxy，請使用 server 所產生 Proxy 的屬性或 invoke 中樞 Proxy 上的方法。傳回值或參數可以是複雜的物件。

傳入中樞上方法名稱的 camel 大小寫版本。 SignalR 會自動進行這項變更，讓 JavaScript 程式碼符合 JavaScript 慣例。

下列範例示範如何呼叫沒有傳回值的伺服器方法，以及如何呼叫具有傳回值的伺服器方法。

沒有 HubMethodName 屬性的伺服器方法

public class ContosoChatHub : Hub
{
    public void NewContosoChatMessage(ChatMessage message)
    {
        Clients.All.addContosoChatMessageToPage(message);
    }
}

定義傳入參數之複雜物件的伺服器程式碼

public class ChatMessage
{
    public string UserName { get; set; }
    public string Message { get; set; }
}

使用產生的 Proxy) 叫用伺服器方法 (的用戶端程式代碼

contosoChatHubProxy.server.newContosoChatMessage({ UserName: userName, Message: message}).done(function () {
        console.log ('Invocation of NewContosoChatMessage succeeded');
    }).fail(function (error) {
        console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
    });

不使用產生的 Proxy (叫用伺服器方法的用戶端程式代碼)

contosoChatHubProxy.invoke('newContosoChatMessage', { UserName: userName, Message: message}).done(function () {
        console.log ('Invocation of NewContosoChatMessage succeeded');
    }).fail(function (error) {
        console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
    });

如果您使用屬性裝飾 Hub 方法 HubMethodName ，請使用該名稱而不變更大小寫。

具有 HubMethodName 屬性的伺服器方法

public class ContosoChatHub : Hub
{
    [HubMethodName("NewContosoChatMessage")]
    public void NewContosoChatMessage(string name, string message)
    {
        Clients.All.addContosoChatMessageToPage(name, message);
    }
}

使用產生的 Proxy) 叫用伺服器方法 (的用戶端程式代碼

contosoChatHubProxy.server.NewContosoChatMessage(userName, message).done(function () {
        console.log ('Invocation of NewContosoChatMessage succeeded');
    }).fail(function (error) {
        console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
    });

不使用產生的 Proxy (叫用伺服器方法的用戶端程式代碼)

contosoChatHubProxy.invoke('NewContosoChatMessage', userName, message).done(function () {
        console.log ('Invocation of NewContosoChatMessage succeeded');
    }).fail(function (error) {
        console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
    });

上述範例示範如何呼叫沒有傳回值的伺服器方法。下列範例示範如何呼叫具有傳回值的伺服器方法。

具有傳回值之方法的伺服器程式碼

public class StockTickerHub : Hub
{
    public IEnumerable<Stock> GetAllStocks()
    {
        return _stockTicker.GetAllStocks();
    }
}

用於傳回值的 Stock 類別

public class Stock
{
    public string Symbol { get; set; }
    public decimal Price { get; set; }
}

使用產生的 Proxy) 叫用伺服器方法 (的用戶端程式代碼

function init() {
    return stockTickerProxy.server.getAllStocks().done(function (stocks) {
        $.each(stocks, function () {
            var stock = this;
            console.log("Symbol=" + stock.Symbol + " Price=" + stock.Price);
        });
    }).fail(function (error) {
        console.log('Error: ' + error);
    });
}

不使用產生的 Proxy (叫用伺服器方法的用戶端程式代碼)

function init() {
    return stockTickerProxy.invoke('getAllStocks').done(function (stocks) {
        $.each(stocks, function () {
            var stock = this;
            console.log("Symbol=" + stock.Symbol + " Price=" + stock.Price);
        });
    }).fail(function (error) {
        console.log('Error: ' + error);
    });
}

如何處理連線存留期事件

SignalR 提供下列您可以處理的連線存留期事件：

starting：在透過連線傳送任何資料之前引發。
received：在連接上收到任何資料時引發。提供收到的資料。
connectionSlow：當用戶端偵測到緩慢或經常卸載連線時引發。
reconnecting：當基礎傳輸開始重新連線時引發。
reconnected：當基礎傳輸重新連線時引發。
stateChanged：連接狀態變更時引發。提供舊狀態和新狀態 (連線、已連線、重新連線或中斷連線) 。
disconnected：連接中斷連線時引發。

例如，如果您想要在發生可能造成明顯延遲的連線問題時顯示警告訊息，請處理 connectionSlow 事件。

使用產生的 Proxy 處理 connectionSlow 事件 ()

$.connection.hub.connectionSlow(function () {
    console.log('We are currently experiencing difficulties with the connection.')
});

在未產生 Proxy 的情況下處理 connectionSlow 事件 ()

var connection = $.hubConnection();
connection.connectionSlow(function () {
    console.log('We are currently experiencing difficulties with the connection.')
});

如需詳細資訊，請參閱瞭解及處理 SignalR 中的連線存留期事件。

如何處理錯誤

SignalR JavaScript 用戶端會提供 error 您可以為其新增處理常式的事件。您也可以使用 fail 方法，為伺服器方法調用所產生的錯誤新增處理常式。

如果您未在伺服器上明確啟用詳細的錯誤訊息，SignalR 在錯誤之後所傳回的例外狀況物件會包含錯誤的最小資訊。例如，如果呼叫 newContosoChatMessage 失敗，錯誤物件中的錯誤訊息會包含「 There was an error invoking Hub method 'contosoChatHub.newContosoChatMessage'. 」不建議基於安全性考慮，將詳細的錯誤訊息傳送至生產環境的用戶端，但如果您想要啟用詳細的錯誤訊息以進行疑難排解，請在伺服器上使用下列程式碼。

var hubConfiguration = new HubConfiguration();
hubConfiguration.EnableDetailedErrors = true;
app.MapSignalR(hubConfiguration);

下列範例示範如何新增錯誤事件的處理常式。

使用產生的 Proxy 新增錯誤處理常式 ()

$.connection.hub.error(function (error) {
    console.log('SignalR error: ' + error)
});

在沒有產生的 Proxy) 的情況下，新增錯誤處理常式 (

var connection = $.hubConnection();
connection.error(function (error) {
    console.log('SignalR error: ' + error)
});

下列範例示範如何處理來自方法調用的錯誤。

使用產生的 Proxy 處理方法調用 (的錯誤)

contosoChatHubProxy.newContosoChatMessage(userName, message)
    .fail(function(error) { 
        console.log( 'newContosoChatMessage error: ' + error) 
    });

在未產生 Proxy 的情況下處理方法調用 (的錯誤)

contosoChatHubProxy.invoke('newContosoChatMessage', userName, message)
    .fail(function(error) { 
        console.log( 'newContosoChatMessage error: ' + error) 
    });

如果方法調用失敗， error 也會引發事件，因此您在方法處理常式和方法回 .fail 呼中的程式碼 error 會執行。

如何啟用用戶端記錄

若要在連接上啟用用戶端記錄，請在呼叫 start 方法來建立連接之前，先在連線物件上設定 logging 屬性。

使用產生的 Proxy) 啟用記錄 (

$.connection.hub.logging = true;
$.connection.hub.start();

在沒有產生的 Proxy 的情況下啟用記錄 ()

var connection = $.hubConnection();
connection.logging = true;
connection.start();

若要查看記錄，請開啟瀏覽器的開發人員工具，並移至 [主控台] 索引標籤。如需示範如何執行的逐步指示和螢幕擷取畫面的教學課程，請參閱使用 ASP.NET Signalr 進行伺服器廣播 - 啟用記錄。

共用方式為

ASP.NET SignalR 中樞 API 指南 - JavaScript 用戶端

本主題中使用的軟體版本

本主題的舊版

問題和批註

概觀

產生的 Proxy 及其用途

使用產生的 Proxy 的時機

用戶端設定

如何參考動態產生的 Proxy

如何為 SignalR 產生的 Proxy 建立實體檔案

如何建立連線

$.connection.hub 與 $.hubConnection () 建立的物件相同

啟動方法的非同步執行

如何建立跨網域連線

呼叫 UseCors

如何設定連線

如何指定查詢字串參數

如何指定傳輸方法

如何取得中樞類別的 Proxy

如何在用戶端上定義伺服器可以呼叫的方法

如何從用戶端呼叫伺服器方法

如何處理連線存留期事件

如何處理錯誤

如何啟用用戶端記錄

意見反應

其他資源