Konfiguracja ASP.NET Core SignalR
JSOpcje serializacji ON/MessagePack
ASP.NET Core SignalR obsługuje dwa protokoły kodowania komunikatów: JSON i MessagePack. Każdy protokół ma opcje konfiguracji serializacji.
JSW przypadku serializacji można skonfigurować na serwerze przy użyciu AddJsonProtocol metody rozszerzenia. AddJsonProtocol
można dodać po AddSignalR w pliku Startup.ConfigureServices
. Metoda AddJsonProtocol
przyjmuje delegata, który odbiera options
obiekt. Właściwość PayloadSerializerOptions tego obiektu jest obiektem System.Text.Json
JsonSerializerOptions , który może służyć do konfigurowania serializacji argumentów i zwracanych wartości. Aby uzyskać więcej informacji, zobacz dokumentację System.Text.Json.
Aby na przykład skonfigurować serializator tak, aby nie zmieniał wielkości liter nazw właściwości, a nie domyślne nazwy przypadków camel, użyj następującego kodu w pliku Program.cs
:
builder.Services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
W kliencie platformy .NET w systemie istnieje ta sama AddJsonProtocol
metoda rozszerzenia.HubConnectionBuilder Aby Microsoft.Extensions.DependencyInjection
rozpoznać metodę rozszerzenia, należy zaimportować przestrzeń nazw:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Uwaga
Obecnie nie można skonfigurować JSserializacji ON w kliencie JavaScript.
Przełączanie do pliku Newtonsoft.Json
Jeśli potrzebujesz funkcji Newtonsoft.Json
, które nie są obsługiwane w programie System.Text.Json
, zobacz Przełączanie na Newtonsoft.Json
.
Opcje serializacji messagePack
Serializacji MessagePack można skonfigurować, podając delegata do wywołania AddMessagePackProtocol . Aby uzyskać więcej informacji, zobacz MessagePack w pliku SignalR .
Uwaga
Obecnie nie można skonfigurować serializacji MessagePack w kliencie JavaScript.
Konfigurowanie opcji serwera
W poniższej tabeli opisano opcje konfigurowania SignalR koncentratorów:
Opcja | Wartość domyślna | opis |
---|---|---|
ClientTimeoutInterval |
30 sekund | Serwer rozważa rozłączenie klienta, jeśli nie odebrał komunikatu (w tym zachowania aktywności) w tym interwale. Może upłynąć dłużej niż ten interwał limitu czasu, aby klient został oznaczony jako odłączony ze względu na sposób implementacji. Zalecana wartość jest dwukrotnie ceniona KeepAliveInterval . |
HandshakeTimeout |
15 sekund | Jeśli klient nie wysyła początkowego komunikatu uzgadniania w tym przedziale czasu, połączenie zostanie zamknięte. Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Jeśli serwer nie wysłał komunikatu w tym interwale, wiadomość ping zostanie wysłana automatycznie, aby zachować otwarte połączenie. Podczas zmiany KeepAliveInterval zmień ServerTimeout ustawienie lub serverTimeoutInMilliseconds na kliencie. Zalecana ServerTimeout wartość lub serverTimeoutInMilliseconds jest dwukrotnie ceniona KeepAliveInterval . |
SupportedProtocols |
Wszystkie zainstalowane protokoły | Protokoły obsługiwane przez to centrum. Domyślnie wszystkie protokoły zarejestrowane na serwerze są dozwolone. Protokoły można usunąć z tej listy, aby wyłączyć określone protokoły dla poszczególnych centrów. |
EnableDetailedErrors |
false |
Jeśli true , szczegółowe komunikaty wyjątków są zwracane do klientów, gdy wyjątek jest zgłaszany w metodzie Centrum. Wartością domyślną jest to false , że te komunikaty wyjątków mogą zawierać poufne informacje. |
StreamBufferCapacity |
10 |
Maksymalna liczba elementów, które mogą być buforowane dla strumieni przekazywania klienta. Jeśli ten limit zostanie osiągnięty, przetwarzanie wywołań zostanie zablokowane, dopóki serwer nie przetworzy elementów strumienia. |
MaximumReceiveMessageSize |
32 KB | Maksymalny rozmiar pojedynczego przychodzącego komunikatu centrum. Zwiększenie wartości może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS). |
MaximumParallelInvocationsPerClient |
1 | Maksymalna liczba metod koncentratora, które każdy klient może wywołać równolegle przed kolejkowaniem. |
DisableImplicitFromServicesParameters |
false |
Argumenty metody koncentratora są rozpoznawane z di, jeśli to możliwe. |
Opcje można skonfigurować dla wszystkich centrów, udostępniając delegat opcji do wywołania AddSignalR
w programie Program.cs
.
builder.Services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
Opcje pojedynczego koncentratora zastępują opcje globalne dostępne w programie AddSignalR
i można je skonfigurować przy użyciu polecenia AddHubOptions:
builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Zaawansowane opcje konfiguracji PROTOKOŁU HTTP
Służy HttpConnectionDispatcherOptions
do konfigurowania ustawień zaawansowanych związanych z transportami i zarządzaniem buforem pamięci. Te opcje są konfigurowane przez przekazanie delegata do MapHub elementu w programie Program.cs
.
using Microsoft.AspNetCore.Http.Connections;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddSignalR();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
}
);
app.Run();
W poniższej tabeli opisano opcje konfigurowania zaawansowanych opcji http platformy ASP.NET Core SignalR:
Opcja | Wartość domyślna | opis |
---|---|---|
ApplicationMaxBufferSize |
64 KB | Maksymalna liczba bajtów odebranych od klienta, który buforuje serwer przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
TransportMaxBufferSize |
64 KB | Maksymalna liczba bajtów wysyłanych przez aplikację buforowanych przez serwer przed zaobserwowanym backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze buforowanie większych komunikatów bez oczekiwania na tłumienie wsteczne, ale może zwiększyć zużycie pamięci. |
AuthorizationData |
Dane automatycznie zbierane z atrybutów zastosowanych Authorize do klasy Hub. |
Lista obiektów używanych IAuthorizeData do określenia, czy klient jest autoryzowany do łączenia się z koncentratorem. |
Transports |
Wszystkie transporty są włączone. | Bit flaguje wyliczenie HttpTransportType wartości, które mogą ograniczyć transporty, których klient może użyć do nawiązania połączenia. |
LongPolling |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu długiego sondowania. |
WebSockets |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu obiektów WebSocket. |
MinimumProtocolVersion |
0 | Określ minimalną wersję protokołu negocjowania. Służy to do ograniczania klientów do nowszych wersji. |
CloseOnAuthenticationExpiration |
fałsz | Ustaw tę opcję, aby włączyć śledzenie wygasania uwierzytelniania, co spowoduje zamknięcie połączeń po wygaśnięciu tokenu. |
Transport Long Polling ma dodatkowe opcje, które można skonfigurować przy użyciu LongPolling
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
PollTimeout |
90 sekund | Maksymalny czas oczekiwania serwera na wysłanie komunikatu do klienta przed zakończeniem pojedynczego żądania sondowania. Zmniejszenie tej wartości powoduje, że klient częściej wysyła nowe żądania sondowania. |
Transport protokołu WebSocket ma dodatkowe opcje, które można skonfigurować przy użyciu WebSockets
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
CloseTimeout |
5 s | Po zamknięciu serwera, jeśli klient nie może zamknąć w tym przedziale czasu, połączenie zostanie zakończone. |
SubProtocolSelector |
null |
Delegat, który może służyć do ustawiania nagłówka Sec-WebSocket-Protocol na wartość niestandardową. Delegat odbiera wartości żądane przez klienta jako dane wejściowe i oczekuje się, że zwróci żądaną wartość. |
Konfigurowanie opcji klienta
Opcje klienta można skonfigurować na typie HubConnectionBuilder
(dostępnym na klientach .NET i JavaScript). Jest ona również dostępna w kliencie Java, ale podklasa HttpHubConnectionBuilder
zawiera opcje konfiguracji konstruktora, a także na HubConnection
samym kliencie.
Konfigurowanie rejestrowania
Rejestrowanie jest konfigurowane w kliencie .NET przy użyciu ConfigureLogging
metody . Dostawcy rejestrowania i filtry można zarejestrować w taki sam sposób, jak na serwerze. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rejestrowania w usłudze ASP.NET Core .
Uwaga
Aby zarejestrować dostawców rejestrowania, należy zainstalować niezbędne pakiety. Aby uzyskać pełną listę, zobacz sekcję Wbudowane dostawcy rejestrowania w dokumentacji.
Aby na przykład włączyć rejestrowanie konsoli, zainstaluj Microsoft.Extensions.Logging.Console
pakiet NuGet. Wywołaj metodę AddConsole
rozszerzenia:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
W kliencie JavaScript istnieje podobna configureLogging
metoda. Podaj wartość wskazującą LogLevel
minimalny poziom komunikatów dziennika do utworzenia. Dzienniki są zapisywane w oknie konsoli przeglądarki.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
LogLevel
Zamiast wartości można również podać string
wartość reprezentującą nazwę poziomu dziennika. Jest to przydatne podczas konfigurowania SignalR rejestrowania w środowiskach, w których nie masz dostępu do LogLevel
stałych.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
W poniższej tabeli wymieniono dostępne poziomy dziennika. Wartość, którą podajesz, ustawia configureLogging
minimalny poziom dziennika, który zostanie zarejestrowany. Komunikaty zarejestrowane na tym poziomie lub poziomy wymienione po niej w tabeli zostaną zarejestrowane.
String | PoziomRejestrowania |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info lub information |
LogLevel.Information |
warn lub warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Uwaga
Aby całkowicie wyłączyć rejestrowanie, określ signalR.LogLevel.None
metodę configureLogging
.
Aby uzyskać więcej informacji na temat rejestrowania, zobacz dokumentację SignalRdiagnostyki.
Klient SignalR Java używa biblioteki SLF4J do rejestrowania. Jest to interfejs API rejestrowania wysokiego poziomu, który umożliwia użytkownikom biblioteki wybranie własnej implementacji rejestrowania przez wprowadzenie określonej zależności rejestrowania. Poniższy fragment kodu pokazuje, jak używać go java.util.logging
z klientem SignalR Java.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Jeśli nie skonfigurujesz rejestrowania w zależnościach, SLF4J ładuje domyślny rejestrator bez operacji z następującym komunikatem ostrzegawczym:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Można to bezpiecznie zignorować.
Konfigurowanie dozwolonych transportów
Transporty używane przez SignalR program można skonfigurować w wywołaniu WithUrl
(withUrl
w języku JavaScript). Bitowe or wartości parametru HttpTransportType
można użyć do ograniczenia klienta do używania tylko określonych transportów. Wszystkie transporty są domyślnie włączone.
Na przykład aby wyłączyć transport zdarzeń wysłanych przez serwer, ale zezwalać na połączenia WebSocket i Long Polling:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
W kliencie języka JavaScript transporty są konfigurowane przez ustawienie transport
pola w obiekcie options udostępnionym na wartość withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
W tej wersji obiektów websocket klienta Java jest jedynym dostępnym transportem.
W kliencie Java transport jest wybierany przy użyciu withTransport
metody w pliku HttpHubConnectionBuilder
. Klient Języka Java domyślnie używa transportu obiektów WebSocket.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Uwaga
Klient SignalR java nie obsługuje jeszcze powrotu transportu.
Konfigurowanie uwierzytelniania elementu nośnego
Aby udostępnić dane uwierzytelniania wraz z żądaniami SignalR , użyj AccessTokenProvider
opcji (accessTokenFactory
w języku JavaScript), aby określić funkcję zwracającą żądany token dostępu. W kliencie platformy .NET ten token dostępu jest przekazywany jako token HTTP "Uwierzytelnianie elementu nośnego" (przy użyciu Authorization
nagłówka o typie Bearer
). W kliencie JavaScript token dostępu jest używany jako token elementu nośnego, z wyjątkiem kilku przypadków, w których interfejsy API przeglądarki ograniczają możliwość stosowania nagłówków (w szczególności w żądaniach zdarzeń wysłanych przez serwer i obiektów WebSocket). W takich przypadkach token dostępu jest udostępniany jako wartość access_token
ciągu zapytania .
W kliencie AccessTokenProvider
platformy .NET można określić opcję przy użyciu delegata opcji w programie WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
W kliencie JavaScript token dostępu jest konfigurowany przez ustawienie accessTokenFactory
pola w obiekcie options w withUrl
pliku :
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
W kliencie SignalR języka Java można skonfigurować token elementu nośnego do użycia do uwierzytelniania, zapewniając fabrykę tokenów dostępu do programu HttpHubConnectionBuilder. Użyj funkcji withAccessTokenFactory, aby udostępnić pojedynczy <ciąg> RxJava. Wywołanie metody Single.defer umożliwia napisanie logiki w celu utworzenia tokenów dostępu dla klienta.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Konfigurowanie limitu czasu i opcji zachowania aktywności
Dodatkowe opcje konfigurowania limitu czasu i zachowania utrzymania aktywności:
Opcja | Wartość domyślna | opis |
---|---|---|
WithServerTimeout |
30 sekund (30 000 milisekund) | Limit czasu działania serwera i jest ustawiany bezpośrednio na .HubConnectionBuilder Jeśli serwer nie wysłał komunikatu w tym interwale, klient uzna serwer za odłączony i wyzwoli Closed zdarzenie (onclose w języku JavaScript). Ta wartość musi być wystarczająco duża, aby wiadomość ping została wysłana z serwera i odebrana przez klienta w przedziale czasu. Zalecana wartość jest liczbą co najmniej dwukrotnie większą niż wartość interwału utrzymania aktywności serwera (WithKeepAliveInterval ), aby umożliwić czas odebrania poleceń ping. |
HandshakeTimeout |
15 sekund | Limit czasu dla uzgadniania początkowego HubConnection serwera i jest dostępny w samym obiekcie. Jeśli serwer nie wysyła odpowiedzi uzgadniania w tym interwale, klient anuluje uzgadnianie i wyzwala Closed zdarzenie (onclose w języku JavaScript). Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
WithKeepAliveInterval |
15 sekund | Określa interwał, w którym klient wysyła komunikaty ping i jest ustawiany bezpośrednio na .HubConnectionBuilder To ustawienie umożliwia serwerowi wykrywanie twardych rozłączeń, takich jak odłączanie komputera od sieci przez klienta. Wysłanie dowolnego komunikatu z klienta spowoduje zresetowanie czasomierza do początku interwału. Jeśli klient nie wysłał komunikatu w ClientTimeoutInterval zestawie na serwerze, serwer uzna klienta za odłączonego. |
W kliencie .NET wartości limitu czasu są określane jako TimeSpan
wartości.
W poniższym przykładzie przedstawiono wartości, które są dwukrotnie wartościami domyślnymi:
var builder = new HubConnectionBuilder()
.WithUrl(Navigation.ToAbsoluteUri("/chathub"))
.WithServerTimeout(TimeSpan.FromSeconds(60))
.WithKeepAliveInterval(TimeSpan.FromSeconds(30))
.Build();
builder.On<string, string>("ReceiveMessage", (user, message) => ...
await builder.StartAsync();
Konfigurowanie stanowego ponownego nawiązywania połączenia
SignalR ponowne połączenie stanowe zmniejsza postrzegany przestój klientów, którzy mają tymczasowe rozłączenie w połączeniu sieciowym, na przykład podczas przełączania połączeń sieciowych lub krótkiej tymczasowej utraty dostępu.
Stanowe ponowne nawiązywanie połączenia umożliwia wykonanie następujących kroków:
- Tymczasowo buforowanie danych na serwerze i kliencie.
- Potwierdzenie odebranych komunikatów (ACK-ing) zarówno przez serwer, jak i klienta.
- Rozpoznawanie, gdy połączenie jest w górę i ponowne tworzenie komunikatów, które mogły zostać wysłane, gdy połączenie nie działa.
Stanowe ponowne połączenie jest dostępne w programie ASP.NET Core 8.0 lub nowszym.
Wybierz stanowe ponowne połączenie zarówno w punkcie końcowym centrum serwera, jak i kliencie:
Zaktualizuj konfigurację punktu końcowego centrum serwera, aby włączyć
AllowStatefulReconnects
opcję:app.MapHub<MyHub>("/hubName", options => { options.AllowStatefulReconnects = true; });
Opcjonalnie maksymalny rozmiar buforu w bajtach dozwolonych przez serwer można ustawić globalnie lub dla określonego centrum z opcją
StatefulReconnectBufferSize
:Zestaw
StatefulReconnectBufferSize
opcji globalnie:builder.AddSignalR(o => o.StatefulReconnectBufferSize = 1000);
Zestaw
StatefulReconnectBufferSize
opcji dla określonego centrum:builder.AddSignalR().AddHubOptions<MyHub>(o => o.StatefulReconnectBufferSize = 1000);
Opcja
StatefulReconnectBufferSize
jest opcjonalna z wartością domyślną 100 000 bajtów.Zaktualizuj kod klienta JavaScript lub TypeScript, aby włączyć
withStatefulReconnect
tę opcję:const builder = new signalR.HubConnectionBuilder() .withUrl("/hubname") .withStatefulReconnect({ bufferSize: 1000 }); // Optional, defaults to 100,000 const connection = builder.build();
Opcja
bufferSize
jest opcjonalna z wartością domyślną 100 000 bajtów.Zaktualizuj kod klienta platformy .NET, aby włączyć
WithStatefulReconnect
opcję:var builder = new HubConnectionBuilder() .WithUrl("<hub url>") .WithStatefulReconnect(); builder.Services.Configure<HubConnectionOptions>(o => o.StatefulReconnectBufferSize = 1000); var hubConnection = builder.Build();
Opcja
StatefulReconnectBufferSize
jest opcjonalna z wartością domyślną 100 000 bajtów.
Konfigurowanie dodatkowych opcji
Dodatkowe opcje można skonfigurować w metodzie WithUrl
(withUrl
w języku JavaScript) w systemie HubConnectionBuilder
lub w różnych interfejsach API konfiguracji w kliencie HttpHubConnectionBuilder
Java:
Opcja platformy .NET | Wartość domyślna | opis |
---|---|---|
AccessTokenProvider |
null |
Funkcja zwracająca ciąg, który jest dostarczany jako token uwierzytelniania elementu nośnego w żądaniach HTTP. |
SkipNegotiation |
false |
Ustaw tę opcję, aby true pominąć krok negocjacji. Obsługiwane tylko wtedy, gdy transport obiektów WebSockets jest jedynym włączonym transportem. Nie można włączyć tego ustawienia w przypadku korzystania z usługi platformy Azure SignalR . |
ClientCertificates |
Pusty | Kolekcja certyfikatów TLS do wysyłania do uwierzytelniania żądań. |
Cookies |
Pusty | Kolekcja żądań HTTP cookiedo wysłania przy użyciu każdego żądania HTTP. |
Credentials |
Pusty | Poświadczenia do wysłania przy użyciu każdego żądania HTTP. |
CloseTimeout |
5 s | Tylko obiekty WebSocket. Maksymalny czas oczekiwania klienta po zamknięciu serwera w celu potwierdzenia zamknięcia żądania zamknięcia. Jeśli serwer nie potwierdzi zamknięcia w tym czasie, klient rozłącza się. |
Headers |
Pusty | Mapa dodatkowych nagłówków HTTP do wysłania przy użyciu każdego żądania HTTP. |
HttpMessageHandlerFactory |
null |
Pełnomocnik, który może służyć do konfigurowania lub zastępowania używanego HttpMessageHandler do wysyłania żądań HTTP. Nie jest używany w przypadku połączeń protokołu WebSocket. Ten delegat musi zwrócić wartość inną niż null i otrzymuje wartość domyślną jako parametr. Zmodyfikuj ustawienia dla tej wartości domyślnej i zwróć je lub zwróć nowe HttpMessageHandler wystąpienie. Podczas zastępowania programu obsługi pamiętaj, aby skopiować ustawienia, które chcesz zachować z dostarczonej procedury obsługi, w przeciwnym razie skonfigurowane opcje (takie jak Cookies i Nagłówki) nie będą stosowane do nowej procedury obsługi. |
Proxy |
null |
Serwer proxy HTTP do użycia podczas wysyłania żądań HTTP. |
UseDefaultCredentials |
false |
Ustaw tę wartość logiczną, aby wysyłać domyślne poświadczenia dla żądań HTTP i WebSocket. Umożliwia to korzystanie z uwierzytelniania systemu Windows. |
WebSocketConfiguration |
null |
Delegat, który może służyć do konfigurowania dodatkowych opcji protokołu WebSocket. Odbiera wystąpienie ClientWebSocketOptions , którego można użyć do skonfigurowania opcji. |
ApplicationMaxBufferSize |
1 MB | Maksymalna liczba bajtów odebranych z serwera buforowanych przez klienta przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia klientowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
TransportMaxBufferSize |
1 MB | Maksymalna liczba bajtów wysyłanych przez aplikację użytkownika buforowanych przez klienta przed zaobserwowaniem backpressure. Zwiększenie tej wartości umożliwia klientowi szybsze buforowanie większych komunikatów bez oczekiwania na tłumienie wsteczne, ale może zwiększyć zużycie pamięci. |
W kliencie platformy .NET te opcje można modyfikować za pomocą delegata opcji dostarczonych do WithUrl
programu :
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.SkipNegotiation = true;
options.Transports = HttpTransportType.WebSockets;
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
W kliencie Języka JavaScript te opcje można podać w obiekcie JavaScript udostępnionym użytkownikowi withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
// "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
headers: { "Foo": "Bar" },
transport: signalR.HttpTransportType.LongPolling
})
.build();
W kliencie Języka Java te opcje można skonfigurować przy użyciu metod zwróconych HttpHubConnectionBuilder
z obiektu HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Dodatkowe zasoby
- Wprowadzenie do platformy ASP.NET Core SignalR
- Używanie koncentratorów w technologii ASP.NET Core SignalR
- ASP.NET Core SignalR JavaScript client
- klient platformy .NET platformy ASP.NET Core SignalR
- Używanie protokołu MessagePack Hub w programie SignalR dla platformy ASP.NET Core
- platformy obsługiwane przez platformy ASP.NET Core SignalR
JSOpcje serializacji ON/MessagePack
ASP.NET Core SignalR obsługuje dwa protokoły kodowania komunikatów: JSON i MessagePack. Każdy protokół ma opcje konfiguracji serializacji.
JSNa serwerze można skonfigurować serializacji przy użyciu AddJsonProtocol metody rozszerzenia, którą można dodać po AddSignalR w metodzie Startup.ConfigureServices
. Metoda AddJsonProtocol
przyjmuje delegata, który odbiera options
obiekt. Właściwość PayloadSerializerSettings tego obiektu jest obiektem Json.NET JsonSerializerSettings
, który może służyć do konfigurowania serializacji argumentów i zwracanych wartości. Aby uzyskać więcej informacji, zobacz dokumentację Json.NET.
Na przykład aby skonfigurować serializator do używania nazw właściwości "PascalCase", a nie domyślnych nazw przypadków camel, użyj następującego kodu w pliku Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
});
W kliencie platformy .NET w systemie istnieje ta sama AddJsonProtocol
metoda rozszerzenia.HubConnectionBuilder Aby Microsoft.Extensions.DependencyInjection
rozpoznać metodę rozszerzenia, należy zaimportować przestrzeń nazw:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
})
.Build();
Uwaga
Obecnie nie można skonfigurować JSserializacji ON w kliencie JavaScript.
Opcje serializacji messagePack
Serializacji MessagePack można skonfigurować, podając delegata do wywołania AddMessagePackProtocol . Aby uzyskać więcej informacji, zobacz MessagePack w pliku SignalR .
Uwaga
Obecnie nie można skonfigurować serializacji MessagePack w kliencie JavaScript.
Konfigurowanie opcji serwera
W poniższej tabeli opisano opcje konfigurowania SignalR koncentratorów:
Opcja | Wartość domyślna | opis |
---|---|---|
HandshakeTimeout |
15 sekund | Jeśli klient nie wysyła początkowego komunikatu uzgadniania w tym przedziale czasu, połączenie zostanie zamknięte. Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Jeśli serwer nie wysłał komunikatu w tym interwale, wiadomość ping zostanie wysłana automatycznie, aby zachować otwarte połączenie. Podczas zmiany KeepAliveInterval zmień ServerTimeout ustawienie lub serverTimeoutInMilliseconds na kliencie. Zalecana ServerTimeout wartość lub serverTimeoutInMilliseconds jest dwukrotnie ceniona KeepAliveInterval . |
SupportedProtocols |
Wszystkie zainstalowane protokoły | Protokoły obsługiwane przez to centrum. Domyślnie wszystkie protokoły zarejestrowane na serwerze są dozwolone. Protokoły można usunąć z tej listy, aby wyłączyć określone protokoły dla poszczególnych centrów. |
EnableDetailedErrors |
false |
Jeśli true , szczegółowe komunikaty wyjątków są zwracane do klientów, gdy wyjątek jest zgłaszany w metodzie Centrum. Wartością domyślną jest to false , że te komunikaty wyjątków mogą zawierać poufne informacje. |
Opcje można skonfigurować dla wszystkich centrów, udostępniając delegat opcji do wywołania AddSignalR
w programie Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Opcje pojedynczego koncentratora zastępują opcje globalne dostępne w programie AddSignalR
i można je skonfigurować przy użyciu polecenia AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Zaawansowane opcje konfiguracji PROTOKOŁU HTTP
Służy HttpConnectionDispatcherOptions
do konfigurowania ustawień zaawansowanych związanych z transportami i zarządzaniem buforem pamięci. Te opcje są konfigurowane przez przekazanie delegata do MapHub elementu w programie Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSignalR((configure) =>
{
var desiredTransports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
configure.MapHub<ChatHub>("/chathub", (options) =>
{
options.Transports = desiredTransports;
});
});
}
W poniższej tabeli opisano opcje konfigurowania zaawansowanych opcji http platformy ASP.NET Core SignalR:
Opcja | Wartość domyślna | opis |
---|---|---|
ApplicationMaxBufferSize |
32 KB | Maksymalna liczba bajtów odebranych od klienta buforowania serwera. Zwiększenie tej wartości umożliwia serwerowi odbieranie większych komunikatów, ale może negatywnie wpłynąć na zużycie pamięci. |
AuthorizationData |
Dane automatycznie zbierane z atrybutów zastosowanych Authorize do klasy Hub. |
Lista obiektów używanych IAuthorizeData do określenia, czy klient jest autoryzowany do łączenia się z koncentratorem. |
TransportMaxBufferSize |
32 KB | Maksymalna liczba bajtów wysyłanych przez aplikację buforowana przez serwer. Zwiększenie tej wartości umożliwia serwerowi wysyłanie większych komunikatów, ale może negatywnie wpłynąć na zużycie pamięci. |
Transports |
Wszystkie transporty są włączone. | Bit flaguje wyliczenie HttpTransportType wartości, które mogą ograniczyć transporty, których klient może użyć do nawiązania połączenia. |
LongPolling |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu długiego sondowania. |
WebSockets |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu obiektów WebSocket. |
Transport Long Polling ma dodatkowe opcje, które można skonfigurować przy użyciu LongPolling
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
PollTimeout |
90 sekund | Maksymalny czas oczekiwania serwera na wysłanie komunikatu do klienta przed zakończeniem pojedynczego żądania sondowania. Zmniejszenie tej wartości powoduje, że klient częściej wysyła nowe żądania sondowania. |
Transport protokołu WebSocket ma dodatkowe opcje, które można skonfigurować przy użyciu WebSockets
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
CloseTimeout |
5 s | Po zamknięciu serwera, jeśli klient nie może zamknąć w tym przedziale czasu, połączenie zostanie zakończone. |
SubProtocolSelector |
null |
Delegat, który może służyć do ustawiania nagłówka Sec-WebSocket-Protocol na wartość niestandardową. Delegat odbiera wartości żądane przez klienta jako dane wejściowe i oczekuje się, że zwróci żądaną wartość. |
Konfigurowanie opcji klienta
Opcje klienta można skonfigurować na typie HubConnectionBuilder
(dostępnym na klientach .NET i JavaScript). Jest ona również dostępna w kliencie Java, ale podklasa HttpHubConnectionBuilder
zawiera opcje konfiguracji konstruktora, a także na HubConnection
samym kliencie.
Konfigurowanie rejestrowania
Rejestrowanie jest konfigurowane w kliencie .NET przy użyciu ConfigureLogging
metody . Dostawcy rejestrowania i filtry można zarejestrować w taki sam sposób, jak na serwerze. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rejestrowania w usłudze ASP.NET Core .
Uwaga
Aby zarejestrować dostawców rejestrowania, należy zainstalować niezbędne pakiety. Aby uzyskać pełną listę, zobacz sekcję Wbudowane dostawcy rejestrowania w dokumentacji.
Aby na przykład włączyć rejestrowanie konsoli, zainstaluj Microsoft.Extensions.Logging.Console
pakiet NuGet. Wywołaj metodę AddConsole
rozszerzenia:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
W kliencie JavaScript istnieje podobna configureLogging
metoda. Podaj wartość wskazującą LogLevel
minimalny poziom komunikatów dziennika do utworzenia. Dzienniki są zapisywane w oknie konsoli przeglądarki.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
Uwaga
Aby całkowicie wyłączyć rejestrowanie, określ signalR.LogLevel.None
metodę configureLogging
.
Aby uzyskać więcej informacji na temat rejestrowania, zobacz dokumentację SignalRdiagnostyki.
Klient SignalR Java używa biblioteki SLF4J do rejestrowania. Jest to interfejs API rejestrowania wysokiego poziomu, który umożliwia użytkownikom biblioteki wybranie własnej implementacji rejestrowania przez wprowadzenie określonej zależności rejestrowania. Poniższy fragment kodu pokazuje, jak używać go java.util.logging
z klientem SignalR Java.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Jeśli nie skonfigurujesz rejestrowania w zależnościach, SLF4J ładuje domyślny rejestrator bez operacji z następującym komunikatem ostrzegawczym:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Można to bezpiecznie zignorować.
Konfigurowanie dozwolonych transportów
Transporty używane przez SignalR program można skonfigurować w wywołaniu WithUrl
(withUrl
w języku JavaScript). Bitowe or wartości parametru HttpTransportType
można użyć do ograniczenia klienta do używania tylko określonych transportów. Wszystkie transporty są domyślnie włączone.
Na przykład aby wyłączyć transport zdarzeń wysłanych przez serwer, ale zezwalać na połączenia WebSocket i Long Polling:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
W kliencie języka JavaScript transporty są konfigurowane przez ustawienie transport
pola w obiekcie options udostępnionym na wartość withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
Konfigurowanie uwierzytelniania elementu nośnego
Aby udostępnić dane uwierzytelniania wraz z żądaniami SignalR , użyj AccessTokenProvider
opcji (accessTokenFactory
w języku JavaScript), aby określić funkcję zwracającą żądany token dostępu. W kliencie platformy .NET ten token dostępu jest przekazywany jako token HTTP "Uwierzytelnianie elementu nośnego" (przy użyciu Authorization
nagłówka o typie Bearer
). W kliencie JavaScript token dostępu jest używany jako token elementu nośnego, z wyjątkiem kilku przypadków, w których interfejsy API przeglądarki ograniczają możliwość stosowania nagłówków (w szczególności w żądaniach zdarzeń wysłanych przez serwer i obiektów WebSocket). W takich przypadkach token dostępu jest udostępniany jako wartość access_token
ciągu zapytania .
W kliencie AccessTokenProvider
platformy .NET można określić opcję przy użyciu delegata opcji w programie WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
W kliencie JavaScript token dostępu jest konfigurowany przez ustawienie accessTokenFactory
pola w obiekcie options w withUrl
pliku :
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
W kliencie SignalR języka Java można skonfigurować token elementu nośnego do użycia do uwierzytelniania, zapewniając fabrykę tokenów dostępu do programu HttpHubConnectionBuilder. Użyj funkcji withAccessTokenFactory, aby udostępnić pojedynczy <ciąg> RxJava. Wywołanie metody Single.defer umożliwia napisanie logiki w celu utworzenia tokenów dostępu dla klienta.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Konfigurowanie limitu czasu i opcji zachowania aktywności
Dodatkowe opcje konfigurowania limitu czasu i zachowania utrzymania aktywności są dostępne w HubConnection
samym obiekcie:
Opcja | Wartość domyślna | opis |
---|---|---|
ServerTimeout |
30 sekund (30 000 milisekund) | Limit czasu działania serwera. Jeśli serwer nie wysłał komunikatu w tym interwale, klient uzna serwer za odłączony i wyzwoli Closed zdarzenie (onclose w języku JavaScript). Ta wartość musi być wystarczająco duża, aby wiadomość ping została wysłana z serwera i odebrana przez klienta w przedziale czasu. Zalecana wartość jest liczbą co najmniej dwukrotnie większą niż wartość serwera KeepAliveInterval , aby umożliwić odebranie poleceń ping. |
HandshakeTimeout |
15 sekund | Limit czasu początkowego uzgadniania serwera. Jeśli serwer nie wysyła odpowiedzi uzgadniania w tym interwale, klient anuluje uzgadnianie i wyzwala Closed zdarzenie (onclose w języku JavaScript). Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
W kliencie .NET wartości limitu czasu są określane jako TimeSpan
wartości.
Konfigurowanie dodatkowych opcji
Dodatkowe opcje można skonfigurować w metodzie WithUrl
(withUrl
w języku JavaScript) w systemie HubConnectionBuilder
lub w różnych interfejsach API konfiguracji w kliencie HttpHubConnectionBuilder
Java:
Opcja platformy .NET | Wartość domyślna | opis |
---|---|---|
AccessTokenProvider |
null |
Funkcja zwracająca ciąg, który jest dostarczany jako token uwierzytelniania elementu nośnego w żądaniach HTTP. |
SkipNegotiation |
false |
Ustaw tę opcję, aby true pominąć krok negocjacji. Obsługiwane tylko wtedy, gdy transport obiektów WebSockets jest jedynym włączonym transportem. Nie można włączyć tego ustawienia w przypadku korzystania z usługi platformy Azure SignalR . |
ClientCertificates |
Pusty | Kolekcja certyfikatów TLS do wysyłania do uwierzytelniania żądań. |
Cookies |
Pusty | Kolekcja żądań HTTP cookiedo wysłania przy użyciu każdego żądania HTTP. |
Credentials |
Pusty | Poświadczenia do wysłania przy użyciu każdego żądania HTTP. |
CloseTimeout |
5 s | Tylko obiekty WebSocket. Maksymalny czas oczekiwania klienta po zamknięciu serwera w celu potwierdzenia zamknięcia żądania zamknięcia. Jeśli serwer nie potwierdzi zamknięcia w tym czasie, klient rozłącza się. |
Headers |
Pusty | Mapa dodatkowych nagłówków HTTP do wysłania przy użyciu każdego żądania HTTP. |
HttpMessageHandlerFactory |
null |
Pełnomocnik, który może służyć do konfigurowania lub zastępowania używanego HttpMessageHandler do wysyłania żądań HTTP. Nie jest używany w przypadku połączeń protokołu WebSocket. Ten delegat musi zwrócić wartość inną niż null i otrzymuje wartość domyślną jako parametr. Zmodyfikuj ustawienia dla tej wartości domyślnej i zwróć je lub zwróć nowe HttpMessageHandler wystąpienie. Podczas zastępowania programu obsługi pamiętaj, aby skopiować ustawienia, które chcesz zachować z dostarczonej procedury obsługi, w przeciwnym razie skonfigurowane opcje (takie jak Cookies i Nagłówki) nie będą stosowane do nowej procedury obsługi. |
Proxy |
null |
Serwer proxy HTTP do użycia podczas wysyłania żądań HTTP. |
UseDefaultCredentials |
false |
Ustaw tę wartość logiczną, aby wysyłać domyślne poświadczenia dla żądań HTTP i WebSocket. Umożliwia to korzystanie z uwierzytelniania systemu Windows. |
WebSocketConfiguration |
null |
Delegat, który może służyć do konfigurowania dodatkowych opcji protokołu WebSocket. Odbiera wystąpienie ClientWebSocketOptions , którego można użyć do skonfigurowania opcji. |
W kliencie platformy .NET te opcje można modyfikować za pomocą delegata opcji dostarczonych do WithUrl
programu :
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
W kliencie Języka JavaScript te opcje można podać w obiekcie JavaScript udostępnionym użytkownikowi withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
W kliencie Języka Java te opcje można skonfigurować przy użyciu metod zwróconych HttpHubConnectionBuilder
z obiektu HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Dodatkowe zasoby
- Wprowadzenie do platformy ASP.NET Core SignalR
- Używanie koncentratorów w technologii ASP.NET Core SignalR
- ASP.NET Core SignalR JavaScript client
- klient platformy .NET platformy ASP.NET Core SignalR
- Używanie protokołu MessagePack Hub w programie SignalR dla platformy ASP.NET Core
- platformy obsługiwane przez platformy ASP.NET Core SignalR
JSOpcje serializacji ON/MessagePack
ASP.NET Core SignalR obsługuje dwa protokoły kodowania komunikatów: JSON i MessagePack. Każdy protokół ma opcje konfiguracji serializacji.
JSNa serwerze można skonfigurować serializacji przy użyciu AddJsonProtocol metody rozszerzenia, którą można dodać po AddSignalR w metodzie Startup.ConfigureServices
. Metoda AddJsonProtocol
przyjmuje delegata, który odbiera options
obiekt. Właściwość PayloadSerializerSettings tego obiektu jest obiektem Json.NET JsonSerializerSettings
, który może służyć do konfigurowania serializacji argumentów i zwracanych wartości. Aby uzyskać więcej informacji, zobacz dokumentację Json.NET.
Na przykład aby skonfigurować serializator do używania nazw właściwości "PascalCase", a nie domyślnych nazw przypadków camel, użyj następującego kodu w pliku Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
});
W kliencie platformy .NET w systemie istnieje ta sama AddJsonProtocol
metoda rozszerzenia.HubConnectionBuilder Aby Microsoft.Extensions.DependencyInjection
rozpoznać metodę rozszerzenia, należy zaimportować przestrzeń nazw:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
})
.Build();
Uwaga
Obecnie nie można skonfigurować JSserializacji ON w kliencie JavaScript.
Opcje serializacji messagePack
Serializacji MessagePack można skonfigurować, podając delegata do wywołania AddMessagePackProtocol . Aby uzyskać więcej informacji, zobacz MessagePack w pliku SignalR .
Uwaga
Obecnie nie można skonfigurować serializacji MessagePack w kliencie JavaScript.
Konfigurowanie opcji serwera
W poniższej tabeli opisano opcje konfigurowania SignalR koncentratorów:
Opcja | Wartość domyślna | opis |
---|---|---|
ClientTimeoutInterval |
30 sekund | Serwer rozważa rozłączenie klienta, jeśli nie odebrał komunikatu (w tym zachowania aktywności) w tym interwale. Może upłynąć dłużej niż ten interwał limitu czasu, aby klient został oznaczony jako odłączony ze względu na sposób implementacji. Zalecana wartość jest dwukrotnie ceniona KeepAliveInterval . |
HandshakeTimeout |
15 sekund | Jeśli klient nie wysyła początkowego komunikatu uzgadniania w tym przedziale czasu, połączenie zostanie zamknięte. Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Jeśli serwer nie wysłał komunikatu w tym interwale, wiadomość ping zostanie wysłana automatycznie, aby zachować otwarte połączenie. Podczas zmiany KeepAliveInterval zmień ServerTimeout ustawienie lub serverTimeoutInMilliseconds na kliencie. Zalecana ServerTimeout wartość lub serverTimeoutInMilliseconds jest dwukrotnie ceniona KeepAliveInterval . |
SupportedProtocols |
Wszystkie zainstalowane protokoły | Protokoły obsługiwane przez to centrum. Domyślnie wszystkie protokoły zarejestrowane na serwerze są dozwolone. Protokoły można usunąć z tej listy, aby wyłączyć określone protokoły dla poszczególnych centrów. |
EnableDetailedErrors |
false |
Jeśli true , szczegółowe komunikaty wyjątków są zwracane do klientów, gdy wyjątek jest zgłaszany w metodzie Centrum. Wartością domyślną jest to false , że te komunikaty wyjątków mogą zawierać poufne informacje. |
Opcje można skonfigurować dla wszystkich centrów, udostępniając delegat opcji do wywołania AddSignalR
w programie Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Opcje pojedynczego koncentratora zastępują opcje globalne dostępne w programie AddSignalR
i można je skonfigurować przy użyciu polecenia AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Zaawansowane opcje konfiguracji PROTOKOŁU HTTP
Służy HttpConnectionDispatcherOptions
do konfigurowania ustawień zaawansowanych związanych z transportami i zarządzaniem buforem pamięci. Te opcje są konfigurowane przez przekazanie delegata do MapHub elementu w programie Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSignalR((configure) =>
{
var desiredTransports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
configure.MapHub<ChatHub>("/chathub", (options) =>
{
options.Transports = desiredTransports;
});
});
}
W poniższej tabeli opisano opcje konfigurowania zaawansowanych opcji http platformy ASP.NET Core SignalR:
Opcja | Wartość domyślna | opis |
---|---|---|
ApplicationMaxBufferSize |
32 KB | Maksymalna liczba bajtów odebranych od klienta buforowania serwera. Zwiększenie tej wartości umożliwia serwerowi odbieranie większych komunikatów, ale może negatywnie wpłynąć na zużycie pamięci. |
AuthorizationData |
Dane automatycznie zbierane z atrybutów zastosowanych Authorize do klasy Hub. |
Lista obiektów używanych IAuthorizeData do określenia, czy klient jest autoryzowany do łączenia się z koncentratorem. |
TransportMaxBufferSize |
32 KB | Maksymalna liczba bajtów wysyłanych przez aplikację buforowana przez serwer. Zwiększenie tej wartości umożliwia serwerowi wysyłanie większych komunikatów, ale może negatywnie wpłynąć na zużycie pamięci. |
Transports |
Wszystkie transporty są włączone. | Bit flaguje wyliczenie HttpTransportType wartości, które mogą ograniczyć transporty, których klient może użyć do nawiązania połączenia. |
LongPolling |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu długiego sondowania. |
WebSockets |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu obiektów WebSocket. |
Transport Long Polling ma dodatkowe opcje, które można skonfigurować przy użyciu LongPolling
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
PollTimeout |
90 sekund | Maksymalny czas oczekiwania serwera na wysłanie komunikatu do klienta przed zakończeniem pojedynczego żądania sondowania. Zmniejszenie tej wartości powoduje, że klient częściej wysyła nowe żądania sondowania. |
Transport protokołu WebSocket ma dodatkowe opcje, które można skonfigurować przy użyciu WebSockets
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
CloseTimeout |
5 s | Po zamknięciu serwera, jeśli klient nie może zamknąć w tym przedziale czasu, połączenie zostanie zakończone. |
SubProtocolSelector |
null |
Delegat, który może służyć do ustawiania nagłówka Sec-WebSocket-Protocol na wartość niestandardową. Delegat odbiera wartości żądane przez klienta jako dane wejściowe i oczekuje się, że zwróci żądaną wartość. |
Konfigurowanie opcji klienta
Opcje klienta można skonfigurować na typie HubConnectionBuilder
(dostępnym na klientach .NET i JavaScript). Jest ona również dostępna w kliencie Java, ale podklasa HttpHubConnectionBuilder
zawiera opcje konfiguracji konstruktora, a także na HubConnection
samym kliencie.
Konfigurowanie rejestrowania
Rejestrowanie jest konfigurowane w kliencie .NET przy użyciu ConfigureLogging
metody . Dostawcy rejestrowania i filtry można zarejestrować w taki sam sposób, jak na serwerze. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rejestrowania w usłudze ASP.NET Core .
Uwaga
Aby zarejestrować dostawców rejestrowania, należy zainstalować niezbędne pakiety. Aby uzyskać pełną listę, zobacz sekcję Wbudowane dostawcy rejestrowania w dokumentacji.
Aby na przykład włączyć rejestrowanie konsoli, zainstaluj Microsoft.Extensions.Logging.Console
pakiet NuGet. Wywołaj metodę AddConsole
rozszerzenia:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
W kliencie JavaScript istnieje podobna configureLogging
metoda. Podaj wartość wskazującą LogLevel
minimalny poziom komunikatów dziennika do utworzenia. Dzienniki są zapisywane w oknie konsoli przeglądarki.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
Uwaga
Aby całkowicie wyłączyć rejestrowanie, określ signalR.LogLevel.None
metodę configureLogging
.
Aby uzyskać więcej informacji na temat rejestrowania, zobacz dokumentację SignalRdiagnostyki.
Klient SignalR Java używa biblioteki SLF4J do rejestrowania. Jest to interfejs API rejestrowania wysokiego poziomu, który umożliwia użytkownikom biblioteki wybranie własnej implementacji rejestrowania przez wprowadzenie określonej zależności rejestrowania. Poniższy fragment kodu pokazuje, jak używać go java.util.logging
z klientem SignalR Java.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Jeśli nie skonfigurujesz rejestrowania w zależnościach, SLF4J ładuje domyślny rejestrator bez operacji z następującym komunikatem ostrzegawczym:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Można to bezpiecznie zignorować.
Konfigurowanie dozwolonych transportów
Transporty używane przez SignalR program można skonfigurować w wywołaniu WithUrl
(withUrl
w języku JavaScript). Bitowe or wartości parametru HttpTransportType
można użyć do ograniczenia klienta do używania tylko określonych transportów. Wszystkie transporty są domyślnie włączone.
Na przykład aby wyłączyć transport zdarzeń wysłanych przez serwer, ale zezwalać na połączenia WebSocket i Long Polling:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
W kliencie języka JavaScript transporty są konfigurowane przez ustawienie transport
pola w obiekcie options udostępnionym na wartość withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
W tej wersji obiektów websocket klienta Java jest jedynym dostępnym transportem.
Konfigurowanie uwierzytelniania elementu nośnego
Aby udostępnić dane uwierzytelniania wraz z żądaniami SignalR , użyj AccessTokenProvider
opcji (accessTokenFactory
w języku JavaScript), aby określić funkcję zwracającą żądany token dostępu. W kliencie platformy .NET ten token dostępu jest przekazywany jako token HTTP "Uwierzytelnianie elementu nośnego" (przy użyciu Authorization
nagłówka o typie Bearer
). W kliencie JavaScript token dostępu jest używany jako token elementu nośnego, z wyjątkiem kilku przypadków, w których interfejsy API przeglądarki ograniczają możliwość stosowania nagłówków (w szczególności w żądaniach zdarzeń wysłanych przez serwer i obiektów WebSocket). W takich przypadkach token dostępu jest udostępniany jako wartość access_token
ciągu zapytania .
W kliencie AccessTokenProvider
platformy .NET można określić opcję przy użyciu delegata opcji w programie WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
W kliencie JavaScript token dostępu jest konfigurowany przez ustawienie accessTokenFactory
pola w obiekcie options w withUrl
pliku :
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
W kliencie SignalR języka Java można skonfigurować token elementu nośnego do użycia do uwierzytelniania, zapewniając fabrykę tokenów dostępu do programu HttpHubConnectionBuilder. Użyj funkcji withAccessTokenFactory, aby udostępnić pojedynczy <ciąg> RxJava. Wywołanie metody Single.defer umożliwia napisanie logiki w celu utworzenia tokenów dostępu dla klienta.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Konfigurowanie limitu czasu i opcji zachowania aktywności
Dodatkowe opcje konfigurowania limitu czasu i zachowania utrzymania aktywności są dostępne w HubConnection
samym obiekcie:
Opcja | Wartość domyślna | opis |
---|---|---|
ServerTimeout |
30 sekund (30 000 milisekund) | Limit czasu działania serwera. Jeśli serwer nie wysłał komunikatu w tym interwale, klient uzna serwer za odłączony i wyzwoli Closed zdarzenie (onclose w języku JavaScript). Ta wartość musi być wystarczająco duża, aby wiadomość ping została wysłana z serwera i odebrana przez klienta w przedziale czasu. Zalecana wartość jest liczbą co najmniej dwukrotnie większą niż wartość serwera KeepAliveInterval , aby umożliwić odebranie poleceń ping. |
HandshakeTimeout |
15 sekund | Limit czasu początkowego uzgadniania serwera. Jeśli serwer nie wysyła odpowiedzi uzgadniania w tym interwale, klient anuluje uzgadnianie i wyzwala Closed zdarzenie (onclose w języku JavaScript). Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Określa interwał wysyłania komunikatów ping przez klienta. Wysłanie dowolnego komunikatu z klienta spowoduje zresetowanie czasomierza do początku interwału. Jeśli klient nie wysłał komunikatu w ClientTimeoutInterval zestawie na serwerze, serwer uzna klienta za odłączonego. |
W kliencie .NET wartości limitu czasu są określane jako TimeSpan
wartości.
Konfigurowanie dodatkowych opcji
Dodatkowe opcje można skonfigurować w metodzie WithUrl
(withUrl
w języku JavaScript) w systemie HubConnectionBuilder
lub w różnych interfejsach API konfiguracji w kliencie HttpHubConnectionBuilder
Java:
Opcja platformy .NET | Wartość domyślna | opis |
---|---|---|
AccessTokenProvider |
null |
Funkcja zwracająca ciąg, który jest dostarczany jako token uwierzytelniania elementu nośnego w żądaniach HTTP. |
SkipNegotiation |
false |
Ustaw tę opcję, aby true pominąć krok negocjacji. Obsługiwane tylko wtedy, gdy transport obiektów WebSockets jest jedynym włączonym transportem. Nie można włączyć tego ustawienia w przypadku korzystania z usługi platformy Azure SignalR . |
ClientCertificates |
Pusty | Kolekcja certyfikatów TLS do wysyłania do uwierzytelniania żądań. |
Cookies |
Pusty | Kolekcja żądań HTTP cookiedo wysłania przy użyciu każdego żądania HTTP. |
Credentials |
Pusty | Poświadczenia do wysłania przy użyciu każdego żądania HTTP. |
CloseTimeout |
5 s | Tylko obiekty WebSocket. Maksymalny czas oczekiwania klienta po zamknięciu serwera w celu potwierdzenia zamknięcia żądania zamknięcia. Jeśli serwer nie potwierdzi zamknięcia w tym czasie, klient rozłącza się. |
Headers |
Pusty | Mapa dodatkowych nagłówków HTTP do wysłania przy użyciu każdego żądania HTTP. |
HttpMessageHandlerFactory |
null |
Pełnomocnik, który może służyć do konfigurowania lub zastępowania używanego HttpMessageHandler do wysyłania żądań HTTP. Nie jest używany w przypadku połączeń protokołu WebSocket. Ten delegat musi zwrócić wartość inną niż null i otrzymuje wartość domyślną jako parametr. Zmodyfikuj ustawienia dla tej wartości domyślnej i zwróć je lub zwróć nowe HttpMessageHandler wystąpienie. Podczas zastępowania programu obsługi pamiętaj, aby skopiować ustawienia, które chcesz zachować z dostarczonej procedury obsługi, w przeciwnym razie skonfigurowane opcje (takie jak Cookies i Nagłówki) nie będą stosowane do nowej procedury obsługi. |
Proxy |
null |
Serwer proxy HTTP do użycia podczas wysyłania żądań HTTP. |
UseDefaultCredentials |
false |
Ustaw tę wartość logiczną, aby wysyłać domyślne poświadczenia dla żądań HTTP i WebSocket. Umożliwia to korzystanie z uwierzytelniania systemu Windows. |
WebSocketConfiguration |
null |
Delegat, który może służyć do konfigurowania dodatkowych opcji protokołu WebSocket. Odbiera wystąpienie ClientWebSocketOptions , którego można użyć do skonfigurowania opcji. |
W kliencie platformy .NET te opcje można modyfikować za pomocą delegata opcji dostarczonych do WithUrl
programu :
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
W kliencie Języka JavaScript te opcje można podać w obiekcie JavaScript udostępnionym użytkownikowi withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
W kliencie Języka Java te opcje można skonfigurować przy użyciu metod zwróconych HttpHubConnectionBuilder
z obiektu HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Dodatkowe zasoby
- Wprowadzenie do platformy ASP.NET Core SignalR
- Używanie koncentratorów w technologii ASP.NET Core SignalR
- ASP.NET Core SignalR JavaScript client
- klient platformy .NET platformy ASP.NET Core SignalR
- Używanie protokołu MessagePack Hub w programie SignalR dla platformy ASP.NET Core
- platformy obsługiwane przez platformy ASP.NET Core SignalR
JSOpcje serializacji ON/MessagePack
ASP.NET Core SignalR obsługuje dwa protokoły kodowania komunikatów: JSON i MessagePack. Każdy protokół ma opcje konfiguracji serializacji.
JSW przypadku serializacji można skonfigurować na serwerze przy użyciu AddJsonProtocol metody rozszerzenia. AddJsonProtocol
można dodać po AddSignalR w pliku Startup.ConfigureServices
. Metoda AddJsonProtocol
przyjmuje delegata, który odbiera options
obiekt. Właściwość PayloadSerializerOptions tego obiektu jest obiektem System.Text.Json
JsonSerializerOptions , który może służyć do konfigurowania serializacji argumentów i zwracanych wartości. Aby uzyskać więcej informacji, zobacz dokumentację System.Text.Json.
Aby na przykład skonfigurować serializator tak, aby nie zmieniał wielkości liter nazw właściwości, a nie domyślne nazwy przypadków camel, użyj następującego kodu w pliku Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
W kliencie platformy .NET w systemie istnieje ta sama AddJsonProtocol
metoda rozszerzenia.HubConnectionBuilder Aby Microsoft.Extensions.DependencyInjection
rozpoznać metodę rozszerzenia, należy zaimportować przestrzeń nazw:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Uwaga
Obecnie nie można skonfigurować JSserializacji ON w kliencie JavaScript.
Przełączanie do pliku Newtonsoft.Json
Jeśli potrzebujesz funkcji Newtonsoft.Json
, które nie są obsługiwane w programie System.Text.Json
, zobacz Przełączanie na Newtonsoft.Json
.
Opcje serializacji messagePack
Serializacji MessagePack można skonfigurować, podając delegata do wywołania AddMessagePackProtocol . Aby uzyskać więcej informacji, zobacz MessagePack w pliku SignalR .
Uwaga
Obecnie nie można skonfigurować serializacji MessagePack w kliencie JavaScript.
Konfigurowanie opcji serwera
W poniższej tabeli opisano opcje konfigurowania SignalR koncentratorów:
Opcja | Wartość domyślna | opis |
---|---|---|
ClientTimeoutInterval |
30 sekund | Serwer rozważa rozłączenie klienta, jeśli nie odebrał komunikatu (w tym zachowania aktywności) w tym interwale. Może upłynąć dłużej niż ten interwał limitu czasu, aby klient został oznaczony jako odłączony ze względu na sposób implementacji. Zalecana wartość jest dwukrotnie ceniona KeepAliveInterval . |
HandshakeTimeout |
15 sekund | Jeśli klient nie wysyła początkowego komunikatu uzgadniania w tym przedziale czasu, połączenie zostanie zamknięte. Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Jeśli serwer nie wysłał komunikatu w tym interwale, wiadomość ping zostanie wysłana automatycznie, aby zachować otwarte połączenie. Podczas zmiany KeepAliveInterval zmień ServerTimeout ustawienie lub serverTimeoutInMilliseconds na kliencie. Zalecana ServerTimeout wartość lub serverTimeoutInMilliseconds jest dwukrotnie ceniona KeepAliveInterval . |
SupportedProtocols |
Wszystkie zainstalowane protokoły | Protokoły obsługiwane przez to centrum. Domyślnie wszystkie protokoły zarejestrowane na serwerze są dozwolone. Protokoły można usunąć z tej listy, aby wyłączyć określone protokoły dla poszczególnych centrów. |
EnableDetailedErrors |
false |
Jeśli true , szczegółowe komunikaty wyjątków są zwracane do klientów, gdy wyjątek jest zgłaszany w metodzie Centrum. Wartością domyślną jest to false , że te komunikaty wyjątków mogą zawierać poufne informacje. |
StreamBufferCapacity |
10 |
Maksymalna liczba elementów, które mogą być buforowane dla strumieni przekazywania klienta. Jeśli ten limit zostanie osiągnięty, przetwarzanie wywołań zostanie zablokowane, dopóki serwer nie przetworzy elementów strumienia. |
MaximumReceiveMessageSize |
32 KB | Maksymalny rozmiar pojedynczego przychodzącego komunikatu centrum. Zwiększenie wartości może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS). |
Opcje można skonfigurować dla wszystkich centrów, udostępniając delegat opcji do wywołania AddSignalR
w programie Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Opcje pojedynczego koncentratora zastępują opcje globalne dostępne w programie AddSignalR
i można je skonfigurować przy użyciu polecenia AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Zaawansowane opcje konfiguracji PROTOKOŁU HTTP
Służy HttpConnectionDispatcherOptions
do konfigurowania ustawień zaawansowanych związanych z transportami i zarządzaniem buforem pamięci. Te opcje są konfigurowane przez przekazanie delegata do MapHub elementu w programie Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
});
});
}
W poniższej tabeli opisano opcje konfigurowania zaawansowanych opcji http platformy ASP.NET Core SignalR:
Opcja | Wartość domyślna | opis |
---|---|---|
ApplicationMaxBufferSize |
32 KB | Maksymalna liczba bajtów odebranych od klienta, który buforuje serwer przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
AuthorizationData |
Dane automatycznie zbierane z atrybutów zastosowanych Authorize do klasy Hub. |
Lista obiektów używanych IAuthorizeData do określenia, czy klient jest autoryzowany do łączenia się z koncentratorem. |
TransportMaxBufferSize |
32 KB | Maksymalna liczba bajtów wysyłanych przez aplikację buforowanych przez serwer przed zaobserwowanym backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze buforowanie większych komunikatów bez oczekiwania na represje wsteczne, ale może zwiększyć zużycie pamięci. |
Transports |
Wszystkie transporty są włączone. | Bit flaguje wyliczenie HttpTransportType wartości, które mogą ograniczyć transporty, których klient może użyć do nawiązania połączenia. |
LongPolling |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu długiego sondowania. |
WebSockets |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu obiektów WebSocket. |
Transport Long Polling ma dodatkowe opcje, które można skonfigurować przy użyciu LongPolling
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
PollTimeout |
90 sekund | Maksymalny czas oczekiwania serwera na wysłanie komunikatu do klienta przed zakończeniem pojedynczego żądania sondowania. Zmniejszenie tej wartości powoduje, że klient częściej wysyła nowe żądania sondowania. |
Transport protokołu WebSocket ma dodatkowe opcje, które można skonfigurować przy użyciu WebSockets
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
CloseTimeout |
5 s | Po zamknięciu serwera, jeśli klient nie może zamknąć w tym przedziale czasu, połączenie zostanie zakończone. |
SubProtocolSelector |
null |
Delegat, który może służyć do ustawiania nagłówka Sec-WebSocket-Protocol na wartość niestandardową. Delegat odbiera wartości żądane przez klienta jako dane wejściowe i oczekuje się, że zwróci żądaną wartość. |
Konfigurowanie opcji klienta
Opcje klienta można skonfigurować na typie HubConnectionBuilder
(dostępnym na klientach .NET i JavaScript). Jest ona również dostępna w kliencie Java, ale podklasa HttpHubConnectionBuilder
zawiera opcje konfiguracji konstruktora, a także na HubConnection
samym kliencie.
Konfigurowanie rejestrowania
Rejestrowanie jest konfigurowane w kliencie .NET przy użyciu ConfigureLogging
metody . Dostawcy rejestrowania i filtry można zarejestrować w taki sam sposób, jak na serwerze. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rejestrowania w usłudze ASP.NET Core .
Uwaga
Aby zarejestrować dostawców rejestrowania, należy zainstalować niezbędne pakiety. Aby uzyskać pełną listę, zobacz sekcję Wbudowane dostawcy rejestrowania w dokumentacji.
Aby na przykład włączyć rejestrowanie konsoli, zainstaluj Microsoft.Extensions.Logging.Console
pakiet NuGet. Wywołaj metodę AddConsole
rozszerzenia:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
W kliencie JavaScript istnieje podobna configureLogging
metoda. Podaj wartość wskazującą LogLevel
minimalny poziom komunikatów dziennika do utworzenia. Dzienniki są zapisywane w oknie konsoli przeglądarki.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
LogLevel
Zamiast wartości można również podać string
wartość reprezentującą nazwę poziomu dziennika. Jest to przydatne podczas konfigurowania SignalR rejestrowania w środowiskach, w których nie masz dostępu do LogLevel
stałych.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
W poniższej tabeli wymieniono dostępne poziomy dziennika. Wartość, którą podajesz, ustawia configureLogging
minimalny poziom dziennika, który zostanie zarejestrowany. Komunikaty zarejestrowane na tym poziomie lub poziomy wymienione po niej w tabeli zostaną zarejestrowane.
String | PoziomRejestrowania |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info lub information |
LogLevel.Information |
warn lub warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Uwaga
Aby całkowicie wyłączyć rejestrowanie, określ signalR.LogLevel.None
metodę configureLogging
.
Aby uzyskać więcej informacji na temat rejestrowania, zobacz dokumentację SignalRdiagnostyki.
Klient SignalR Java używa biblioteki SLF4J do rejestrowania. Jest to interfejs API rejestrowania wysokiego poziomu, który umożliwia użytkownikom biblioteki wybranie własnej implementacji rejestrowania przez wprowadzenie określonej zależności rejestrowania. Poniższy fragment kodu pokazuje, jak używać go java.util.logging
z klientem SignalR Java.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Jeśli nie skonfigurujesz rejestrowania w zależnościach, SLF4J ładuje domyślny rejestrator bez operacji z następującym komunikatem ostrzegawczym:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Można to bezpiecznie zignorować.
Konfigurowanie dozwolonych transportów
Transporty używane przez SignalR program można skonfigurować w wywołaniu WithUrl
(withUrl
w języku JavaScript). Bitowe or wartości parametru HttpTransportType
można użyć do ograniczenia klienta do używania tylko określonych transportów. Wszystkie transporty są domyślnie włączone.
Na przykład aby wyłączyć transport zdarzeń wysłanych przez serwer, ale zezwalać na połączenia WebSocket i Long Polling:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
W kliencie języka JavaScript transporty są konfigurowane przez ustawienie transport
pola w obiekcie options udostępnionym na wartość withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
W tej wersji obiektów websocket klienta Java jest jedynym dostępnym transportem.
W kliencie Java transport jest wybierany przy użyciu withTransport
metody w pliku HttpHubConnectionBuilder
. Klient Języka Java domyślnie używa transportu obiektów WebSocket.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Uwaga
Klient SignalR java nie obsługuje jeszcze powrotu transportu.
Konfigurowanie uwierzytelniania elementu nośnego
Aby udostępnić dane uwierzytelniania wraz z żądaniami SignalR , użyj AccessTokenProvider
opcji (accessTokenFactory
w języku JavaScript), aby określić funkcję zwracającą żądany token dostępu. W kliencie platformy .NET ten token dostępu jest przekazywany jako token HTTP "Uwierzytelnianie elementu nośnego" (przy użyciu Authorization
nagłówka o typie Bearer
). W kliencie JavaScript token dostępu jest używany jako token elementu nośnego, z wyjątkiem kilku przypadków, w których interfejsy API przeglądarki ograniczają możliwość stosowania nagłówków (w szczególności w żądaniach zdarzeń wysłanych przez serwer i obiektów WebSocket). W takich przypadkach token dostępu jest udostępniany jako wartość access_token
ciągu zapytania .
W kliencie AccessTokenProvider
platformy .NET można określić opcję przy użyciu delegata opcji w programie WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
W kliencie JavaScript token dostępu jest konfigurowany przez ustawienie accessTokenFactory
pola w obiekcie options w withUrl
pliku :
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
W kliencie SignalR języka Java można skonfigurować token elementu nośnego do użycia do uwierzytelniania, zapewniając fabrykę tokenów dostępu do programu HttpHubConnectionBuilder. Użyj funkcji withAccessTokenFactory, aby udostępnić pojedynczy <ciąg> RxJava. Wywołanie metody Single.defer umożliwia napisanie logiki w celu utworzenia tokenów dostępu dla klienta.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Konfigurowanie limitu czasu i opcji zachowania aktywności
Dodatkowe opcje konfigurowania limitu czasu i zachowania utrzymania aktywności są dostępne w HubConnection
samym obiekcie:
Opcja | Wartość domyślna | opis |
---|---|---|
ServerTimeout |
30 sekund (30 000 milisekund) | Limit czasu działania serwera. Jeśli serwer nie wysłał komunikatu w tym interwale, klient uzna serwer za odłączony i wyzwoli Closed zdarzenie (onclose w języku JavaScript). Ta wartość musi być wystarczająco duża, aby wiadomość ping została wysłana z serwera i odebrana przez klienta w przedziale czasu. Zalecana wartość jest liczbą co najmniej dwukrotnie większą niż wartość serwera KeepAliveInterval , aby umożliwić odebranie poleceń ping. |
HandshakeTimeout |
15 sekund | Limit czasu początkowego uzgadniania serwera. Jeśli serwer nie wysyła odpowiedzi uzgadniania w tym interwale, klient anuluje uzgadnianie i wyzwala Closed zdarzenie (onclose w języku JavaScript). Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Określa interwał wysyłania komunikatów ping przez klienta. Wysłanie dowolnego komunikatu z klienta spowoduje zresetowanie czasomierza do początku interwału. Jeśli klient nie wysłał komunikatu w ClientTimeoutInterval zestawie na serwerze, serwer uzna klienta za odłączonego. |
W kliencie .NET wartości limitu czasu są określane jako TimeSpan
wartości.
Konfigurowanie dodatkowych opcji
Dodatkowe opcje można skonfigurować w metodzie WithUrl
(withUrl
w języku JavaScript) w systemie HubConnectionBuilder
lub w różnych interfejsach API konfiguracji w kliencie HttpHubConnectionBuilder
Java:
Opcja platformy .NET | Wartość domyślna | opis |
---|---|---|
AccessTokenProvider |
null |
Funkcja zwracająca ciąg, który jest dostarczany jako token uwierzytelniania elementu nośnego w żądaniach HTTP. |
SkipNegotiation |
false |
Ustaw tę opcję, aby true pominąć krok negocjacji. Obsługiwane tylko wtedy, gdy transport obiektów WebSockets jest jedynym włączonym transportem. Nie można włączyć tego ustawienia w przypadku korzystania z usługi platformy Azure SignalR . |
ClientCertificates |
Pusty | Kolekcja certyfikatów TLS do wysyłania do uwierzytelniania żądań. |
Cookies |
Pusty | Kolekcja żądań HTTP cookiedo wysłania przy użyciu każdego żądania HTTP. |
Credentials |
Pusty | Poświadczenia do wysłania przy użyciu każdego żądania HTTP. |
CloseTimeout |
5 s | Tylko obiekty WebSocket. Maksymalny czas oczekiwania klienta po zamknięciu serwera w celu potwierdzenia zamknięcia żądania zamknięcia. Jeśli serwer nie potwierdzi zamknięcia w tym czasie, klient rozłącza się. |
Headers |
Pusty | Mapa dodatkowych nagłówków HTTP do wysłania przy użyciu każdego żądania HTTP. |
HttpMessageHandlerFactory |
null |
Pełnomocnik, który może służyć do konfigurowania lub zastępowania używanego HttpMessageHandler do wysyłania żądań HTTP. Nie jest używany w przypadku połączeń protokołu WebSocket. Ten delegat musi zwrócić wartość inną niż null i otrzymuje wartość domyślną jako parametr. Zmodyfikuj ustawienia dla tej wartości domyślnej i zwróć je lub zwróć nowe HttpMessageHandler wystąpienie. Podczas zastępowania programu obsługi pamiętaj, aby skopiować ustawienia, które chcesz zachować z dostarczonej procedury obsługi, w przeciwnym razie skonfigurowane opcje (takie jak Cookies i Nagłówki) nie będą stosowane do nowej procedury obsługi. |
Proxy |
null |
Serwer proxy HTTP do użycia podczas wysyłania żądań HTTP. |
UseDefaultCredentials |
false |
Ustaw tę wartość logiczną, aby wysyłać domyślne poświadczenia dla żądań HTTP i WebSocket. Umożliwia to korzystanie z uwierzytelniania systemu Windows. |
WebSocketConfiguration |
null |
Delegat, który może służyć do konfigurowania dodatkowych opcji protokołu WebSocket. Odbiera wystąpienie ClientWebSocketOptions , którego można użyć do skonfigurowania opcji. |
W kliencie platformy .NET te opcje można modyfikować za pomocą delegata opcji dostarczonych do WithUrl
programu :
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
W kliencie Języka JavaScript te opcje można podać w obiekcie JavaScript udostępnionym użytkownikowi withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
W kliencie Języka Java te opcje można skonfigurować przy użyciu metod zwróconych HttpHubConnectionBuilder
z obiektu HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Dodatkowe zasoby
- Wprowadzenie do platformy ASP.NET Core SignalR
- Używanie koncentratorów w technologii ASP.NET Core SignalR
- ASP.NET Core SignalR JavaScript client
- klient platformy .NET platformy ASP.NET Core SignalR
- Używanie protokołu MessagePack Hub w programie SignalR dla platformy ASP.NET Core
- platformy obsługiwane przez platformy ASP.NET Core SignalR
JSOpcje serializacji ON/MessagePack
ASP.NET Core SignalR obsługuje dwa protokoły kodowania komunikatów: JSON i MessagePack. Każdy protokół ma opcje konfiguracji serializacji.
JSW przypadku serializacji można skonfigurować na serwerze przy użyciu AddJsonProtocol metody rozszerzenia. AddJsonProtocol
można dodać po AddSignalR w pliku Startup.ConfigureServices
. Metoda AddJsonProtocol
przyjmuje delegata, który odbiera options
obiekt. Właściwość PayloadSerializerOptions tego obiektu jest obiektem System.Text.Json
JsonSerializerOptions , który może służyć do konfigurowania serializacji argumentów i zwracanych wartości. Aby uzyskać więcej informacji, zobacz dokumentację System.Text.Json.
Aby na przykład skonfigurować serializator tak, aby nie zmieniał wielkości liter nazw właściwości, a nie domyślne nazwy przypadków camel, użyj następującego kodu w pliku Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null
});
W kliencie platformy .NET w systemie istnieje ta sama AddJsonProtocol
metoda rozszerzenia.HubConnectionBuilder Aby Microsoft.Extensions.DependencyInjection
rozpoznać metodę rozszerzenia, należy zaimportować przestrzeń nazw:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Uwaga
Obecnie nie można skonfigurować JSserializacji ON w kliencie JavaScript.
Przełączanie do pliku Newtonsoft.Json
Jeśli potrzebujesz funkcji Newtonsoft.Json
, które nie są obsługiwane w programie System.Text.Json
, zobacz Przełączanie na Newtonsoft.Json
.
Opcje serializacji messagePack
Serializacji MessagePack można skonfigurować, podając delegata do wywołania AddMessagePackProtocol . Aby uzyskać więcej informacji, zobacz MessagePack w pliku SignalR .
Uwaga
Obecnie nie można skonfigurować serializacji MessagePack w kliencie JavaScript.
Konfigurowanie opcji serwera
W poniższej tabeli opisano opcje konfigurowania SignalR koncentratorów:
Opcja | Wartość domyślna | opis |
---|---|---|
ClientTimeoutInterval |
30 sekund | Serwer rozważa rozłączenie klienta, jeśli nie odebrał komunikatu (w tym zachowania aktywności) w tym interwale. Może upłynąć dłużej niż ten interwał limitu czasu, aby klient został oznaczony jako odłączony ze względu na sposób implementacji. Zalecana wartość jest dwukrotnie ceniona KeepAliveInterval . |
HandshakeTimeout |
15 sekund | Jeśli klient nie wysyła początkowego komunikatu uzgadniania w tym przedziale czasu, połączenie zostanie zamknięte. Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Jeśli serwer nie wysłał komunikatu w tym interwale, wiadomość ping zostanie wysłana automatycznie, aby zachować otwarte połączenie. Podczas zmiany KeepAliveInterval zmień ServerTimeout ustawienie lub serverTimeoutInMilliseconds na kliencie. Zalecana ServerTimeout wartość lub serverTimeoutInMilliseconds jest dwukrotnie ceniona KeepAliveInterval . |
SupportedProtocols |
Wszystkie zainstalowane protokoły | Protokoły obsługiwane przez to centrum. Domyślnie wszystkie protokoły zarejestrowane na serwerze są dozwolone. Protokoły można usunąć z tej listy, aby wyłączyć określone protokoły dla poszczególnych centrów. |
EnableDetailedErrors |
false |
Jeśli true , szczegółowe komunikaty wyjątków są zwracane do klientów, gdy wyjątek jest zgłaszany w metodzie Centrum. Wartością domyślną jest to false , że te komunikaty wyjątków mogą zawierać poufne informacje. |
StreamBufferCapacity |
10 |
Maksymalna liczba elementów, które mogą być buforowane dla strumieni przekazywania klienta. Jeśli ten limit zostanie osiągnięty, przetwarzanie wywołań zostanie zablokowane, dopóki serwer nie przetworzy elementów strumienia. |
MaximumReceiveMessageSize |
32 KB | Maksymalny rozmiar pojedynczego przychodzącego komunikatu centrum. Zwiększenie wartości może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS). |
Opcje można skonfigurować dla wszystkich centrów, udostępniając delegat opcji do wywołania AddSignalR
w programie Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Opcje pojedynczego koncentratora zastępują opcje globalne dostępne w programie AddSignalR
i można je skonfigurować przy użyciu polecenia AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Zaawansowane opcje konfiguracji PROTOKOŁU HTTP
Służy HttpConnectionDispatcherOptions
do konfigurowania ustawień zaawansowanych związanych z transportami i zarządzaniem buforem pamięci. Te opcje są konfigurowane przez przekazanie delegata do MapHub elementu w programie Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
});
});
}
W poniższej tabeli opisano opcje konfigurowania zaawansowanych opcji http platformy ASP.NET Core SignalR:
Opcja | Wartość domyślna | opis |
---|---|---|
ApplicationMaxBufferSize |
32 KB | Maksymalna liczba bajtów odebranych od klienta, który buforuje serwer przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
AuthorizationData |
Dane automatycznie zbierane z atrybutów zastosowanych Authorize do klasy Hub. |
Lista obiektów używanych IAuthorizeData do określenia, czy klient jest autoryzowany do łączenia się z koncentratorem. |
TransportMaxBufferSize |
32 KB | Maksymalna liczba bajtów wysyłanych przez aplikację buforowanych przez serwer przed zaobserwowanym backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze buforowanie większych komunikatów bez oczekiwania na represje wsteczne, ale może zwiększyć zużycie pamięci. |
Transports |
Wszystkie transporty są włączone. | Bit flaguje wyliczenie HttpTransportType wartości, które mogą ograniczyć transporty, których klient może użyć do nawiązania połączenia. |
LongPolling |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu długiego sondowania. |
WebSockets |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu obiektów WebSocket. |
MinimumProtocolVersion |
0 | Określ minimalną wersję protokołu negocjowania. Służy to do ograniczania klientów do nowszych wersji. |
Transport Long Polling ma dodatkowe opcje, które można skonfigurować przy użyciu LongPolling
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
PollTimeout |
90 sekund | Maksymalny czas oczekiwania serwera na wysłanie komunikatu do klienta przed zakończeniem pojedynczego żądania sondowania. Zmniejszenie tej wartości powoduje, że klient częściej wysyła nowe żądania sondowania. |
Transport protokołu WebSocket ma dodatkowe opcje, które można skonfigurować przy użyciu WebSockets
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
CloseTimeout |
5 s | Po zamknięciu serwera, jeśli klient nie może zamknąć w tym przedziale czasu, połączenie zostanie zakończone. |
SubProtocolSelector |
null |
Delegat, który może służyć do ustawiania nagłówka Sec-WebSocket-Protocol na wartość niestandardową. Delegat odbiera wartości żądane przez klienta jako dane wejściowe i oczekuje się, że zwróci żądaną wartość. |
Konfigurowanie opcji klienta
Opcje klienta można skonfigurować na typie HubConnectionBuilder
(dostępnym na klientach .NET i JavaScript). Jest ona również dostępna w kliencie Java, ale podklasa HttpHubConnectionBuilder
zawiera opcje konfiguracji konstruktora, a także na HubConnection
samym kliencie.
Konfigurowanie rejestrowania
Rejestrowanie jest konfigurowane w kliencie .NET przy użyciu ConfigureLogging
metody . Dostawcy rejestrowania i filtry można zarejestrować w taki sam sposób, jak na serwerze. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rejestrowania w usłudze ASP.NET Core .
Uwaga
Aby zarejestrować dostawców rejestrowania, należy zainstalować niezbędne pakiety. Aby uzyskać pełną listę, zobacz sekcję Wbudowane dostawcy rejestrowania w dokumentacji.
Aby na przykład włączyć rejestrowanie konsoli, zainstaluj Microsoft.Extensions.Logging.Console
pakiet NuGet. Wywołaj metodę AddConsole
rozszerzenia:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
W kliencie JavaScript istnieje podobna configureLogging
metoda. Podaj wartość wskazującą LogLevel
minimalny poziom komunikatów dziennika do utworzenia. Dzienniki są zapisywane w oknie konsoli przeglądarki.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
LogLevel
Zamiast wartości można również podać string
wartość reprezentującą nazwę poziomu dziennika. Jest to przydatne podczas konfigurowania SignalR rejestrowania w środowiskach, w których nie masz dostępu do LogLevel
stałych.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
W poniższej tabeli wymieniono dostępne poziomy dziennika. Wartość, którą podajesz, ustawia configureLogging
minimalny poziom dziennika, który zostanie zarejestrowany. Komunikaty zarejestrowane na tym poziomie lub poziomy wymienione po niej w tabeli zostaną zarejestrowane.
String | PoziomRejestrowania |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info lub information |
LogLevel.Information |
warn lub warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Uwaga
Aby całkowicie wyłączyć rejestrowanie, określ signalR.LogLevel.None
metodę configureLogging
.
Aby uzyskać więcej informacji na temat rejestrowania, zobacz dokumentację SignalRdiagnostyki.
Klient SignalR Java używa biblioteki SLF4J do rejestrowania. Jest to interfejs API rejestrowania wysokiego poziomu, który umożliwia użytkownikom biblioteki wybranie własnej implementacji rejestrowania przez wprowadzenie określonej zależności rejestrowania. Poniższy fragment kodu pokazuje, jak używać go java.util.logging
z klientem SignalR Java.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Jeśli nie skonfigurujesz rejestrowania w zależnościach, SLF4J ładuje domyślny rejestrator bez operacji z następującym komunikatem ostrzegawczym:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Można to bezpiecznie zignorować.
Konfigurowanie dozwolonych transportów
Transporty używane przez SignalR program można skonfigurować w wywołaniu WithUrl
(withUrl
w języku JavaScript). Bitowe or wartości parametru HttpTransportType
można użyć do ograniczenia klienta do używania tylko określonych transportów. Wszystkie transporty są domyślnie włączone.
Na przykład aby wyłączyć transport zdarzeń wysłanych przez serwer, ale zezwalać na połączenia WebSocket i Long Polling:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
W kliencie języka JavaScript transporty są konfigurowane przez ustawienie transport
pola w obiekcie options udostępnionym na wartość withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
W tej wersji obiektów websocket klienta Java jest jedynym dostępnym transportem.
W kliencie Java transport jest wybierany przy użyciu withTransport
metody w pliku HttpHubConnectionBuilder
. Klient Języka Java domyślnie używa transportu obiektów WebSocket.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Uwaga
Klient SignalR java nie obsługuje jeszcze powrotu transportu.
Konfigurowanie uwierzytelniania elementu nośnego
Aby udostępnić dane uwierzytelniania wraz z żądaniami SignalR , użyj AccessTokenProvider
opcji (accessTokenFactory
w języku JavaScript), aby określić funkcję zwracającą żądany token dostępu. W kliencie platformy .NET ten token dostępu jest przekazywany jako token HTTP "Uwierzytelnianie elementu nośnego" (przy użyciu Authorization
nagłówka o typie Bearer
). W kliencie JavaScript token dostępu jest używany jako token elementu nośnego, z wyjątkiem kilku przypadków, w których interfejsy API przeglądarki ograniczają możliwość stosowania nagłówków (w szczególności w żądaniach zdarzeń wysłanych przez serwer i obiektów WebSocket). W takich przypadkach token dostępu jest udostępniany jako wartość access_token
ciągu zapytania .
W kliencie AccessTokenProvider
platformy .NET można określić opcję przy użyciu delegata opcji w programie WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
W kliencie JavaScript token dostępu jest konfigurowany przez ustawienie accessTokenFactory
pola w obiekcie options w withUrl
pliku :
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
W kliencie SignalR języka Java można skonfigurować token elementu nośnego do użycia do uwierzytelniania, zapewniając fabrykę tokenów dostępu do programu HttpHubConnectionBuilder. Użyj funkcji withAccessTokenFactory, aby udostępnić pojedynczy <ciąg> RxJava. Wywołanie metody Single.defer umożliwia napisanie logiki w celu utworzenia tokenów dostępu dla klienta.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Konfigurowanie limitu czasu i opcji zachowania aktywności
Dodatkowe opcje konfigurowania limitu czasu i zachowania utrzymania aktywności są dostępne w HubConnection
samym obiekcie:
Opcja | Wartość domyślna | opis |
---|---|---|
ServerTimeout |
30 sekund (30 000 milisekund) | Limit czasu działania serwera. Jeśli serwer nie wysłał komunikatu w tym interwale, klient uzna serwer za odłączony i wyzwoli Closed zdarzenie (onclose w języku JavaScript). Ta wartość musi być wystarczająco duża, aby wiadomość ping została wysłana z serwera i odebrana przez klienta w przedziale czasu. Zalecana wartość jest liczbą co najmniej dwukrotnie większą niż wartość serwera KeepAliveInterval , aby umożliwić odebranie poleceń ping. |
HandshakeTimeout |
15 sekund | Limit czasu początkowego uzgadniania serwera. Jeśli serwer nie wysyła odpowiedzi uzgadniania w tym interwale, klient anuluje uzgadnianie i wyzwala Closed zdarzenie (onclose w języku JavaScript). Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Określa interwał wysyłania komunikatów ping przez klienta. Wysłanie dowolnego komunikatu z klienta spowoduje zresetowanie czasomierza do początku interwału. Jeśli klient nie wysłał komunikatu w ClientTimeoutInterval zestawie na serwerze, serwer uzna klienta za odłączonego. |
W kliencie .NET wartości limitu czasu są określane jako TimeSpan
wartości.
Konfigurowanie dodatkowych opcji
Dodatkowe opcje można skonfigurować w metodzie WithUrl
(withUrl
w języku JavaScript) w systemie HubConnectionBuilder
lub w różnych interfejsach API konfiguracji w kliencie HttpHubConnectionBuilder
Java:
Opcja platformy .NET | Wartość domyślna | opis |
---|---|---|
AccessTokenProvider |
null |
Funkcja zwracająca ciąg, który jest dostarczany jako token uwierzytelniania elementu nośnego w żądaniach HTTP. |
SkipNegotiation |
false |
Ustaw tę opcję, aby true pominąć krok negocjacji. Obsługiwane tylko wtedy, gdy transport obiektów WebSockets jest jedynym włączonym transportem. Nie można włączyć tego ustawienia w przypadku korzystania z usługi platformy Azure SignalR . |
ClientCertificates |
Pusty | Kolekcja certyfikatów TLS do wysyłania do uwierzytelniania żądań. |
Cookies |
Pusty | Kolekcja żądań HTTP cookiedo wysłania przy użyciu każdego żądania HTTP. |
Credentials |
Pusty | Poświadczenia do wysłania przy użyciu każdego żądania HTTP. |
CloseTimeout |
5 s | Tylko obiekty WebSocket. Maksymalny czas oczekiwania klienta po zamknięciu serwera w celu potwierdzenia zamknięcia żądania zamknięcia. Jeśli serwer nie potwierdzi zamknięcia w tym czasie, klient rozłącza się. |
Headers |
Pusty | Mapa dodatkowych nagłówków HTTP do wysłania przy użyciu każdego żądania HTTP. |
HttpMessageHandlerFactory |
null |
Pełnomocnik, który może służyć do konfigurowania lub zastępowania używanego HttpMessageHandler do wysyłania żądań HTTP. Nie jest używany w przypadku połączeń protokołu WebSocket. Ten delegat musi zwrócić wartość inną niż null i otrzymuje wartość domyślną jako parametr. Zmodyfikuj ustawienia dla tej wartości domyślnej i zwróć je lub zwróć nowe HttpMessageHandler wystąpienie. Podczas zastępowania programu obsługi pamiętaj, aby skopiować ustawienia, które chcesz zachować z dostarczonej procedury obsługi, w przeciwnym razie skonfigurowane opcje (takie jak Cookies i Nagłówki) nie będą stosowane do nowej procedury obsługi. |
Proxy |
null |
Serwer proxy HTTP do użycia podczas wysyłania żądań HTTP. |
UseDefaultCredentials |
false |
Ustaw tę wartość logiczną, aby wysyłać domyślne poświadczenia dla żądań HTTP i WebSocket. Umożliwia to korzystanie z uwierzytelniania systemu Windows. |
WebSocketConfiguration |
null |
Delegat, który może służyć do konfigurowania dodatkowych opcji protokołu WebSocket. Odbiera wystąpienie ClientWebSocketOptions , którego można użyć do skonfigurowania opcji. |
W kliencie platformy .NET te opcje można modyfikować za pomocą delegata opcji dostarczonych do WithUrl
programu :
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
W kliencie Języka JavaScript te opcje można podać w obiekcie JavaScript udostępnionym użytkownikowi withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
W kliencie Języka Java te opcje można skonfigurować przy użyciu metod zwróconych HttpHubConnectionBuilder
z obiektu HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Dodatkowe zasoby
- Wprowadzenie do platformy ASP.NET Core SignalR
- Używanie koncentratorów w technologii ASP.NET Core SignalR
- ASP.NET Core SignalR JavaScript client
- klient platformy .NET platformy ASP.NET Core SignalR
- Używanie protokołu MessagePack Hub w programie SignalR dla platformy ASP.NET Core
- platformy obsługiwane przez platformy ASP.NET Core SignalR
JSOpcje serializacji ON/MessagePack
ASP.NET Core SignalR obsługuje dwa protokoły kodowania komunikatów: JSON i MessagePack. Każdy protokół ma opcje konfiguracji serializacji.
JSW przypadku serializacji można skonfigurować na serwerze przy użyciu AddJsonProtocol metody rozszerzenia. AddJsonProtocol
można dodać po AddSignalR w pliku Startup.ConfigureServices
. Metoda AddJsonProtocol
przyjmuje delegata, który odbiera options
obiekt. Właściwość PayloadSerializerOptions tego obiektu jest obiektem System.Text.Json
JsonSerializerOptions , który może służyć do konfigurowania serializacji argumentów i zwracanych wartości. Aby uzyskać więcej informacji, zobacz dokumentację System.Text.Json.
Aby na przykład skonfigurować serializator tak, aby nie zmieniał wielkości liter nazw właściwości, a nie domyślne nazwy przypadków camel, użyj następującego kodu w pliku Startup.ConfigureServices
:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
W kliencie platformy .NET w systemie istnieje ta sama AddJsonProtocol
metoda rozszerzenia.HubConnectionBuilder Aby Microsoft.Extensions.DependencyInjection
rozpoznać metodę rozszerzenia, należy zaimportować przestrzeń nazw:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Uwaga
Obecnie nie można skonfigurować JSserializacji ON w kliencie JavaScript.
Przełączanie do pliku Newtonsoft.Json
Jeśli potrzebujesz funkcji Newtonsoft.Json
, które nie są obsługiwane w programie System.Text.Json
, zobacz Przełączanie na Newtonsoft.Json
.
Opcje serializacji messagePack
Serializacji MessagePack można skonfigurować, podając delegata do wywołania AddMessagePackProtocol . Aby uzyskać więcej informacji, zobacz MessagePack w pliku SignalR .
Uwaga
Obecnie nie można skonfigurować serializacji MessagePack w kliencie JavaScript.
Konfigurowanie opcji serwera
W poniższej tabeli opisano opcje konfigurowania SignalR koncentratorów:
Opcja | Wartość domyślna | opis |
---|---|---|
ClientTimeoutInterval |
30 sekund | Serwer rozważa rozłączenie klienta, jeśli nie odebrał komunikatu (w tym zachowania aktywności) w tym interwale. Może upłynąć dłużej niż ten interwał limitu czasu, aby klient został oznaczony jako odłączony ze względu na sposób implementacji. Zalecana wartość jest dwukrotnie ceniona KeepAliveInterval . |
HandshakeTimeout |
15 sekund | Jeśli klient nie wysyła początkowego komunikatu uzgadniania w tym przedziale czasu, połączenie zostanie zamknięte. Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Jeśli serwer nie wysłał komunikatu w tym interwale, wiadomość ping zostanie wysłana automatycznie, aby zachować otwarte połączenie. Podczas zmiany KeepAliveInterval zmień ServerTimeout ustawienie lub serverTimeoutInMilliseconds na kliencie. Zalecana ServerTimeout wartość lub serverTimeoutInMilliseconds jest dwukrotnie ceniona KeepAliveInterval . |
SupportedProtocols |
Wszystkie zainstalowane protokoły | Protokoły obsługiwane przez to centrum. Domyślnie wszystkie protokoły zarejestrowane na serwerze są dozwolone. Protokoły można usunąć z tej listy, aby wyłączyć określone protokoły dla poszczególnych centrów. |
EnableDetailedErrors |
false |
Jeśli true , szczegółowe komunikaty wyjątków są zwracane do klientów, gdy wyjątek jest zgłaszany w metodzie Centrum. Wartością domyślną jest to false , że te komunikaty wyjątków mogą zawierać poufne informacje. |
StreamBufferCapacity |
10 |
Maksymalna liczba elementów, które mogą być buforowane dla strumieni przekazywania klienta. Jeśli ten limit zostanie osiągnięty, przetwarzanie wywołań zostanie zablokowane, dopóki serwer nie przetworzy elementów strumienia. |
MaximumReceiveMessageSize |
32 KB | Maksymalny rozmiar pojedynczego przychodzącego komunikatu centrum. Zwiększenie wartości może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS). |
MaximumParallelInvocationsPerClient |
1 | Maksymalna liczba metod koncentratora, które każdy klient może wywołać równolegle przed kolejkowaniem. |
Opcje można skonfigurować dla wszystkich centrów, udostępniając delegat opcji do wywołania AddSignalR
w programie Startup.ConfigureServices
.
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Opcje pojedynczego koncentratora zastępują opcje globalne dostępne w programie AddSignalR
i można je skonfigurować przy użyciu polecenia AddHubOptions:
services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Zaawansowane opcje konfiguracji PROTOKOŁU HTTP
Służy HttpConnectionDispatcherOptions
do konfigurowania ustawień zaawansowanych związanych z transportami i zarządzaniem buforem pamięci. Te opcje są konfigurowane przez przekazanie delegata do MapHub elementu w programie Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
});
});
}
W poniższej tabeli opisano opcje konfigurowania zaawansowanych opcji http platformy ASP.NET Core SignalR:
Opcja | Wartość domyślna | opis |
---|---|---|
ApplicationMaxBufferSize |
32 KB | Maksymalna liczba bajtów odebranych od klienta, który buforuje serwer przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
AuthorizationData |
Dane automatycznie zbierane z atrybutów zastosowanych Authorize do klasy Hub. |
Lista obiektów używanych IAuthorizeData do określenia, czy klient jest autoryzowany do łączenia się z koncentratorem. |
TransportMaxBufferSize |
32 KB | Maksymalna liczba bajtów wysyłanych przez aplikację buforowanych przez serwer przed zaobserwowanym backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze buforowanie większych komunikatów bez oczekiwania na represje wsteczne, ale może zwiększyć zużycie pamięci. |
Transports |
Wszystkie transporty są włączone. | Bit flaguje wyliczenie HttpTransportType wartości, które mogą ograniczyć transporty, których klient może użyć do nawiązania połączenia. |
LongPolling |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu długiego sondowania. |
WebSockets |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu obiektów WebSocket. |
MinimumProtocolVersion |
0 | Określ minimalną wersję protokołu negocjowania. Służy to do ograniczania klientów do nowszych wersji. |
Transport Long Polling ma dodatkowe opcje, które można skonfigurować przy użyciu LongPolling
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
PollTimeout |
90 sekund | Maksymalny czas oczekiwania serwera na wysłanie komunikatu do klienta przed zakończeniem pojedynczego żądania sondowania. Zmniejszenie tej wartości powoduje, że klient częściej wysyła nowe żądania sondowania. |
Transport protokołu WebSocket ma dodatkowe opcje, które można skonfigurować przy użyciu WebSockets
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
CloseTimeout |
5 s | Po zamknięciu serwera, jeśli klient nie może zamknąć w tym przedziale czasu, połączenie zostanie zakończone. |
SubProtocolSelector |
null |
Delegat, który może służyć do ustawiania nagłówka Sec-WebSocket-Protocol na wartość niestandardową. Delegat odbiera wartości żądane przez klienta jako dane wejściowe i oczekuje się, że zwróci żądaną wartość. |
Konfigurowanie opcji klienta
Opcje klienta można skonfigurować na typie HubConnectionBuilder
(dostępnym na klientach .NET i JavaScript). Jest ona również dostępna w kliencie Java, ale podklasa HttpHubConnectionBuilder
zawiera opcje konfiguracji konstruktora, a także na HubConnection
samym kliencie.
Konfigurowanie rejestrowania
Rejestrowanie jest konfigurowane w kliencie .NET przy użyciu ConfigureLogging
metody . Dostawcy rejestrowania i filtry można zarejestrować w taki sam sposób, jak na serwerze. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rejestrowania w usłudze ASP.NET Core .
Uwaga
Aby zarejestrować dostawców rejestrowania, należy zainstalować niezbędne pakiety. Aby uzyskać pełną listę, zobacz sekcję Wbudowane dostawcy rejestrowania w dokumentacji.
Aby na przykład włączyć rejestrowanie konsoli, zainstaluj Microsoft.Extensions.Logging.Console
pakiet NuGet. Wywołaj metodę AddConsole
rozszerzenia:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
W kliencie JavaScript istnieje podobna configureLogging
metoda. Podaj wartość wskazującą LogLevel
minimalny poziom komunikatów dziennika do utworzenia. Dzienniki są zapisywane w oknie konsoli przeglądarki.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
LogLevel
Zamiast wartości można również podać string
wartość reprezentującą nazwę poziomu dziennika. Jest to przydatne podczas konfigurowania SignalR rejestrowania w środowiskach, w których nie masz dostępu do LogLevel
stałych.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
W poniższej tabeli wymieniono dostępne poziomy dziennika. Wartość, którą podajesz, ustawia configureLogging
minimalny poziom dziennika, który zostanie zarejestrowany. Komunikaty zarejestrowane na tym poziomie lub poziomy wymienione po niej w tabeli zostaną zarejestrowane.
String | PoziomRejestrowania |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info lub information |
LogLevel.Information |
warn lub warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Uwaga
Aby całkowicie wyłączyć rejestrowanie, określ signalR.LogLevel.None
metodę configureLogging
.
Aby uzyskać więcej informacji na temat rejestrowania, zobacz dokumentację SignalRdiagnostyki.
Klient SignalR Java używa biblioteki SLF4J do rejestrowania. Jest to interfejs API rejestrowania wysokiego poziomu, który umożliwia użytkownikom biblioteki wybranie własnej implementacji rejestrowania przez wprowadzenie określonej zależności rejestrowania. Poniższy fragment kodu pokazuje, jak używać go java.util.logging
z klientem SignalR Java.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Jeśli nie skonfigurujesz rejestrowania w zależnościach, SLF4J ładuje domyślny rejestrator bez operacji z następującym komunikatem ostrzegawczym:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Można to bezpiecznie zignorować.
Konfigurowanie dozwolonych transportów
Transporty używane przez SignalR program można skonfigurować w wywołaniu WithUrl
(withUrl
w języku JavaScript). Bitowe or wartości parametru HttpTransportType
można użyć do ograniczenia klienta do używania tylko określonych transportów. Wszystkie transporty są domyślnie włączone.
Na przykład aby wyłączyć transport zdarzeń wysłanych przez serwer, ale zezwalać na połączenia WebSocket i Long Polling:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
W kliencie języka JavaScript transporty są konfigurowane przez ustawienie transport
pola w obiekcie options udostępnionym na wartość withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
W tej wersji obiektów websocket klienta Java jest jedynym dostępnym transportem.
W kliencie Java transport jest wybierany przy użyciu withTransport
metody w pliku HttpHubConnectionBuilder
. Klient Języka Java domyślnie używa transportu obiektów WebSocket.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Uwaga
Klient SignalR java nie obsługuje jeszcze powrotu transportu.
Konfigurowanie uwierzytelniania elementu nośnego
Aby udostępnić dane uwierzytelniania wraz z żądaniami SignalR , użyj AccessTokenProvider
opcji (accessTokenFactory
w języku JavaScript), aby określić funkcję zwracającą żądany token dostępu. W kliencie platformy .NET ten token dostępu jest przekazywany jako token HTTP "Uwierzytelnianie elementu nośnego" (przy użyciu Authorization
nagłówka o typie Bearer
). W kliencie JavaScript token dostępu jest używany jako token elementu nośnego, z wyjątkiem kilku przypadków, w których interfejsy API przeglądarki ograniczają możliwość stosowania nagłówków (w szczególności w żądaniach zdarzeń wysłanych przez serwer i obiektów WebSocket). W takich przypadkach token dostępu jest udostępniany jako wartość access_token
ciągu zapytania .
W kliencie AccessTokenProvider
platformy .NET można określić opcję przy użyciu delegata opcji w programie WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
W kliencie JavaScript token dostępu jest konfigurowany przez ustawienie accessTokenFactory
pola w obiekcie options w withUrl
pliku :
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
W kliencie SignalR języka Java można skonfigurować token elementu nośnego do użycia do uwierzytelniania, zapewniając fabrykę tokenów dostępu do programu HttpHubConnectionBuilder. Użyj funkcji withAccessTokenFactory, aby udostępnić pojedynczy <ciąg> RxJava. Wywołanie metody Single.defer umożliwia napisanie logiki w celu utworzenia tokenów dostępu dla klienta.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Konfigurowanie limitu czasu i opcji zachowania aktywności
Dodatkowe opcje konfigurowania limitu czasu i zachowania utrzymania aktywności są dostępne w HubConnection
samym obiekcie:
Opcja | Wartość domyślna | opis |
---|---|---|
ServerTimeout |
30 sekund (30 000 milisekund) | Limit czasu działania serwera. Jeśli serwer nie wysłał komunikatu w tym interwale, klient uzna serwer za odłączony i wyzwoli Closed zdarzenie (onclose w języku JavaScript). Ta wartość musi być wystarczająco duża, aby wiadomość ping została wysłana z serwera i odebrana przez klienta w przedziale czasu. Zalecana wartość jest liczbą co najmniej dwukrotnie większą niż wartość serwera KeepAliveInterval , aby umożliwić odebranie poleceń ping. |
HandshakeTimeout |
15 sekund | Limit czasu początkowego uzgadniania serwera. Jeśli serwer nie wysyła odpowiedzi uzgadniania w tym interwale, klient anuluje uzgadnianie i wyzwala Closed zdarzenie (onclose w języku JavaScript). Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Określa interwał wysyłania komunikatów ping przez klienta. Wysłanie dowolnego komunikatu z klienta spowoduje zresetowanie czasomierza do początku interwału. Jeśli klient nie wysłał komunikatu w ClientTimeoutInterval zestawie na serwerze, serwer uzna klienta za odłączonego. |
W kliencie .NET wartości limitu czasu są określane jako TimeSpan
wartości.
Konfigurowanie dodatkowych opcji
Dodatkowe opcje można skonfigurować w metodzie WithUrl
(withUrl
w języku JavaScript) w systemie HubConnectionBuilder
lub w różnych interfejsach API konfiguracji w kliencie HttpHubConnectionBuilder
Java:
Opcja platformy .NET | Wartość domyślna | opis |
---|---|---|
AccessTokenProvider |
null |
Funkcja zwracająca ciąg, który jest dostarczany jako token uwierzytelniania elementu nośnego w żądaniach HTTP. |
SkipNegotiation |
false |
Ustaw tę opcję, aby true pominąć krok negocjacji. Obsługiwane tylko wtedy, gdy transport obiektów WebSockets jest jedynym włączonym transportem. Nie można włączyć tego ustawienia w przypadku korzystania z usługi platformy Azure SignalR . |
ClientCertificates |
Pusty | Kolekcja certyfikatów TLS do wysyłania do uwierzytelniania żądań. |
Cookies |
Pusty | Kolekcja żądań HTTP cookiedo wysłania przy użyciu każdego żądania HTTP. |
Credentials |
Pusty | Poświadczenia do wysłania przy użyciu każdego żądania HTTP. |
CloseTimeout |
5 s | Tylko obiekty WebSocket. Maksymalny czas oczekiwania klienta po zamknięciu serwera w celu potwierdzenia zamknięcia żądania zamknięcia. Jeśli serwer nie potwierdzi zamknięcia w tym czasie, klient rozłącza się. |
Headers |
Pusty | Mapa dodatkowych nagłówków HTTP do wysłania przy użyciu każdego żądania HTTP. |
HttpMessageHandlerFactory |
null |
Pełnomocnik, który może służyć do konfigurowania lub zastępowania używanego HttpMessageHandler do wysyłania żądań HTTP. Nie jest używany w przypadku połączeń protokołu WebSocket. Ten delegat musi zwrócić wartość inną niż null i otrzymuje wartość domyślną jako parametr. Zmodyfikuj ustawienia dla tej wartości domyślnej i zwróć je lub zwróć nowe HttpMessageHandler wystąpienie. Podczas zastępowania programu obsługi pamiętaj, aby skopiować ustawienia, które chcesz zachować z dostarczonej procedury obsługi, w przeciwnym razie skonfigurowane opcje (takie jak Cookies i Nagłówki) nie będą stosowane do nowej procedury obsługi. |
Proxy |
null |
Serwer proxy HTTP do użycia podczas wysyłania żądań HTTP. |
UseDefaultCredentials |
false |
Ustaw tę wartość logiczną, aby wysyłać domyślne poświadczenia dla żądań HTTP i WebSocket. Umożliwia to korzystanie z uwierzytelniania systemu Windows. |
WebSocketConfiguration |
null |
Delegat, który może służyć do konfigurowania dodatkowych opcji protokołu WebSocket. Odbiera wystąpienie ClientWebSocketOptions , którego można użyć do skonfigurowania opcji. |
W kliencie platformy .NET te opcje można modyfikować za pomocą delegata opcji dostarczonych do WithUrl
programu :
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.SkipNegotiation = true;
options.Transports = HttpTransportType.WebSockets;
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
W kliencie Języka JavaScript te opcje można podać w obiekcie JavaScript udostępnionym użytkownikowi withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
// "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
headers: { "Foo": "Bar" },
transport: signalR.HttpTransportType.LongPolling
})
.build();
W kliencie Języka Java te opcje można skonfigurować przy użyciu metod zwróconych HttpHubConnectionBuilder
z obiektu HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Dodatkowe zasoby
- Wprowadzenie do platformy ASP.NET Core SignalR
- Używanie koncentratorów w technologii ASP.NET Core SignalR
- ASP.NET Core SignalR JavaScript client
- klient platformy .NET platformy ASP.NET Core SignalR
- Używanie protokołu MessagePack Hub w programie SignalR dla platformy ASP.NET Core
- platformy obsługiwane przez platformy ASP.NET Core SignalR
JSOpcje serializacji ON/MessagePack
ASP.NET Core SignalR obsługuje dwa protokoły kodowania komunikatów: JSON i MessagePack. Każdy protokół ma opcje konfiguracji serializacji.
JSW przypadku serializacji można skonfigurować na serwerze przy użyciu AddJsonProtocol metody rozszerzenia. AddJsonProtocol
można dodać po AddSignalR w pliku Program.cs
. Metoda AddJsonProtocol
przyjmuje delegata, który odbiera options
obiekt. Właściwość PayloadSerializerOptions tego obiektu jest obiektem System.Text.Json
JsonSerializerOptions , który może służyć do konfigurowania serializacji argumentów i zwracanych wartości. Aby uzyskać więcej informacji, zobacz dokumentację System.Text.Json.
Aby na przykład skonfigurować serializator tak, aby nie zmieniał wielkości liter nazw właściwości, a nie domyślne nazwy przypadków camel, użyj następującego kodu w pliku Program.cs
:
builder.Services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
W kliencie platformy .NET w systemie istnieje ta sama AddJsonProtocol
metoda rozszerzenia.HubConnectionBuilder Aby Microsoft.Extensions.DependencyInjection
rozpoznać metodę rozszerzenia, należy zaimportować przestrzeń nazw:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Uwaga
Obecnie nie można skonfigurować JSserializacji ON w kliencie JavaScript.
Przełączanie do pliku Newtonsoft.Json
Jeśli potrzebujesz funkcji Newtonsoft.Json
, które nie są obsługiwane w programie System.Text.Json
, zobacz Przełączanie na Newtonsoft.Json
.
Opcje serializacji messagePack
Serializacji MessagePack można skonfigurować, podając delegata do wywołania AddMessagePackProtocol . Aby uzyskać więcej informacji, zobacz MessagePack w pliku SignalR .
Uwaga
Obecnie nie można skonfigurować serializacji MessagePack w kliencie JavaScript.
Konfigurowanie opcji serwera
W poniższej tabeli opisano opcje konfigurowania SignalR koncentratorów:
Opcja | Wartość domyślna | opis |
---|---|---|
ClientTimeoutInterval |
30 sekund | Serwer rozważa rozłączenie klienta, jeśli nie odebrał komunikatu (w tym zachowania aktywności) w tym interwale. Może upłynąć dłużej niż ten interwał limitu czasu, aby klient został oznaczony jako odłączony ze względu na sposób implementacji. Zalecana wartość jest dwukrotnie ceniona KeepAliveInterval . |
HandshakeTimeout |
15 sekund | Jeśli klient nie wysyła początkowego komunikatu uzgadniania w tym przedziale czasu, połączenie zostanie zamknięte. Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Jeśli serwer nie wysłał komunikatu w tym interwale, wiadomość ping zostanie wysłana automatycznie, aby zachować otwarte połączenie. Podczas zmiany KeepAliveInterval zmień ServerTimeout ustawienie lub serverTimeoutInMilliseconds na kliencie. Zalecana ServerTimeout wartość lub serverTimeoutInMilliseconds jest dwukrotnie ceniona KeepAliveInterval . |
SupportedProtocols |
Wszystkie zainstalowane protokoły | Protokoły obsługiwane przez to centrum. Domyślnie wszystkie protokoły zarejestrowane na serwerze są dozwolone. Protokoły można usunąć z tej listy, aby wyłączyć określone protokoły dla poszczególnych centrów. |
EnableDetailedErrors |
false |
Jeśli true , szczegółowe komunikaty wyjątków są zwracane do klientów, gdy wyjątek jest zgłaszany w metodzie Centrum. Wartością domyślną jest to false , że te komunikaty wyjątków mogą zawierać poufne informacje. |
StreamBufferCapacity |
10 |
Maksymalna liczba elementów, które mogą być buforowane dla strumieni przekazywania klienta. Jeśli ten limit zostanie osiągnięty, przetwarzanie wywołań zostanie zablokowane, dopóki serwer nie przetworzy elementów strumienia. |
MaximumReceiveMessageSize |
32 KB | Maksymalny rozmiar pojedynczego przychodzącego komunikatu centrum. Zwiększenie wartości może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS). |
MaximumParallelInvocationsPerClient |
1 | Maksymalna liczba metod koncentratora, które każdy klient może wywołać równolegle przed kolejkowaniem. |
Opcje można skonfigurować dla wszystkich centrów, udostępniając delegat opcji do wywołania AddSignalR
w programie Program.cs
.
builder.Services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
Opcje pojedynczego koncentratora zastępują opcje globalne dostępne w programie AddSignalR
i można je skonfigurować przy użyciu polecenia AddHubOptions:
builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Zaawansowane opcje konfiguracji PROTOKOŁU HTTP
Służy HttpConnectionDispatcherOptions
do konfigurowania ustawień zaawansowanych związanych z transportami i zarządzaniem buforem pamięci. Te opcje są konfigurowane przez przekazanie delegata do MapHub elementu w programie Program.cs
.
using Microsoft.AspNetCore.Http.Connections;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddSignalR();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
}
);
app.Run();
W poniższej tabeli opisano opcje konfigurowania zaawansowanych opcji http platformy ASP.NET Core SignalR:
Opcja | Wartość domyślna | opis |
---|---|---|
ApplicationMaxBufferSize |
64 KB | Maksymalna liczba bajtów odebranych od klienta, który buforuje serwer przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
TransportMaxBufferSize |
64 KB | Maksymalna liczba bajtów wysyłanych przez aplikację buforowanych przez serwer przed zaobserwowanym backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze buforowanie większych komunikatów bez oczekiwania na tłumienie wsteczne, ale może zwiększyć zużycie pamięci. |
AuthorizationData |
Dane automatycznie zbierane z atrybutów zastosowanych Authorize do klasy Hub. |
Lista obiektów używanych IAuthorizeData do określenia, czy klient jest autoryzowany do łączenia się z koncentratorem. |
Transports |
Wszystkie transporty są włączone. | Bit flaguje wyliczenie HttpTransportType wartości, które mogą ograniczyć transporty, których klient może użyć do nawiązania połączenia. |
LongPolling |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu długiego sondowania. |
WebSockets |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu obiektów WebSocket. |
MinimumProtocolVersion |
0 | Określ minimalną wersję protokołu negocjowania. Służy to do ograniczania klientów do nowszych wersji. |
CloseOnAuthenticationExpiration |
fałsz | Ustaw tę opcję, aby włączyć śledzenie wygasania uwierzytelniania, które spowoduje zamknięcie połączeń po wygaśnięciu tokenu. |
Transport Long Polling ma dodatkowe opcje, które można skonfigurować przy użyciu LongPolling
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
PollTimeout |
90 sekund | Maksymalny czas oczekiwania serwera na wysłanie komunikatu do klienta przed zakończeniem pojedynczego żądania sondowania. Zmniejszenie tej wartości powoduje, że klient częściej wysyła nowe żądania sondowania. |
Transport protokołu WebSocket ma dodatkowe opcje, które można skonfigurować przy użyciu WebSockets
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
CloseTimeout |
5 s | Po zamknięciu serwera, jeśli klient nie może zamknąć w tym przedziale czasu, połączenie zostanie zakończone. |
SubProtocolSelector |
null |
Delegat, który może służyć do ustawiania nagłówka Sec-WebSocket-Protocol na wartość niestandardową. Delegat odbiera wartości żądane przez klienta jako dane wejściowe i oczekuje się, że zwróci żądaną wartość. |
Konfigurowanie opcji klienta
Opcje klienta można skonfigurować na typie HubConnectionBuilder
(dostępnym na klientach .NET i JavaScript). Jest ona również dostępna w kliencie Java, ale podklasa HttpHubConnectionBuilder
zawiera opcje konfiguracji konstruktora, a także na HubConnection
samym kliencie.
Konfigurowanie rejestrowania
Rejestrowanie jest konfigurowane w kliencie .NET przy użyciu ConfigureLogging
metody . Dostawcy rejestrowania i filtry można zarejestrować w taki sam sposób, jak na serwerze. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rejestrowania w usłudze ASP.NET Core .
Uwaga
Aby zarejestrować dostawców rejestrowania, należy zainstalować niezbędne pakiety. Aby uzyskać pełną listę, zobacz sekcję Wbudowane dostawcy rejestrowania w dokumentacji.
Aby na przykład włączyć rejestrowanie konsoli, zainstaluj Microsoft.Extensions.Logging.Console
pakiet NuGet. Wywołaj metodę AddConsole
rozszerzenia:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
W kliencie JavaScript istnieje podobna configureLogging
metoda. Podaj wartość wskazującą LogLevel
minimalny poziom komunikatów dziennika do utworzenia. Dzienniki są zapisywane w oknie konsoli przeglądarki.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
LogLevel
Zamiast wartości można również podać string
wartość reprezentującą nazwę poziomu dziennika. Jest to przydatne podczas konfigurowania SignalR rejestrowania w środowiskach, w których nie masz dostępu do LogLevel
stałych.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
W poniższej tabeli wymieniono dostępne poziomy dziennika. Wartość, którą podajesz, ustawia configureLogging
minimalny poziom dziennika, który zostanie zarejestrowany. Komunikaty zarejestrowane na tym poziomie lub poziomy wymienione po niej w tabeli zostaną zarejestrowane.
String | PoziomRejestrowania |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info lub information |
LogLevel.Information |
warn lub warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Uwaga
Aby całkowicie wyłączyć rejestrowanie, określ signalR.LogLevel.None
metodę configureLogging
.
Aby uzyskać więcej informacji na temat rejestrowania, zobacz dokumentację SignalRdiagnostyki.
Klient SignalR Java używa biblioteki SLF4J do rejestrowania. Jest to interfejs API rejestrowania wysokiego poziomu, który umożliwia użytkownikom biblioteki wybranie własnej implementacji rejestrowania przez wprowadzenie określonej zależności rejestrowania. Poniższy fragment kodu pokazuje, jak używać go java.util.logging
z klientem SignalR Java.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Jeśli nie skonfigurujesz rejestrowania w zależnościach, SLF4J ładuje domyślny rejestrator bez operacji z następującym komunikatem ostrzegawczym:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Można to bezpiecznie zignorować.
Konfigurowanie dozwolonych transportów
Transporty używane przez SignalR program można skonfigurować w wywołaniu WithUrl
(withUrl
w języku JavaScript). Bitowe or wartości parametru HttpTransportType
można użyć do ograniczenia klienta do używania tylko określonych transportów. Wszystkie transporty są domyślnie włączone.
Na przykład aby wyłączyć transport zdarzeń wysłanych przez serwer, ale zezwalać na połączenia WebSocket i Long Polling:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
W kliencie języka JavaScript transporty są konfigurowane przez ustawienie transport
pola w obiekcie options udostępnionym na wartość withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
W tej wersji obiektów websocket klienta Java jest jedynym dostępnym transportem.
W kliencie Java transport jest wybierany przy użyciu withTransport
metody w pliku HttpHubConnectionBuilder
. Klient Języka Java domyślnie używa transportu obiektów WebSocket.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Uwaga
Klient SignalR java nie obsługuje jeszcze powrotu transportu.
Konfigurowanie uwierzytelniania elementu nośnego
Aby udostępnić dane uwierzytelniania wraz z żądaniami SignalR , użyj AccessTokenProvider
opcji (accessTokenFactory
w języku JavaScript), aby określić funkcję zwracającą żądany token dostępu. W kliencie platformy .NET ten token dostępu jest przekazywany jako token HTTP "Uwierzytelnianie elementu nośnego" (przy użyciu Authorization
nagłówka o typie Bearer
). W kliencie JavaScript token dostępu jest używany jako token elementu nośnego, z wyjątkiem kilku przypadków, w których interfejsy API przeglądarki ograniczają możliwość stosowania nagłówków (w szczególności w żądaniach zdarzeń wysłanych przez serwer i obiektów WebSocket). W takich przypadkach token dostępu jest udostępniany jako wartość access_token
ciągu zapytania .
W kliencie AccessTokenProvider
platformy .NET można określić opcję przy użyciu delegata opcji w programie WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
W kliencie JavaScript token dostępu jest konfigurowany przez ustawienie accessTokenFactory
pola w obiekcie options w withUrl
pliku :
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
W kliencie SignalR języka Java można skonfigurować token elementu nośnego do użycia do uwierzytelniania, zapewniając fabrykę tokenów dostępu do programu HttpHubConnectionBuilder. Użyj funkcji withAccessTokenFactory, aby udostępnić pojedynczy <ciąg> RxJava. Wywołanie metody Single.defer umożliwia napisanie logiki w celu utworzenia tokenów dostępu dla klienta.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Konfigurowanie limitu czasu i opcji zachowania aktywności
Dodatkowe opcje konfigurowania limitu czasu i zachowania utrzymania aktywności są dostępne w HubConnection
samym obiekcie:
Opcja | Wartość domyślna | opis |
---|---|---|
ServerTimeout |
30 sekund (30 000 milisekund) | Limit czasu działania serwera. Jeśli serwer nie wysłał komunikatu w tym interwale, klient uzna serwer za odłączony i wyzwoli Closed zdarzenie (onclose w języku JavaScript). Ta wartość musi być wystarczająco duża, aby wiadomość ping została wysłana z serwera i odebrana przez klienta w przedziale czasu. Zalecana wartość jest liczbą co najmniej dwukrotnie większą niż wartość serwera KeepAliveInterval , aby umożliwić odebranie poleceń ping. |
HandshakeTimeout |
15 sekund | Limit czasu początkowego uzgadniania serwera. Jeśli serwer nie wysyła odpowiedzi uzgadniania w tym interwale, klient anuluje uzgadnianie i wyzwala Closed zdarzenie (onclose w języku JavaScript). Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Określa interwał wysyłania komunikatów ping przez klienta. Wysłanie dowolnego komunikatu z klienta spowoduje zresetowanie czasomierza do początku interwału. Jeśli klient nie wysłał komunikatu w ClientTimeoutInterval zestawie na serwerze, serwer uzna klienta za odłączonego. |
W kliencie .NET wartości limitu czasu są określane jako TimeSpan
wartości.
Konfigurowanie dodatkowych opcji
Dodatkowe opcje można skonfigurować w metodzie WithUrl
(withUrl
w języku JavaScript) w systemie HubConnectionBuilder
lub w różnych interfejsach API konfiguracji w kliencie HttpHubConnectionBuilder
Java:
Opcja platformy .NET | Wartość domyślna | opis |
---|---|---|
AccessTokenProvider |
null |
Funkcja zwracająca ciąg, który jest dostarczany jako token uwierzytelniania elementu nośnego w żądaniach HTTP. |
SkipNegotiation |
false |
Ustaw tę opcję, aby true pominąć krok negocjacji. Obsługiwane tylko wtedy, gdy transport obiektów WebSockets jest jedynym włączonym transportem. Nie można włączyć tego ustawienia w przypadku korzystania z usługi platformy Azure SignalR . |
ClientCertificates |
Pusty | Kolekcja certyfikatów TLS do wysyłania do uwierzytelniania żądań. |
Cookies |
Pusty | Kolekcja żądań HTTP cookiedo wysłania przy użyciu każdego żądania HTTP. |
Credentials |
Pusty | Poświadczenia do wysłania przy użyciu każdego żądania HTTP. |
CloseTimeout |
5 s | Tylko obiekty WebSocket. Maksymalny czas oczekiwania klienta po zamknięciu serwera w celu potwierdzenia zamknięcia żądania zamknięcia. Jeśli serwer nie potwierdzi zamknięcia w tym czasie, klient rozłącza się. |
Headers |
Pusty | Mapa dodatkowych nagłówków HTTP do wysłania przy użyciu każdego żądania HTTP. |
HttpMessageHandlerFactory |
null |
Pełnomocnik, który może służyć do konfigurowania lub zastępowania używanego HttpMessageHandler do wysyłania żądań HTTP. Nie jest używany w przypadku połączeń protokołu WebSocket. Ten delegat musi zwrócić wartość inną niż null i otrzymuje wartość domyślną jako parametr. Zmodyfikuj ustawienia dla tej wartości domyślnej i zwróć je lub zwróć nowe HttpMessageHandler wystąpienie. Podczas zastępowania programu obsługi pamiętaj, aby skopiować ustawienia, które chcesz zachować z dostarczonej procedury obsługi, w przeciwnym razie skonfigurowane opcje (takie jak Cookies i Nagłówki) nie będą stosowane do nowej procedury obsługi. |
Proxy |
null |
Serwer proxy HTTP do użycia podczas wysyłania żądań HTTP. |
UseDefaultCredentials |
false |
Ustaw tę wartość logiczną, aby wysyłać domyślne poświadczenia dla żądań HTTP i WebSocket. Umożliwia to korzystanie z uwierzytelniania systemu Windows. |
WebSocketConfiguration |
null |
Delegat, który może służyć do konfigurowania dodatkowych opcji protokołu WebSocket. Odbiera wystąpienie ClientWebSocketOptions , którego można użyć do skonfigurowania opcji. |
ApplicationMaxBufferSize |
1 MB | Maksymalna liczba bajtów odebranych z serwera buforowanych przez klienta przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia klientowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
TransportMaxBufferSize |
1 MB | Maksymalna liczba bajtów wysyłanych przez aplikację użytkownika buforowanych przez klienta przed zaobserwowaniem backpressure. Zwiększenie tej wartości umożliwia klientowi szybsze buforowanie większych komunikatów bez oczekiwania na tłumienie wsteczne, ale może zwiększyć zużycie pamięci. |
W kliencie platformy .NET te opcje można modyfikować za pomocą delegata opcji dostarczonych do WithUrl
programu :
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.SkipNegotiation = true;
options.Transports = HttpTransportType.WebSockets;
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
W kliencie Języka JavaScript te opcje można podać w obiekcie JavaScript udostępnionym użytkownikowi withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
// "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
headers: { "Foo": "Bar" },
transport: signalR.HttpTransportType.LongPolling
})
.build();
W kliencie Języka Java te opcje można skonfigurować przy użyciu metod zwróconych HttpHubConnectionBuilder
z obiektu HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Dodatkowe zasoby
- Wprowadzenie do platformy ASP.NET Core SignalR
- Używanie koncentratorów w technologii ASP.NET Core SignalR
- ASP.NET Core SignalR JavaScript client
- klient platformy .NET platformy ASP.NET Core SignalR
- Używanie protokołu MessagePack Hub w programie SignalR dla platformy ASP.NET Core
- platformy obsługiwane przez platformy ASP.NET Core SignalR
JSOpcje serializacji ON/MessagePack
ASP.NET Core SignalR obsługuje dwa protokoły kodowania komunikatów: JSON i MessagePack. Każdy protokół ma opcje konfiguracji serializacji.
JSW przypadku serializacji można skonfigurować na serwerze przy użyciu AddJsonProtocol metody rozszerzenia. AddJsonProtocol
można dodać po AddSignalR w pliku Startup.ConfigureServices
. Metoda AddJsonProtocol
przyjmuje delegata, który odbiera options
obiekt. Właściwość PayloadSerializerOptions tego obiektu jest obiektem System.Text.Json
JsonSerializerOptions , który może służyć do konfigurowania serializacji argumentów i zwracanych wartości. Aby uzyskać więcej informacji, zobacz dokumentację System.Text.Json.
Aby na przykład skonfigurować serializator tak, aby nie zmieniał wielkości liter nazw właściwości, a nie domyślne nazwy przypadków camel, użyj następującego kodu w pliku Program.cs
:
builder.Services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
});
W kliencie platformy .NET w systemie istnieje ta sama AddJsonProtocol
metoda rozszerzenia.HubConnectionBuilder Aby Microsoft.Extensions.DependencyInjection
rozpoznać metodę rozszerzenia, należy zaimportować przestrzeń nazw:
// At the top of the file:
using Microsoft.Extensions.DependencyInjection;
// When constructing your connection:
var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerOptions.PropertyNamingPolicy = null;
})
.Build();
Uwaga
Obecnie nie można skonfigurować JSserializacji ON w kliencie JavaScript.
Przełączanie do pliku Newtonsoft.Json
Jeśli potrzebujesz funkcji Newtonsoft.Json
, które nie są obsługiwane w programie System.Text.Json
, zobacz Przełączanie na Newtonsoft.Json
.
Opcje serializacji messagePack
Serializacji MessagePack można skonfigurować, podając delegata do wywołania AddMessagePackProtocol . Aby uzyskać więcej informacji, zobacz MessagePack w pliku SignalR .
Uwaga
Obecnie nie można skonfigurować serializacji MessagePack w kliencie JavaScript.
Konfigurowanie opcji serwera
W poniższej tabeli opisano opcje konfigurowania SignalR koncentratorów:
Opcja | Wartość domyślna | opis |
---|---|---|
ClientTimeoutInterval |
30 sekund | Serwer rozważa rozłączenie klienta, jeśli nie odebrał komunikatu (w tym zachowania aktywności) w tym interwale. Może upłynąć dłużej niż ten interwał limitu czasu, aby klient został oznaczony jako odłączony ze względu na sposób implementacji. Zalecana wartość jest dwukrotnie ceniona KeepAliveInterval . |
HandshakeTimeout |
15 sekund | Jeśli klient nie wysyła początkowego komunikatu uzgadniania w tym przedziale czasu, połączenie zostanie zamknięte. Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Jeśli serwer nie wysłał komunikatu w tym interwale, wiadomość ping zostanie wysłana automatycznie, aby zachować otwarte połączenie. Podczas zmiany KeepAliveInterval zmień ServerTimeout ustawienie lub serverTimeoutInMilliseconds na kliencie. Zalecana ServerTimeout wartość lub serverTimeoutInMilliseconds jest dwukrotnie ceniona KeepAliveInterval . |
SupportedProtocols |
Wszystkie zainstalowane protokoły | Protokoły obsługiwane przez to centrum. Domyślnie wszystkie protokoły zarejestrowane na serwerze są dozwolone. Protokoły można usunąć z tej listy, aby wyłączyć określone protokoły dla poszczególnych centrów. |
EnableDetailedErrors |
false |
Jeśli true , szczegółowe komunikaty wyjątków są zwracane do klientów, gdy wyjątek jest zgłaszany w metodzie Centrum. Wartością domyślną jest to false , że te komunikaty wyjątków mogą zawierać poufne informacje. |
StreamBufferCapacity |
10 |
Maksymalna liczba elementów, które mogą być buforowane dla strumieni przekazywania klienta. Jeśli ten limit zostanie osiągnięty, przetwarzanie wywołań zostanie zablokowane, dopóki serwer nie przetworzy elementów strumienia. |
MaximumReceiveMessageSize |
32 KB | Maksymalny rozmiar pojedynczego przychodzącego komunikatu centrum. Zwiększenie wartości może zwiększyć ryzyko ataków typu "odmowa usługi" (DoS). |
MaximumParallelInvocationsPerClient |
1 | Maksymalna liczba metod koncentratora, które każdy klient może wywołać równolegle przed kolejkowaniem. |
DisableImplicitFromServicesParameters |
false |
Argumenty metody koncentratora zostaną rozpoznane z di, jeśli to możliwe. |
Opcje można skonfigurować dla wszystkich centrów, udostępniając delegat opcji do wywołania AddSignalR
w programie Program.cs
.
builder.Services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
Opcje pojedynczego koncentratora zastępują opcje globalne dostępne w programie AddSignalR
i można je skonfigurować przy użyciu polecenia AddHubOptions:
builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
options.EnableDetailedErrors = true;
});
Zaawansowane opcje konfiguracji PROTOKOŁU HTTP
Służy HttpConnectionDispatcherOptions
do konfigurowania ustawień zaawansowanych związanych z transportami i zarządzaniem buforem pamięci. Te opcje są konfigurowane przez przekazanie delegata do MapHub elementu w programie Program.cs
.
using Microsoft.AspNetCore.Http.Connections;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddSignalR();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
options.Transports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;
}
);
app.Run();
W poniższej tabeli opisano opcje konfigurowania zaawansowanych opcji http platformy ASP.NET Core SignalR:
Opcja | Wartość domyślna | opis |
---|---|---|
ApplicationMaxBufferSize |
64 KB | Maksymalna liczba bajtów odebranych od klienta, który buforuje serwer przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
TransportMaxBufferSize |
64 KB | Maksymalna liczba bajtów wysyłanych przez aplikację buforowanych przez serwer przed zaobserwowanym backpressure. Zwiększenie tej wartości umożliwia serwerowi szybsze buforowanie większych komunikatów bez oczekiwania na tłumienie wsteczne, ale może zwiększyć zużycie pamięci. |
AuthorizationData |
Dane automatycznie zbierane z atrybutów zastosowanych Authorize do klasy Hub. |
Lista obiektów używanych IAuthorizeData do określenia, czy klient jest autoryzowany do łączenia się z koncentratorem. |
Transports |
Wszystkie transporty są włączone. | Bit flaguje wyliczenie HttpTransportType wartości, które mogą ograniczyć transporty, których klient może użyć do nawiązania połączenia. |
LongPolling |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu długiego sondowania. |
WebSockets |
Zobacz poniżej. | Dodatkowe opcje specyficzne dla transportu obiektów WebSocket. |
MinimumProtocolVersion |
0 | Określ minimalną wersję protokołu negocjowania. Służy to do ograniczania klientów do nowszych wersji. |
CloseOnAuthenticationExpiration |
fałsz | Ustaw tę opcję, aby włączyć śledzenie wygasania uwierzytelniania, które spowoduje zamknięcie połączeń po wygaśnięciu tokenu. |
Transport Long Polling ma dodatkowe opcje, które można skonfigurować przy użyciu LongPolling
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
PollTimeout |
90 sekund | Maksymalny czas oczekiwania serwera na wysłanie komunikatu do klienta przed zakończeniem pojedynczego żądania sondowania. Zmniejszenie tej wartości powoduje, że klient częściej wysyła nowe żądania sondowania. |
Transport protokołu WebSocket ma dodatkowe opcje, które można skonfigurować przy użyciu WebSockets
właściwości :
Opcja | Wartość domyślna | opis |
---|---|---|
CloseTimeout |
5 s | Po zamknięciu serwera, jeśli klient nie może zamknąć w tym przedziale czasu, połączenie zostanie zakończone. |
SubProtocolSelector |
null |
Delegat, który może służyć do ustawiania nagłówka Sec-WebSocket-Protocol na wartość niestandardową. Delegat odbiera wartości żądane przez klienta jako dane wejściowe i oczekuje się, że zwróci żądaną wartość. |
Konfigurowanie opcji klienta
Opcje klienta można skonfigurować na typie HubConnectionBuilder
(dostępnym na klientach .NET i JavaScript). Jest ona również dostępna w kliencie Java, ale podklasa HttpHubConnectionBuilder
zawiera opcje konfiguracji konstruktora, a także na HubConnection
samym kliencie.
Konfigurowanie rejestrowania
Rejestrowanie jest konfigurowane w kliencie .NET przy użyciu ConfigureLogging
metody . Dostawcy rejestrowania i filtry można zarejestrować w taki sam sposób, jak na serwerze. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rejestrowania w usłudze ASP.NET Core .
Uwaga
Aby zarejestrować dostawców rejestrowania, należy zainstalować niezbędne pakiety. Aby uzyskać pełną listę, zobacz sekcję Wbudowane dostawcy rejestrowania w dokumentacji.
Aby na przykład włączyć rejestrowanie konsoli, zainstaluj Microsoft.Extensions.Logging.Console
pakiet NuGet. Wywołaj metodę AddConsole
rozszerzenia:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.Build();
W kliencie JavaScript istnieje podobna configureLogging
metoda. Podaj wartość wskazującą LogLevel
minimalny poziom komunikatów dziennika do utworzenia. Dzienniki są zapisywane w oknie konsoli przeglądarki.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging(signalR.LogLevel.Information)
.build();
LogLevel
Zamiast wartości można również podać string
wartość reprezentującą nazwę poziomu dziennika. Jest to przydatne podczas konfigurowania SignalR rejestrowania w środowiskach, w których nie masz dostępu do LogLevel
stałych.
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub")
.configureLogging("warn")
.build();
W poniższej tabeli wymieniono dostępne poziomy dziennika. Wartość, którą podajesz, ustawia configureLogging
minimalny poziom dziennika, który zostanie zarejestrowany. Komunikaty zarejestrowane na tym poziomie lub poziomy wymienione po niej w tabeli zostaną zarejestrowane.
String | PoziomRejestrowania |
---|---|
trace |
LogLevel.Trace |
debug |
LogLevel.Debug |
info lub information |
LogLevel.Information |
warn lub warning |
LogLevel.Warning |
error |
LogLevel.Error |
critical |
LogLevel.Critical |
none |
LogLevel.None |
Uwaga
Aby całkowicie wyłączyć rejestrowanie, określ signalR.LogLevel.None
metodę configureLogging
.
Aby uzyskać więcej informacji na temat rejestrowania, zobacz dokumentację SignalRdiagnostyki.
Klient SignalR Java używa biblioteki SLF4J do rejestrowania. Jest to interfejs API rejestrowania wysokiego poziomu, który umożliwia użytkownikom biblioteki wybranie własnej implementacji rejestrowania przez wprowadzenie określonej zależności rejestrowania. Poniższy fragment kodu pokazuje, jak używać go java.util.logging
z klientem SignalR Java.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Jeśli nie skonfigurujesz rejestrowania w zależnościach, SLF4J ładuje domyślny rejestrator bez operacji z następującym komunikatem ostrzegawczym:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Można to bezpiecznie zignorować.
Konfigurowanie dozwolonych transportów
Transporty używane przez SignalR program można skonfigurować w wywołaniu WithUrl
(withUrl
w języku JavaScript). Bitowe or wartości parametru HttpTransportType
można użyć do ograniczenia klienta do używania tylko określonych transportów. Wszystkie transporty są domyślnie włączone.
Na przykład aby wyłączyć transport zdarzeń wysłanych przez serwer, ale zezwalać na połączenia WebSocket i Long Polling:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
W kliencie języka JavaScript transporty są konfigurowane przez ustawienie transport
pola w obiekcie options udostępnionym na wartość withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
.build();
W tej wersji obiektów websocket klienta Java jest jedynym dostępnym transportem.
W kliencie Java transport jest wybierany przy użyciu withTransport
metody w pliku HttpHubConnectionBuilder
. Klient Języka Java domyślnie używa transportu obiektów WebSocket.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withTransport(TransportEnum.WEBSOCKETS)
.build();
Uwaga
Klient SignalR java nie obsługuje jeszcze powrotu transportu.
Konfigurowanie uwierzytelniania elementu nośnego
Aby udostępnić dane uwierzytelniania wraz z żądaniami SignalR , użyj AccessTokenProvider
opcji (accessTokenFactory
w języku JavaScript), aby określić funkcję zwracającą żądany token dostępu. W kliencie platformy .NET ten token dostępu jest przekazywany jako token HTTP "Uwierzytelnianie elementu nośnego" (przy użyciu Authorization
nagłówka o typie Bearer
). W kliencie JavaScript token dostępu jest używany jako token elementu nośnego, z wyjątkiem kilku przypadków, w których interfejsy API przeglądarki ograniczają możliwość stosowania nagłówków (w szczególności w żądaniach zdarzeń wysłanych przez serwer i obiektów WebSocket). W takich przypadkach token dostępu jest udostępniany jako wartość access_token
ciągu zapytania .
W kliencie AccessTokenProvider
platformy .NET można określić opcję przy użyciu delegata opcji w programie WithUrl
:
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
W kliencie JavaScript token dostępu jest konfigurowany przez ustawienie accessTokenFactory
pola w obiekcie options w withUrl
pliku :
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
W kliencie SignalR języka Java można skonfigurować token elementu nośnego do użycia do uwierzytelniania, zapewniając fabrykę tokenów dostępu do programu HttpHubConnectionBuilder. Użyj funkcji withAccessTokenFactory, aby udostępnić pojedynczy <ciąg> RxJava. Wywołanie metody Single.defer umożliwia napisanie logiki w celu utworzenia tokenów dostępu dla klienta.
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();
Konfigurowanie limitu czasu i opcji zachowania aktywności
Dodatkowe opcje konfigurowania limitu czasu i zachowania utrzymania aktywności są dostępne w HubConnection
samym obiekcie:
Opcja | Wartość domyślna | opis |
---|---|---|
ServerTimeout |
30 sekund (30 000 milisekund) | Limit czasu działania serwera. Jeśli serwer nie wysłał komunikatu w tym interwale, klient uzna serwer za odłączony i wyzwoli Closed zdarzenie (onclose w języku JavaScript). Ta wartość musi być wystarczająco duża, aby wiadomość ping została wysłana z serwera i odebrana przez klienta w przedziale czasu. Zalecana wartość jest liczbą co najmniej dwukrotnie większą niż wartość serwera KeepAliveInterval , aby umożliwić odebranie poleceń ping. |
HandshakeTimeout |
15 sekund | Limit czasu początkowego uzgadniania serwera. Jeśli serwer nie wysyła odpowiedzi uzgadniania w tym interwale, klient anuluje uzgadnianie i wyzwala Closed zdarzenie (onclose w języku JavaScript). Jest to zaawansowane ustawienie, które powinno być modyfikowane tylko wtedy, gdy występują błędy przekroczenia limitu czasu uzgadniania z powodu poważnych opóźnień sieci. Aby uzyskać więcej informacji na temat procesu uzgadniania, zobacz SignalR Specyfikacja protokołu koncentratora. |
KeepAliveInterval |
15 sekund | Określa interwał wysyłania komunikatów ping przez klienta. Wysłanie dowolnego komunikatu z klienta spowoduje zresetowanie czasomierza do początku interwału. Jeśli klient nie wysłał komunikatu w ClientTimeoutInterval zestawie na serwerze, serwer uzna klienta za odłączonego. |
W kliencie .NET wartości limitu czasu są określane jako TimeSpan
wartości.
Konfigurowanie dodatkowych opcji
Dodatkowe opcje można skonfigurować w metodzie WithUrl
(withUrl
w języku JavaScript) w systemie HubConnectionBuilder
lub w różnych interfejsach API konfiguracji w kliencie HttpHubConnectionBuilder
Java:
Opcja platformy .NET | Wartość domyślna | opis |
---|---|---|
AccessTokenProvider |
null |
Funkcja zwracająca ciąg, który jest dostarczany jako token uwierzytelniania elementu nośnego w żądaniach HTTP. |
SkipNegotiation |
false |
Ustaw tę opcję, aby true pominąć krok negocjacji. Obsługiwane tylko wtedy, gdy transport obiektów WebSockets jest jedynym włączonym transportem. Nie można włączyć tego ustawienia w przypadku korzystania z usługi platformy Azure SignalR . |
ClientCertificates |
Pusty | Kolekcja certyfikatów TLS do wysyłania do uwierzytelniania żądań. |
Cookies |
Pusty | Kolekcja żądań HTTP cookiedo wysłania przy użyciu każdego żądania HTTP. |
Credentials |
Pusty | Poświadczenia do wysłania przy użyciu każdego żądania HTTP. |
CloseTimeout |
5 s | Tylko obiekty WebSocket. Maksymalny czas oczekiwania klienta po zamknięciu serwera w celu potwierdzenia zamknięcia żądania zamknięcia. Jeśli serwer nie potwierdzi zamknięcia w tym czasie, klient rozłącza się. |
Headers |
Pusty | Mapa dodatkowych nagłówków HTTP do wysłania przy użyciu każdego żądania HTTP. |
HttpMessageHandlerFactory |
null |
Pełnomocnik, który może służyć do konfigurowania lub zastępowania używanego HttpMessageHandler do wysyłania żądań HTTP. Nie jest używany w przypadku połączeń protokołu WebSocket. Ten delegat musi zwrócić wartość inną niż null i otrzymuje wartość domyślną jako parametr. Zmodyfikuj ustawienia dla tej wartości domyślnej i zwróć je lub zwróć nowe HttpMessageHandler wystąpienie. Podczas zastępowania programu obsługi pamiętaj, aby skopiować ustawienia, które chcesz zachować z dostarczonej procedury obsługi, w przeciwnym razie skonfigurowane opcje (takie jak Cookies i Nagłówki) nie będą stosowane do nowej procedury obsługi. |
Proxy |
null |
Serwer proxy HTTP do użycia podczas wysyłania żądań HTTP. |
UseDefaultCredentials |
false |
Ustaw tę wartość logiczną, aby wysyłać domyślne poświadczenia dla żądań HTTP i WebSocket. Umożliwia to korzystanie z uwierzytelniania systemu Windows. |
WebSocketConfiguration |
null |
Delegat, który może służyć do konfigurowania dodatkowych opcji protokołu WebSocket. Odbiera wystąpienie ClientWebSocketOptions , którego można użyć do skonfigurowania opcji. |
ApplicationMaxBufferSize |
1 MB | Maksymalna liczba bajtów odebranych z serwera buforowanych przez klienta przed zastosowaniem funkcji backpressure. Zwiększenie tej wartości umożliwia klientowi szybsze odbieranie większych komunikatów bez stosowania funkcji backpressure, ale może zwiększyć zużycie pamięci. |
TransportMaxBufferSize |
1 MB | Maksymalna liczba bajtów wysyłanych przez aplikację użytkownika buforowanych przez klienta przed zaobserwowaniem backpressure. Zwiększenie tej wartości umożliwia klientowi szybsze buforowanie większych komunikatów bez oczekiwania na tłumienie wsteczne, ale może zwiększyć zużycie pamięci. |
W kliencie platformy .NET te opcje można modyfikować za pomocą delegata opcji dostarczonych do WithUrl
programu :
var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/chathub", options => {
options.Headers["Foo"] = "Bar";
options.SkipNegotiation = true;
options.Transports = HttpTransportType.WebSockets;
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
W kliencie Języka JavaScript te opcje można podać w obiekcie JavaScript udostępnionym użytkownikowi withUrl
:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/chathub", {
// "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
headers: { "Foo": "Bar" },
transport: signalR.HttpTransportType.LongPolling
})
.build();
W kliencie Języka Java te opcje można skonfigurować przy użyciu metod zwróconych HttpHubConnectionBuilder
z obiektu HubConnectionBuilder.create("HUB URL")
HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();
Dodatkowe zasoby
- Wprowadzenie do platformy ASP.NET Core SignalR
- Używanie koncentratorów w technologii ASP.NET Core SignalR
- ASP.NET Core SignalR JavaScript client
- klient platformy .NET platformy ASP.NET Core SignalR
- Używanie protokołu MessagePack Hub w programie SignalR dla platformy ASP.NET Core
- platformy obsługiwane przez platformy ASP.NET Core SignalR