ASP.NET SignalR Hubs API Guide - Klien .NET (SignalR 1.x)
oleh Patrick Fletcher, Tom Dykstra
Peringatan
Dokumentasi ini bukan untuk versi terbaru SignalR. Lihat ASP.NET Core SignalR.
Dokumen ini menyediakan pengantar untuk menggunakan Hubs API untuk SignalR versi 2 di klien .NET, seperti aplikasi Windows Store (WinRT), WPF, Silverlight, dan konsol.
SIGNALR Hubs API memungkinkan Anda melakukan panggilan prosedur jarak jauh (RPC) dari server ke klien yang terhubung dan dari klien ke server. Dalam kode server, Anda menentukan metode yang dapat dipanggil oleh klien, dan Anda memanggil metode yang berjalan pada klien. Dalam kode klien, Anda menentukan metode yang dapat dipanggil dari server, dan Anda memanggil metode yang berjalan di server. SignalR mengurus semua pipa klien-ke-server untuk Anda.
SignalR juga menawarkan API tingkat bawah yang disebut Koneksi Persisten. Untuk pengenalan SignalR, Hub, dan Koneksi Persisten, atau untuk tutorial yang menunjukkan cara membangun aplikasi SignalR lengkap, lihat SignalR - Memulai.
Gambaran Umum
Dokumen ini berisi bagian berikut:
Cara menentukan metode pada klien yang dapat dipanggil server
Sampel kode aplikasi WPF, Silverlight, dan konsol untuk metode klien yang dapat dipanggil server
Untuk contoh proyek klien .NET, lihat sumber daya berikut ini:
- gustavo-armenta / SignalR-Samples on GitHub.com (WinRT, Silverlight, contoh aplikasi konsol).
- DamianEdwards / SignalR-MoveShapeDemo / MoveShape.Desktop di GitHub.com (contoh WPF).
- SignalR / Microsoft.AspNet.SignalR.Client.Samples di GitHub.com (Contoh aplikasi konsol).
Untuk dokumentasi tentang cara memprogram server atau klien JavaScript, lihat sumber daya berikut:
Tautan ke topik Referensi API adalah ke API versi .NET 4.5. Jika Anda menggunakan .NET 4, lihat topik API versi .NET 4.
Penyiapan klien
Instal paket NuGet Microsoft.AspNet.SignalR.Client (bukan paket Microsoft.AspNet.SignalR ). Paket ini mendukung WinRT, Silverlight, WPF, aplikasi konsol, dan klien Windows Phone, untuk klien .NET 4 dan .NET 4.5.
Jika versi SignalR yang Anda miliki pada klien berbeda dari versi yang Anda miliki di server, SignalR sering dapat beradaptasi dengan perbedaan. Misalnya, ketika SignalR versi 2.0 dirilis dan Anda menginstalnya di server, server akan mendukung klien yang memiliki 1.1.x diinstal serta klien yang telah menginstal 2.0. Jika perbedaan antara versi di server dan versi pada klien terlalu bagus, SignalR memberikan InvalidOperationException pengecualian ketika klien mencoba membuat koneksi. Pesan kesalahannya adalah "You are using a version of the client that isn't compatible with the server. Client version X.X, server version X.X".
Cara membuat koneksi
Sebelum dapat membuat koneksi, Anda harus membuat HubConnection objek dan membuat proksi. Untuk membuat koneksi, panggil Start metode pada HubConnection objek .
var hubConnection = new HubConnection("http://www.contoso.com/");
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock => Console.WriteLine("Stock update for {0} new price {1}", stock.Symbol, stock.Price));
await hubConnection.Start();
Catatan
Untuk klien JavaScript, Anda harus mendaftarkan setidaknya satu penanganan aktivitas sebelum memanggil Start metode untuk membuat koneksi. Ini tidak diperlukan untuk klien .NET. Untuk klien JavaScript, kode proksi yang dihasilkan secara otomatis membuat proksi untuk semua Hub yang ada di server, dan mendaftarkan handler adalah cara Anda menunjukkan Hub mana yang ingin digunakan klien Anda. Tetapi untuk klien .NET Anda membuat proksi Hub secara manual, jadi SignalR mengasumsikan bahwa Anda akan menggunakan Hub apa pun yang Anda buat proksinya.
Kode sampel menggunakan URL "/signalr" default untuk menyambungkan ke layanan SignalR Anda. Untuk informasi tentang cara menentukan URL dasar yang berbeda, lihat ASP.NET Panduan API SignalR Hubs - Server - URL /signalr.
Metode ini Start dijalankan secara asinkron. Untuk memastikan bahwa baris kode berikutnya tidak dijalankan sampai setelah koneksi dibuat, gunakan await dalam metode asinkron ASP.NET 4,5 atau .Wait() dalam metode sinkron. Jangan gunakan .Wait() di klien WinRT.
await connection.Start();
connection.Start().Wait();
Kelas HubConnection ini aman untuk utas.
Koneksi lintas domain dari klien Silverlight
Untuk informasi tentang cara mengaktifkan koneksi lintas domain dari klien Silverlight, lihat Membuat Layanan Tersedia Di Seluruh Batas Domain.
Cara mengonfigurasi koneksi
Sebelum membuat koneksi, Anda bisa menentukan salah satu opsi berikut:
- Batas koneksi bersamaan.
- Parameter string kueri.
- Metode transportasi.
- Header HTTP.
- Sertifikat klien.
Cara mengatur jumlah maksimum koneksi bersamaan di klien WPF
Di klien WPF, Anda mungkin harus meningkatkan jumlah maksimum koneksi bersamaan dari nilai default 2. Nilai yang disarankan adalah 10.
var hubConnection = new HubConnection("http://www.contoso.com/");
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock => Console.WriteLine("Stock update for {0} new price {1}", stock.Symbol, stock.Price));
ServicePointManager.DefaultConnectionLimit = 10;
await hubConnection.Start();
Untuk informasi selengkapnya, lihat ServicePointManager.DefaultConnectionLimit.
Cara menentukan parameter string kueri
Jika Anda ingin mengirim data ke server saat klien tersambung, Anda bisa menambahkan parameter string kueri ke objek koneksi. Contoh berikut menunjukkan cara mengatur parameter string kueri dalam kode klien.
var querystringData = new Dictionary<string, string>();
querystringData.Add("contosochatversion", "1.0");
var connection = new HubConnection("http://contoso.com/", querystringData);
Contoh berikut menunjukkan cara membaca parameter string kueri dalam kode server.
public class StockTickerHub : Hub
{
public override Task OnConnected()
{
var version = Context.QueryString["contosochatversion"];
if (version != "1.0")
{
Clients.Caller.notifyWrongVersion();
}
return base.OnConnected();
}
}
Cara menentukan metode transportasi
Sebagai bagian dari proses koneksi, klien SignalR biasanya bernegosiasi dengan server untuk menentukan transportasi terbaik yang didukung oleh server dan klien. Jika Anda sudah tahu transportasi mana yang ingin Anda gunakan, Anda dapat melewati proses negosiasi ini. Untuk menentukan metode transportasi, teruskan objek transportasi ke metode Mulai. Contoh berikut menunjukkan cara menentukan metode transportasi dalam kode klien.
var hubConnection = new HubConnection("http://www.contoso.com/");
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock => Console.WriteLine("Stock update for {0} new price {1}", stock.Symbol, stock.Price));
await hubConnection.Start(new LongPollingTransport());
Namespace Microsoft.AspNet.SignalR.Client.Transports menyertakan kelas berikut yang dapat Anda gunakan untuk menentukan transportasi.
- LongPollingTransport
- ServerSentEventsTransport
- WebSocketTransport (Hanya tersedia ketika server dan klien menggunakan .NET 4.5.)
- AutoTransport (Secara otomatis memilih transportasi terbaik yang didukung oleh klien dan server. Ini adalah transportasi default. Meneruskan ini ke
Startmetode memiliki efek yang sama seperti tidak meneruskan apa pun.)
Transportasi ForeverFrame tidak termasuk dalam daftar ini karena hanya digunakan oleh browser.
Untuk informasi tentang cara memeriksa metode transportasi dalam kode server, lihat ASP.NET Panduan API SignalR Hubs - Server - Cara mendapatkan informasi tentang klien dari properti Konteks. Untuk informasi selengkapnya tentang transportasi dan fallback, lihat Pengantar SignalR - Transportasi dan Fallback.
Cara menentukan header HTTP
Untuk mengatur header HTTP, gunakan Headers properti pada objek koneksi. Contoh berikut menunjukkan cara menambahkan header HTTP.
hubConnection = new hubConnection("http://www.contoso.com/");
connection.Headers.Add("headername", "headervalue");
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock => Console.WriteLine("Stock update for {0} new price {1}", stock.Symbol, stock.Price));
await connection.Start();
Cara menentukan sertifikat klien
Untuk menambahkan sertifikat klien, gunakan AddClientCertificate metode pada objek koneksi.
hubConnection = new hubConnection("http://www.contoso.com/");
hubConnection.AddClientCertificate(X509Certificate.CreateFromCertFile("MyCert.cer"));
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock => Console.WriteLine("Stock update for {0} new price {1}", stock.Symbol, stock.Price));
await connection.Start();
Cara membuat proksi Hub
Untuk menentukan metode pada klien yang dapat dipanggil Hub dari server, dan untuk memanggil metode di Hub di server, buat proksi untuk Hub dengan memanggil CreateHubProxy objek koneksi. String yang Anda berikan CreateHubProxy adalah nama kelas Hub Anda, atau nama yang ditentukan oleh HubName atribut jika string digunakan di server. Pencocokan nama tidak peka huruf besar/kecil.
Kelas hub di server
public class StockTickerHub : Hub
Membuat proksi klien untuk kelas Hub
var hubConnection = new HubConnection("http://www.contoso.com/");
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock => Console.WriteLine("Stock update for {0} new price {1}", stock.Symbol, stock.Price));
await hubConnection.Start();
Jika Anda menghias kelas Hub dengan HubName atribut , gunakan nama tersebut.
Kelas hub di server
[HubName("stockTicker")]
public class StockTickerHub : Hub
Membuat proksi klien untuk kelas Hub
var hubConnection = new HubConnection("http://www.contoso.com/");
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("stockTicker");
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock =>
Console.WriteLine("Stock update for {0} new price {1}", stock.Symbol, stock.Price));
await hubConnection.Start();
Objek proksi aman untuk utas. Bahkan, jika Anda memanggil HubConnection.CreateHubProxy beberapa kali dengan yang sama hubName, Anda mendapatkan objek cache IHubProxy yang sama.
Cara menentukan metode pada klien yang dapat dipanggil server
Untuk menentukan metode yang dapat dipanggil server, gunakan metode proksi On untuk mendaftarkan penanganan aktivitas.
Pencocokan nama metode tidak peka huruf besar/kecil. Misalnya, Clients.All.UpdateStockPrice pada server akan menjalankan updateStockPrice, , updatestockpriceatau UpdateStockPrice pada klien.
Platform klien yang berbeda memiliki persyaratan yang berbeda tentang cara Anda menulis kode metode untuk memperbarui UI. Contoh yang ditampilkan adalah untuk klien WinRT (Windows Store .NET). Contoh aplikasi WPF, Silverlight, dan konsol disediakan di bagian terpisah nanti dalam topik ini.
Metode tanpa parameter
Jika metode yang Anda tangani tidak memiliki parameter, gunakan kelebihan On metode non-generik:
Kode server memanggil metode klien tanpa parameter
public class StockTickerHub : Hub
{
public void NotifyAllClients()
{
Clients.All.Notify();
}
}
Kode Klien WinRT untuk metode yang dipanggil dari server tanpa parameter (lihat contoh WPF dan Silverlight nanti dalam topik ini)
var hubConnection = new HubConnection("http://www.contoso.com/");
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHub.On("notify", () =>
// Context is a reference to SynchronizationContext.Current
Context.Post(delegate
{
textBox.Text += "Notified!\n";
}, null)
);
await hubConnection.Start();
Metode dengan parameter, menentukan jenis parameter
Jika metode yang Anda tangani memiliki parameter, tentukan jenis parameter sebagai jenis On generik metode. Ada kelebihan beban umum metode On untuk memungkinkan Anda menentukan hingga 8 parameter (4 pada Windows Phone 7). Dalam contoh berikut, satu parameter dikirim ke UpdateStockPrice metode .
Metode klien panggilan kode server dengan parameter
public void BroadcastStockPrice(Stock stock)
{
context.Clients.Others.UpdateStockPrice(stock);
}
Kelas Stock yang digunakan untuk parameter
public class Stock
{
public string Symbol { get; set; }
public decimal Price { get; set; }
}
Kode Klien WinRT untuk metode yang dipanggil dari server dengan parameter (lihat contoh WPF dan Silverlight nanti dalam topik ini)
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock =>
// Context is a reference to SynchronizationContext.Current
Context.Post(delegate
{
textBox.Text += string.Format("Stock update for {0} new price {1}\n", stock.Symbol, stock.Price);
}, null)
);
Metode dengan parameter, menentukan objek dinamis untuk parameter
Sebagai alternatif untuk menentukan parameter sebagai jenis On generik metode, Anda dapat menentukan parameter sebagai objek dinamis:
Metode klien panggilan kode server dengan parameter
public void BroadcastStockPrice(Stock stock)
{
context.Clients.Others.UpdateStockPrice(stock);
}
Kelas Stock yang digunakan untuk parameter
public class Stock
{
public string Symbol { get; set; }
public decimal Price { get; set; }
}
Kode Klien WinRT untuk metode yang dipanggil dari server dengan parameter, menggunakan objek dinamis untuk parameter (lihat contoh WPF dan Silverlight nanti dalam topik ini)
stockTickerHubProxy.On("UpdateStockPrice", stock =>
// Context is a reference to SynchronizationContext.Current
Context.Post(delegate
{
textBox.Text += string.Format("Stock update for {0} new price {1}\n", stock.Symbol, stock.Price);
}, null)
);
Cara menghapus handler
Untuk menghapus handler, panggil metodenya Dispose .
Kode klien untuk metode yang dipanggil dari server
var updateStockPriceHandler = stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock =>
Context.Post(delegate
{
textBox.Text += string.Format("Stock update for {0} new price {1}\n", stock.Symbol, stock.Price);
}, null)
);
Kode klien untuk menghapus handler
updateStockPriceHandler.Dispose();
Cara memanggil metode server dari klien
Untuk memanggil metode di server, gunakan Invoke metode pada proksi Hub.
Jika metode server tidak memiliki nilai pengembalian, gunakan kelebihan Invoke metode yang tidak umum.
Kode server untuk metode yang tidak memiliki nilai pengembalian
public class StockTickerHub : Hub
{
public void JoinGroup(string groupName)
{
Groups.Add(Context.ConnectionId, groupName);
}
}
Kode klien memanggil metode yang tidak memiliki nilai pengembalian
stockTickerHubProxy.Invoke("JoinGroup", hubConnection.ConnectionID, "SignalRChatRoom");
Jika metode server memiliki nilai pengembalian, tentukan jenis pengembalian sebagai jenis Invoke generik metode.
Kode server untuk metode yang memiliki nilai pengembalian dan mengambil parameter jenis kompleks
public IEnumerable<Stock> AddStock(Stock stock)
{
_stockTicker.AddStock(stock);
return _stockTicker.GetAllStocks();
}
Kelas Stock yang digunakan untuk parameter dan nilai pengembalian
public class Stock
{
public string Symbol { get; set; }
public decimal Price { get; set; }
}
Kode klien memanggil metode yang memiliki nilai pengembalian dan mengambil parameter jenis kompleks, dalam metode asinkron ASP.NET 4,5
var stocks = await stockTickerHub.Invoke<IEnumerable<Stock>>("AddStock", new Stock() { Symbol = "MSFT" });
foreach (Stock stock in stocks)
{
textBox.Text += string.Format("Symbol: {0} price: {1}\n", stock.Symbol, stock.Price);
}
Kode klien memanggil metode yang memiliki nilai pengembalian dan mengambil parameter jenis kompleks, dalam metode sinkron
var stocks = stockTickerHub.Invoke<IEnumerable<Stock>>("AddStock", new Stock() { Symbol = "MSFT" }).Result;
foreach (Stock stock in stocks)
{
textBox.Text += string.Format("Symbol: {0} price: {1}\n", stock.Symbol, stock.Price);
}
Metode ini Invoke dijalankan secara asinkron dan mengembalikan Task objek. Jika Anda tidak menentukan await atau .Wait(), baris kode berikutnya akan dijalankan sebelum metode yang Anda panggil selesai dieksekusi.
Cara menangani peristiwa seumur hidup koneksi
SignalR menyediakan peristiwa seumur hidup koneksi berikut yang dapat Anda tangani:
Received: Dimunculkan ketika ada data yang diterima pada koneksi. Menyediakan data yang diterima.ConnectionSlow: Dimunculkan saat klien mendeteksi koneksi yang lambat atau sering terputus.Reconnecting: Dinaikkan ketika transportasi yang mendasar mulai terhubung kembali.Reconnected: Dinaikkan ketika transportasi yang mendasar telah tersambung kembali.StateChanged: Dimunculkan saat status koneksi berubah. Menyediakan status lama dan status baru. Untuk informasi tentang nilai status koneksi, lihat Enumerasi ConnectionState.Closed: Dinaikkan ketika koneksi terputus.
Misalnya, jika Anda ingin menampilkan pesan peringatan untuk kesalahan yang tidak fatal tetapi menyebabkan masalah koneksi terputus-terputus, seperti lambat atau sering menghilangkan koneksi, tangani ConnectionSlow peristiwa.
hubConnection.ConnectionSlow += () => Console.WriteLine("Connection problems.");
Untuk informasi selengkapnya, lihat Memahami dan Menangani Peristiwa Seumur Hidup Koneksi di SignalR.
Cara menangani kesalahan
Jika Anda tidak secara eksplisit mengaktifkan pesan kesalahan terperinci di server, objek pengecualian yang dikembalikan SignalR setelah kesalahan berisi informasi minimal tentang kesalahan tersebut. Misalnya, jika panggilan ke newContosoChatMessage gagal, pesan kesalahan dalam objek kesalahan berisi "There was an error invoking Hub method 'contosoChatHub.newContosoChatMessage'." Mengirim pesan kesalahan terperinci ke klien dalam produksi tidak disarankan karena alasan keamanan, tetapi jika Anda ingin mengaktifkan pesan kesalahan terperinci untuk tujuan pemecahan masalah, gunakan kode berikut di server.
var hubConfiguration = new HubConfiguration();
hubConfiguration.EnableDetailedErrors = true;
RouteTable.Routes.MapHubs(hubConfiguration);
Untuk menangani kesalahan yang dimunculkan SignalR, Anda dapat menambahkan handler untuk Error peristiwa pada objek koneksi.
hubConnection.Error += ex => Console.WriteLine("SignalR error: {0}", ex.Message);
Untuk menangani kesalahan dari pemanggilan metode, bungkus kode dalam blok try-catch.
try
{
IEnumerable<Stock> stocks = await stockTickerHub.Invoke<IEnumerable<Stock>>("GetAllStocks");
foreach (Stock stock in stocks)
{
Console.WriteLine("Symbol: {0} price: {1}", stock.Symbol, stock.Price);
}
}
catch (Exception ex)
{
Console.WriteLine("Error invoking GetAllStocks: {0}", ex.Message);
}
Cara mengaktifkan pengelogan sisi klien
Untuk mengaktifkan pengelogan sisi klien, atur TraceLevel properti dan TraceWriter pada objek koneksi.
var hubConnection = new HubConnection("http://www.contoso.com/");
hubConnection.TraceLevel = TraceLevels.All;
hubConnection.TraceWriter = Console.Out;
IHubProxy stockTickerHubProxy = hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock => Console.WriteLine("Stock update for {0} new price {1}", stock.Symbol, stock.Price));
await hubConnection.Start();
Sampel kode aplikasi WPF, Silverlight, dan konsol untuk metode klien yang dapat dipanggil server
Sampel kode yang ditampilkan sebelumnya untuk menentukan metode klien yang dapat dipanggil server berlaku untuk klien WinRT. Sampel berikut menunjukkan kode yang setara untuk klien aplikasi WPF, Silverlight, dan konsol.
Metode tanpa parameter
Kode klien WPF untuk metode yang dipanggil dari server tanpa parameter
stockTickerHub.On<Stock>("notify", () =>
Dispatcher.InvokeAsync(() =>
{
SignalRTextBlock.Text += string.Format("Notified!");
})
);
Kode klien Silverlight untuk metode yang dipanggil dari server tanpa parameter
stockTickerHub.On<Stock>("notify", () =>
// Context is a reference to SynchronizationContext.Current
Context.Post(delegate
{
textBox.Text += "Notified!";
}, null)
);
Kode klien aplikasi konsol untuk metode yang dipanggil dari server tanpa parameter
stockTickerHubProxyProxy.On("Notify", () => Console.WriteLine("Notified!"));
Metode dengan parameter, menentukan jenis parameter
Kode klien WPF untuk metode yang dipanggil dari server dengan parameter
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock =>
Dispatcher.InvokeAsync(() =>
{
textBox.Text += string.Format("Stock update for {0} new price {1}\n", stock.Symbol, stock.Price);
})
);
Kode klien Silverlight untuk metode yang dipanggil dari server dengan parameter
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock =>
// Context is a reference to SynchronizationContext.Current
Context.Post(delegate
{
textBox.Text += string.Format("Stock update for {0} new price {1}\n", stock.Symbol, stock.Price);
}, null)
);
Kode klien aplikasi konsol untuk metode yang dipanggil dari server dengan parameter
stockTickerHubProxy.On<Stock>("UpdateStockPrice", stock =>
Console.WriteLine("Symbol {0} Price {1}", stock.Symbol, stock.Price));
Metode dengan parameter, menentukan objek dinamis untuk parameter
Kode klien WPF untuk metode yang dipanggil dari server dengan parameter, menggunakan objek dinamis untuk parameter
stockTickerHubProxy.On("UpdateStockPrice", stock =>
Dispatcher.InvokeAsync(() =>
{
textBox.Text += string.Format("Stock update for {0} new price {1}\n", stock.Symbol, stock.Price);
})
);
Kode klien Silverlight untuk metode yang dipanggil dari server dengan parameter, menggunakan objek dinamis untuk parameter
stockTickerHubProxy.On("UpdateStockPrice", stock =>
// Context is a reference to SynchronizationContext.Current
Context.Post(delegate
{
textBox.Text += string.Format("Stock update for {0} new price {1}\n", stock.Symbol, stock.Price);
}, null)
);
Kode klien aplikasi konsol untuk metode yang dipanggil dari server dengan parameter, menggunakan objek dinamis untuk parameter
stockTickerHubProxy.On("UpdateStockPrice", stock =>
Console.WriteLine("Symbol {0} Price {1}", stock.Symbol, stock.Price));
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk