Opzioni di configurazione QUIC

La System.Net.Quic libreria usa classi di opzioni per configurare gli oggetti protocollo (QuicListener e QuicConnection) prima della costruzione e dell'inizializzazione. A tale scopo sono disponibili tre diverse classi di opzioni:

Tutte le classi di opzioni possono essere configurate in modo incrementale, ovvero non richiedono l'inizializzazione di alcuna delle relative proprietà tramite il costruttore e possono essere configurate in modo indipendente. Tuttavia, quando vengono usati per configurare un nuovo listener o una connessione, le opzioni vengono convalidate e viene generato un tipo appropriato di ArgumentException per eventuali valori obbligatori mancanti o non configurati correttamente. Ad esempio, se QuicConnectionOptions.DefaultStreamErrorCode obbligatorio non è impostato, la chiamata ConnectAsync(QuicClientConnectionOptions, CancellationToken) genera ArgumentOutOfRangeException.

QuicListenerOptions

QuicListenerOptions vengono usati in QuicListener.ListenAsync(QuicListenerOptions, CancellationToken) quando si avvia un nuovo QuicListener. Le singole proprietà di configurazione sono:

Protocolli di Applicazione

ApplicationProtocols definire i protocolli dell'applicazione accettati dal server (RFC 7301 - ALPN). Può contenere più valori per protocolli diversi che possono non essere correlati. Nel processo di accettazione di una nuova connessione, il listener può restringere o selezionare un protocollo specifico per ogni connessione in ingresso, vedere QuicListenerOptions.ConnectionOptionsCallback. Questa proprietà è obbligatoria e deve contenere almeno un valore.

Callback delle Opzioni di Connessione

ConnectionOptionsCallback è un delegato da utilizzare per scegliere QuicServerConnectionOptions per una connessione in ingresso. Alla funzione viene assegnata un'istanza parzialmente inizializzata di QuicConnection e SslClientHelloInfo contenente il nome del server richiesto dal client (RFC 6066 - SNI). Il delegato viene richiamato per ogni connessione in ingresso. Può restituire opzioni diverse in base alle informazioni sul client fornite oppure può restituire in modo sicuro la stessa istanza delle opzioni ogni volta. Lo scopo e la forma del delegato sono intenzionalmente simili a ServerOptionsSelectionCallback usato in SslStream.AuthenticateAsServerAsync(ServerOptionsSelectionCallback, Object, CancellationToken). Questa proprietà è obbligatoria.

ListenBacklog

ListenBacklog determina il numero di connessioni in ingresso che possono essere mantenute dal listener prima che vengano rifiutate altre connessioni. Ogni tentativo di stabilire una connessione conta, anche quando fallisce o quando la connessione viene interrotta mentre si attende in coda. Anche i processi in corso per stabilire una nuova connessione contribuiscono a questo limite. Le connessioni o i tentativi di connessione vengono conteggiati fino a quando non vengono recuperati tramite QuicListener.AcceptConnectionAsync(CancellationToken). Lo scopo del limite di backlog è impedire che i server vengano sovraccaricati da più connessioni in ingresso rispetto a quelle che possono elaborare. Questa proprietà è facoltativa, il valore predefinito è 512.

Punto di ascolto (ListenEndPoint)

ListenEndPoint contiene l'indirizzo IP e la porta in cui il listener accetterà nuove connessioni. A causa dell'implementazione sottostante, MsQuic, il listener viene sempre associato a un socket dual stack con caratteri universali, indipendentemente da ciò che viene specificato qui. Ciò può causare alcuni comportamenti imprevisti, in particolare rispetto ai normali socket TCP, come in casi HTTP/1.1 e HTTP/2. Per altre informazioni, vedere Guida alla risoluzione dei problemi di QUIC. Questa proprietà è obbligatoria.

QuicConnectionOptions

QuicConnectionOptions le opzioni vengono condivise tra QuicClientConnectionOptions e QuicServerConnectionOptions. Si tratta di una classe di base astratta e non può essere usata autonomamente. Contiene queste proprietà:

CodiceErroreChiusuraPredefinita

DefaultCloseErrorCode viene utilizzato quando la connessione viene eliminata senza chiamare QuicConnection.CloseAsync(Int64, CancellationToken). È richiesto dal protocollo QUIC per fornire un motivo a livello di applicazione per la chiusura di una connessione (RFC 9000 - Chiusura connessione). QuicConnection non ha modo di forzare il codice dell'applicazione a chiamare CloseAsync(Int64, CancellationToken) prima di eliminare la connessione. In tal caso, la connessione deve conoscere il codice di errore da usare. Questa proprietà è obbligatoria.

DefaultStreamErrorCode

DefaultStreamErrorCode viene usato quando un flusso viene eliminato prima che tutti i dati vengano letti. Quando si ricevono dati tramite il flusso QUIC, un'applicazione può utilizzare tutti i dati o, in caso contrario, deve interrompere il lato di lettura. Analogamente alla chiusura della connessione, il protocollo QUIC richiede un motivo a livello di applicazione per interrompere il lato lettura (RFC 9000 - Interrompi invio). Questa proprietà è obbligatoria.

