gRPC für .NET-Konfiguration

Artikel
11/06/2024

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der Supportrichtlinie für .NET und .NET Core. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Konfigurieren von Dienstoptionen

gRPC-Dienste werden mit AddGrpc in Startup.cs konfiguriert. Konfigurationsoptionen befinden sich im Grpc.AspNetCore.Server-Paket.

In der folgenden Tabelle werden die Optionen für die Konfiguration von gRPC-Diensten beschrieben:

Option	Standardwert	Beschreibung
`MaxSendMessageSize`	`null`	Die maximale Nachrichtengröße in Bytes, die vom Server gesendet werden kann. Der Versuch, eine Nachricht zu senden, die die konfigurierte maximale Nachrichtengröße überschreitet, führt zu einer Ausnahme. Wenn dieser Wert auf `null` festgelegt wird, ist die Größe der Nachricht unbegrenzt.
`MaxReceiveMessageSize`	4 MB	Die maximale Nachrichtengröße in Bytes, die vom Server empfangen werden kann. Wenn der Server eine Nachricht erhält, die diesen Grenzwert überschreitet, wird eine Ausnahme ausgelöst. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten zu empfangen, kann sich jedoch negativ auf den Arbeitsspeicherverbrauch auswirken. Wenn dieser Wert auf `null` festgelegt wird, ist die Größe der Nachricht unbegrenzt.
`EnableDetailedErrors`	`false`	Bei `true` werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Dienstmethode ausgelöst wird. Der Standardwert ist `false`. Das Festlegen von `EnableDetailedErrors` auf `true` kann zum Verlust von vertraulichen Informationen führen.
`CompressionProviders`	gzip	Eine Sammlung von Komprimierungsanbietern, die zum Komprimieren und Dekomprimieren von Nachrichten verwendet werden. Es können benutzerdefinierte Komprimierungsanbieter erstellt und der Sammlung hinzugefügt werden. Die standardmäßig konfigurierten Anbieter unterstützen die gzip-Komprimierung.
`ResponseCompressionAlgorithm`	`null`	Der Komprimierungsalgorithmus, der zur Komprimierung der vom Server gesendeten Nachrichten verwendet wird. Der Algorithmus muss mit einem Komprimierungsanbieter in `CompressionProviders` übereinstimmen. Damit der Algorithmus eine Antwort komprimieren kann, muss der Client angeben, dass er den Algorithmus unterstützt, indem er ihn im grpc-accept-encoding-Header sendet.
`ResponseCompressionLevel`	`null`	Die Komprimierungsstufe, die zur Komprimierung der vom Server gesendeten Nachrichten verwendet wird.
`Interceptors`	Keine	Eine Sammlung von Interceptors, die bei jedem gRPC-Aufruf ausgeführt werden. Interceptors werden in der Reihenfolge ausgeführt, in der sie registriert sind. Global konfigurierte Interceptors werden vor Interceptors ausgeführt, die für einen einzelnen Dienst konfiguriert sind. Ein Interceptor ist standardmäßig auf die Lebensdauer einer Anforderung beschränkt. Der Interceptorkonstruktor wird aufgerufen, und Parameter werden über die Abhängigkeitsinjektion (Dependency Injection, DI) aufgelöst. Ein Interceptortyp kann auch per DI registriert werden, um die Art der Erstellung und seine Lebensdauer zu überschreiben. Ein Interceptor bieten ähnliche Funktionen wie ASP.NET Core-Middleware. Weitere Informationen finden Sie unter Gegenüberstellung: gRPC-Interceptors und Middleware.
`IgnoreUnknownServices`	`false`	Bei `true` geben Aufrufe unbekannter Dienste und Methoden nicht den Status `true` zurück, und die Anforderung wird an die nächste registrierte Middleware in ASP.NET Core übergeben.

Optionen können für alle Dienste konfiguriert werden, indem ein Optionsdelegat für den AddGrpc-Aufruf in Startup.ConfigureServices bereitgestellt wird:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc(options =>
    {
        options.EnableDetailedErrors = true;
        options.MaxReceiveMessageSize = 2 * 1024 * 1024; // 2 MB
        options.MaxSendMessageSize = 5 * 1024 * 1024; // 5 MB
    });
}

Optionen für einen einzelnen Dienst haben Vorrang vor den globalen Optionen in AddGrpc und können mit AddServiceOptions<TService> konfiguriert werden:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc().AddServiceOptions<MyService>(options =>
    {
        options.MaxReceiveMessageSize = 2 * 1024 * 1024; // 2 MB
        options.MaxSendMessageSize = 5 * 1024 * 1024; // 5 MB
    });
}