HandshakeTimeout

HandshakeTimeout imposta il limite di tempo in cui la connessione deve essere stabilita completamente; in caso contrario, viene interrotto. È possibile impostare questo valore su InfiniteTimeSpan ma è sconsigliato. I tentativi di connessione potrebbero bloccarsi per un periodo illimitato e non è possibile cancellarli, a parte l'arresto di QuicListener. Questa proprietà è facoltativa, il valore predefinito è 10 secondi.

IdleTimeout

Se la connessione è inattiva per più del tempo specificato IdleTimeout, essa viene disconnessa. Questa opzione fa parte della specifica del protocollo QUIC (RFC 9000 - Timeout di inattività) e viene inviata al peer durante l'handshake della connessione. La connessione sceglie quindi il valore più piccolo tra il proprio e il timeout di inattività del peer e lo utilizza. Di conseguenza, la connessione può essere chiusa per inattività prima del tempo previsto dall'opzione impostata. Questa proprietà è facoltativa, il valore predefinito è basato su MsQuic, ovvero 30 secondi.

DimensioniInizialiFinestraRicezione

InitialReceiveWindowSizes specifica un set di valori che limita la quantità di dati, inizialmente, che può essere ricevuta dalla connessione e/o dal flusso. Il protocollo QUIC definisce un meccanismo per limitare la quantità di dati che è possibile inviare sui singoli flussi e cumulativamente per l'intera connessione (RFC 9000 - Controllo del flusso di dati). Questi limiti si applicano solo prima che l'applicazione inizi a utilizzare i dati. Successivamente, MsQuic regola continuamente le dimensioni della finestra di ricezione in base alla velocità con cui l'applicazione le legge. Questa proprietà è di QuicReceiveWindowSizes tipo , che contiene queste opzioni:

Questi valori devono essere un numero intero non negativo che rappresenta una potenza pari a 2; si tratta di una limitazione ereditata da MsQuic. L'impostazione di uno di questi valori su 0 significa essenzialmente che nessun dato verrà mai ricevuto dal flusso specifico o da una connessione nel suo complesso. Questa proprietà è facoltativa, i valori predefiniti sono 64 KB per un flusso e 64 MB per una connessione.

KeepAliveInterval

KeepAliveInterval determina se e con quale frequenza vengono inviati fotogrammi PING per mantenere attiva la connessione e impedirne la chiusura IdleTimeout (RFC 9000 - PING Frame). Nel caso in cui si imposti questa proprietà, prendere in considerazione la raccomandazione di RFC 9000 - rinviare il timeout di inattività. L'impostazione del valore troppo basso potrebbe influire negativamente sulle prestazioni. Inoltre, l'impostazione della proprietà troppo vicina al timeout di inattività potrebbe comunque causare la chiusura della connessione. Questa proprietà è facoltativa, il valore predefinito significa InfiniteTimeSpan che non verrà inviato alcun PING.

Numero massimo di flussi bidirezionali in entrata

MaxInboundBidirectionalStreams determina il numero massimo di flussi bidirezionali attivi simultaneamente che la connessione è disposta ad accettare. Si noti che ciò differisce dal modo in cui la specifica QUIC definisce la gestione della concorrenza (RFC 9000 - Controllo della concorrenza). Il protocollo QUIC conta i flussi cumulativamente, per tutta la durata della connessione e usa un limite sempre crescente per determinare il numero complessivo di flussi accettati dalla connessione, inclusi i flussi già chiusi (RFC 9000 - frame MAX_STREAMS). Questa proprietà semplifica questa operazione in modo che l'applicazione specifichi solo il limite di flusso simultaneo e MsQuic si occupi della conversione di questo limite ai fotogrammi corrispondenti MAX_STREAMS . Questa proprietà è facoltativa, il valore predefinito è 0 per le connessioni client e 100 per le connessioni server.

MaxInboundUnidirectionalStreams

MaxInboundUnidirectionalStreams determina il numero massimo di flussi unidirezionali attivi simultaneamente che la connessione è disposta ad accettare. Si noti che ciò differisce dal modo in cui la specifica QUIC definisce la concorrenza del flusso di gestione (RFC 9000 - Controllo della concorrenza). Il protocollo QUIC conta i flussi cumulativamente, per tutta la durata della connessione e usa un limite sempre crescente per determinare il numero complessivo di flussi accettati dalla connessione, inclusi i flussi già chiusi (RFC 9000 - frame MAX_STREAMS). Questa proprietà semplifica questa operazione in modo che l'applicazione specifichi solo il limite di flusso simultaneo e MsQuic si occupi della conversione di questo limite ai fotogrammi corrispondenti MAX_STREAMS . Questa proprietà è facoltativa, il valore predefinito è 0 per le connessioni client e 10 per le connessioni server.

StreamCapacityCallback