Ein Dienstinterceptor ist standardmäßig auf die Lebensdauer einer Anforderung beschränkt. Durch das Registrieren des Interceptortyp per DI kann die Art der Erstellung und seine Lebensdauer überschrieben werden.

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc(options =>
    {
        options.Interceptors.Add<LoggingInterceptor>();
    });
    services.AddSingleton<LoggingInterceptor>();
}

ASP.NET Core-Serveroptionen

Grpc.AspNetCore.Server wird von einem ASP.NET Core-Webserver gehostet. Es gibt eine Reihe von Optionen für ASP.NET Core-Server, einschließlich Kestrel, IIS und HTTP.sys. Jeder Server bietet zusätzliche Optionen für die Verarbeitung von HTTP-Anforderungen.

Der von einer ASP.NET Core-App verwendete Server wird im App-Startcode konfiguriert. Der Standardserver ist Kestrel.

Weitere Informationen zu den verschiedenen Servern und ihren Konfigurationsoptionen finden Sie unter:

Konfigurieren von Clientoptionen

Die gRPC-Clientkonfiguration ist auf GrpcChannelOptions festgelegt. Konfigurationsoptionen befinden sich im Grpc.Net.Client-Paket.

In der folgenden Tabelle werden die Optionen für die Konfiguration von gRPC-Kanälen beschrieben:

Option	Standardwert	Beschreibung
`HttpHandler`	Neue Instanz	Der `HttpMessageHandler` wird für gRPC-Aufrufe verwendet. Ein Client kann so eingestellt werden, dass er einen benutzerdefinierten `HttpClientHandler` konfiguriert oder der HTTP-Pipeline zusätzliche Handler für gRPC-Aufrufe hinzufügt. Wenn kein `HttpMessageHandler` angegeben ist, wird eine neue `HttpClientHandler`-Instanz für den Kanal mit automatischer Entfernung erstellt.
`HttpClient`	`null`	Der `HttpClient` wird für gRPC-Aufrufe verwendet. Diese Einstellung ist eine Alternative zum `HttpHandler`.
`DisposeHttpClient`	`false`	Wenn diese Option auf `true` festgelegt und ein `HttpMessageHandler` oder `HttpClient` angegeben ist, wird entweder der `HttpHandler` oder `HttpClient` entfernt, wenn der `GrpcChannel` entfernt wird.
`LoggerFactory`	`null`	Die `LoggerFactory`, die vom Client zur Protokollierung von Informationen über gRPC-Aufrufe verwendet wird. Eine `LoggerFactory`-Instanz kann aus der Abhängigkeitsinjektion aufgelöst oder mit `LoggerFactory.Create` erstellt werden. Beispiele zum Konfigurieren der Protokollierung finden Sie unter Protokollierung und Diagnosen in gRPC für .NET.
`MaxSendMessageSize`	`null`	Die maximale Nachrichtengröße in Bytes, die vom Client gesendet werden kann. Der Versuch, eine Nachricht zu senden, die die konfigurierte maximale Nachrichtengröße überschreitet, führt zu einer Ausnahme. Wenn dieser Wert auf `null` festgelegt wird, ist die Größe der Nachricht unbegrenzt.
`MaxReceiveMessageSize`	4 MB	Die maximale Nachrichtengröße in Bytes, die vom Client empfangen werden kann. Wenn der Client eine Nachricht erhält, die diesen Grenzwert überschreitet, wird eine Ausnahme ausgelöst. Eine Erhöhung dieses Werts ermöglicht es dem Client, größere Nachrichten zu empfangen, kann sich jedoch negativ auf den Arbeitsspeicherverbrauch auswirken. Wenn dieser Wert auf `null` festgelegt wird, ist die Größe der Nachricht unbegrenzt.
`Credentials`	`null`	Eine `ChannelCredentials`-Instanz. Anmeldeinformationen werden verwendet, um Authentifizierungsmetadaten zu gRPC-Aufrufen hinzuzufügen.
`CompressionProviders`	gzip	Eine Sammlung von Komprimierungsanbietern, die zum Komprimieren und Dekomprimieren von Nachrichten verwendet werden. Es können benutzerdefinierte Komprimierungsanbieter erstellt und der Sammlung hinzugefügt werden. Die standardmäßig konfigurierten Anbieter unterstützen die gzip-Komprimierung.
`ThrowOperationCanceledOnCancellation`	`false`	Wenn dieser Wert auf `true` festgelegt ist, wird OperationCanceledException ausgelöst, wenn ein Aufruf abgebrochen oder seine Frist überschritten wird.
`UnsafeUseInsecureChannelCallCredentials`	`false`	Wenn dieser Wert auf `true` festgelegt ist, werden `CallCredentials` auf gRPC-Anrufe von einem unsicheren Kanal angewendet. Das Senden von Authentifizierungsheadern über eine unsichere Verbindung hat Sicherheitsauswirkungen und sollte in Produktionsumgebungen vermieden werden.
`MaxRetryAttempts`	5	Die maximale Anzahl von Wiederholungsversuchen. Durch diesen Wert werden alle in der Dienstkonfiguration angegebenen Werte für Wiederholungs- und Hedgingversuche begrenzt. Wiederholungen lassen sich nicht allein durch Festlegen dieses Werts aktivieren. Wiederholungen werden in der Dienstkonfiguration aktiviert, die mithilfe von `ServiceConfig` vorgenommen werden kann. Mit dem Wert `null` wird das Limit für die maximale Anzahl der Wiederholungsversuche entfernt. Weitere Informationen zu Erneuten finden Sie unter Behandlung vorübergehender Fehler mit gRPC-Wiederholungen.
`MaxRetryBufferSize`	16 MB	Die maximale Größe des Puffers in Byte, der bei Wiederholungen oder Hedgingaufrufen zum Speichern von gesendeten Nachrichten verwendet werden kann. Wenn das Pufferlimit überschritten wird, werden keine Wiederholungsversuche mehr durchgeführt, und alle Hedgingaufrufe bis auf einen werden abgebrochen. Dieser Grenzwert gilt für alle Aufrufe, die über diesen Kanal erfolgen. Mit dem Wert `null` wird das Limit für die maximale Größe des Wiederholungspuffers entfernt.
`MaxRetryBufferPerCallSize`	1 MB	Die maximale Größe des Puffers in Byte, der bei Wiederholungen oder Hedgingaufrufen zum Speichern von gesendeten Nachrichten verwendet werden kann. Wenn das Pufferlimit überschritten wird, werden keine Wiederholungsversuche mehr durchgeführt, und alle Hedgingaufrufe bis auf einen werden abgebrochen. Dieser Grenzwert gilt für einen Aufruf. Mit dem Wert `null` wird das Limit für die maximale Größe des Wiederholungspuffers pro Aufruf entfernt.
`ServiceConfig`	`null`	Die Dienstkonfiguration für einen gRPC-Kanal. Eine Dienstkonfiguration kann verwendet werden, um gRPC-Wiederholungen zu konfigurieren.

Der folgende Code

Legt die maximale Größe der Nachricht zum Senden und Empfangen für den Kanal fest.
Erstellt einen Client.

static async Task Main(string[] args)
{
    var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions
    {
        MaxReceiveMessageSize = 5 * 1024 * 1024, // 5 MB
        MaxSendMessageSize = 2 * 1024 * 1024 // 2 MB
    });
    var client = new Greeter.GreeterClient(channel);

    var reply = await client.SayHelloAsync(
                      new HelloRequest { Name = "GreeterClient" });
    Console.WriteLine("Greeting: " + reply.Message);
}

Beachten Sie, dass ein Clientinterceptor nicht mit GrpcChannelOptions konfiguriert werden. Stattdessen wird ein Clientinterceptor unter Verwendung der Intercept-Erweiterungsmethode mit einem Kanal konfiguriert. Die Erweiterungsmethode ist im Grpc.Core.Interceptors-Namespace vorhanden.

static async Task Main(string[] args)
{
    var channel = GrpcChannel.ForAddress("https://localhost:5001");
    var callInvoker = channel.Intercept(new LoggingInterceptor());
    var client = new Greeter.GreeterClient(callInvoker);

    var reply = await client.SayHelloAsync(
                      new HelloRequest { Name = "GreeterClient" });
    Console.WriteLine("Greeting: " + reply.Message);
}

System.Net-Handleroptionen

Grpc.Net.Client verwendet einen von HttpMessageHandler abgeleiteten HTTP-Transport, um HTTP-Anforderungen zu erstellen. Jeder Handler bietet zusätzliche Optionen für die Erstellung von HTTP-Anforderungen.

Der Handler wird für einen Kanal konfiguriert und kann durch Festlegen von GrpcChannelOptions.HttpHandler überschrieben werden. .NET Core 3 und .NET 5 oder höher verwenden SocketsHttpHandler standardmäßig . gRPC-Client-Apps auf .NET Framework sollten WinHttpHandler konfigurieren.

Weitere Informationen zu den verschiedenen Handlern und ihren Konfigurationsoptionen finden Sie unter:

Freigeben über