StreamCapacityCallback è un callback richiamato ogni volta che il peer rilascia una nuova capacità di flusso tramite MAX_STREAMS e, di conseguenza, la capacità corrente è superiore a 0. I valori specificati negli argomenti di callback sono incrementi di capacità, ovvero la somma di tutti i valori del callback sarà uguale all'ultimo valore ricevuto da MAX_STREAMS (RFC 9000 - MAX_STREAMS Frame). Questo callback è stato progettato per supportare SocketsHttpHandler.EnableMultipleHttp3Connections le funzionalità e include diverse avvertenze:

  • Spetta all'applicazione tenere traccia di tutti i flussi in apertura e aperti per conoscere la capacità effettiva in ogni momento.
  • Il callback potrebbe essere chiamato in parallelo, quindi spetta all'applicazione gestire correttamente la sincronizzazione intorno al conteggio dei flussi.
  • La prima invocazione (con la capacità iniziale) potrebbe avvenire prima che l'istanza venga concessa tramite QuicConnection o QuicConnection.ConnectAsync(QuicClientConnectionOptions, CancellationToken).

Lo scenario semplificato seguente acquisisce il comportamento dell'apertura del flusso e del callback:

  1. Il client avvia la connessione al server tramite:

    var client = await QuicConnection.ConnectAsync(new QuicClientConnectionOptions
{
    ...
    StreamCapacityCallback = (connection, args) =>
        Console.WriteLine($"{connection} stream capacity increased by: unidi += {args.UnidirectionalIncrement}, bidi += {args.BidirectionalIncrement}")
};

  2. Il server invia le impostazioni iniziali al client con il limite 2 di flusso per i flussi unidirezionali e 0 bidirezionale.

  3. Il client StreamCapacityCallback viene chiamato e stampa:

    [conn][0x58575BF805B0] stream capacity increased by: unidi += 2, bidi += 0

  4. La chiamata client a ConnectAsync risponde con la connessione [conn][0x58575BF805B0].

  5. Il client tenta di aprire alcuni stream:

    var stream1 = await connection.OpenOutboundStreamAsync(QuicStreamType.Unidirectional);
var stream2 = await connection.OpenOutboundStreamAsync(QuicStreamType.Unidirectional);
// The following call will get suspended because the stream's limit has been reached.
var taskStream3 = connection.OpenOutboundStreamAsync(QuicStreamType.Unidirectional);

  6. Il client termina e chiude i primi due flussi:

    await stream1.WriteAsync(data, completeWrites: true);
await stream1.DisposeAsync();
await stream2.WriteAsync(data, completeWrites: true);
await stream2.DisposeAsync();
Console.WriteLine($"Stream 3 {(taskStream3.IsCompleted ? "opened" : "pending")}");

  7. Il client stampa:

    Stream 3 pending

  8. Il server rilascia capacità aggiuntiva di 2 dopo l'elaborazione dei primi due flussi.

  9. Due cose accadono sul client. Innanzitutto, viene aperto un terzo flusso:

    var stream3 = await taskStream3;

    Quindi, il client StreamCapacityCallback viene chiamato di nuovo e stampa:

    [conn][0x58575BF805B0] stream capacity increased by: unidi += 2, bidi += 0

Questa proprietà è facoltativa.

QuicServerConnectionOptions

QuicServerConnectionOptions le opzioni sono specifiche per una connessione lato server. Oltre alle proprietà ereditate da QuicConnectionOptions, contiene quanto segue:

Opzioni di Autenticazione del Server

ServerAuthenticationOptions contiene le impostazioni TLS per la connessione al server. Le opzioni sono le stesse usate in SslStream.AuthenticateAsServer(SslServerAuthenticationOptions) e SslStream.AuthenticateAsServerAsync(SslServerAuthenticationOptions, CancellationToken). Per il server QUIC, SslServerAuthenticationOptions è valido se:

Questa proprietà è obbligatoria e deve soddisfare le condizioni elencate.

QuicClientConnectionOptions

QuicClientConnectionOptions le opzioni sono specifiche di una connessione lato client. Oltre alle proprietà ereditate da QuicConnectionOptions, contiene quanto segue:

Opzioni di Autenticazione Client

ClientAuthenticationOptions contiene l'impostazione TLS per la connessione client. Le opzioni sono le stesse usate in SslStream.AuthenticateAsClient(SslClientAuthenticationOptions) e SslStream.AuthenticateAsClientAsync(SslClientAuthenticationOptions, CancellationToken). Per il client QUIC, SslClientAuthenticationOptions è valido se:

Questa proprietà è obbligatoria e deve soddisfare le condizioni elencate.

LocalEndPoint

LocalEndPoint contiene l'indirizzo IP e la porta a cui verrà associata la connessione client. Se non specificato, il sistema operativo assegna un indirizzo IP e una porta. Questa proprietà è facoltativa.

Punto finale remoto

RemoteEndPoint può essere DnsEndPoint o IPEndPoint del peer a cui viene stabilita la connessione. Se si tratta di un DnsEndPoint, viene usato il primo indirizzo IP restituito da Dns.GetHostAddressesAsync(String, CancellationToken) . Questa proprietà è obbligatoria.

  • Last updated on