Configuration de gRPC pour .NET

Article
11/30/2023

Configurer les options des services

Les services gRPC sont configurés avec AddGrpc dans Startup.cs. Les options de configuration se trouvent dans le package Grpc.AspNetCore.Server.

Le tableau suivant décrit les options de configuration des services gRPC :

Option	Valeur par défaut	Description
`MaxSendMessageSize`	`null`	Taille maximale des messages (en octets) pouvant être envoyés à partir du serveur. La tentative d’envoi d’un message qui dépasse la taille maximale configurée entraîne une exception. Lorsque la valeur est définie sur `null`, la taille du message est illimitée.
`MaxReceiveMessageSize`	4 Mo	Taille maximale du message en octets pouvant être reçue par le serveur. Si le serveur reçoit un message qui dépasse cette limite, il lève une exception. L’augmentation de cette valeur permet au serveur de recevoir des messages plus volumineux, mais peut avoir un impact négatif sur la consommation de mémoire. Lorsque la valeur est définie sur `null`, la taille du message est illimitée.
`EnableDetailedErrors`	`false`	Si `true`, des messages d’exception détaillés sont retournés aux clients lorsqu’une exception est levée dans une méthode de service. Par défaut, il s’agit de `false`. La définition de `EnableDetailedErrors` sur `true` peut faire fuiter des informations sensibles.
`CompressionProviders`	gzip	Une collection de fournisseurs de compression utilisés pour compresser et décompresser les messages. Des fournisseurs de compression personnalisés peuvent être créés et ajoutés à la collection. Les fournisseurs configurés par défaut prennent en charge la compression gzip.
`ResponseCompressionAlgorithm`	`null`	L’algorithme de compression utilisé pour compresser les messages envoyés à partir du serveur. L’algorithme doit correspondre à un fournisseur de compression dans `CompressionProviders`. Pour que l’algorithme compresse une réponse, le client doit indiquer qu’il prend en charge l’algorithme dans l’en-tête grpc-accept-encoding.
`ResponseCompressionLevel`	`null`	Le niveau de compression utilisé pour compresser les messages envoyés à partir du serveur.
`Interceptors`	Aucun	Une collection d’intercepteurs exécutés avec chaque appel gRPC. Les intercepteurs sont exécutés dans l’ordre dans lequel ils sont inscrits. Les intercepteurs globalement configurés sont exécutés avant les intercepteurs configurés pour un seul service. Les intercepteurs ont une durée de vie par requête par défaut. Le constructeur de l’intercepteur est appelé, et les paramètres sont résolus à partir de l’injection de dépendances (DI). Un type d’intercepteur peut également être inscrit auprès de la DI pour remplacer la façon dont il est créé et sa durée de vie. Les intercepteurs offrent des fonctionnalités similaires à celles des intergiciels ASP.NET Core. Pour plus d’informations, consultez Intercepteurs gRPC vs. Intergiciels (middleware).
`IgnoreUnknownServices`	`false`	Si `true`, les appels aux services et méthodes inconnus ne retournent pas d’état UNIMPLEMENTED, et la requête passe à l’intergiciel inscrit suivant dans ASP.NET Core.

Les options peuvent être configurées pour tous les services en fournissant un délégué d’options à l’appel AddGrpc dans Startup.ConfigureServices :

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
    });
}

Les options d’un service unique remplacent les options globales fournies dans AddGrpc et peuvent être configurées à l’aide de AddServiceOptions<TService> :

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

Les intercepteurs de service ont une durée de vie par requête par défaut. L’inscription du type d’intercepteur auprès de la DI remplace la façon dont un intercepteur est créé et sa durée de vie.

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

Options de serveur ASP.NET Core

Grpc.AspNetCore.Server est hébergé par un serveur web ASP.NET Core. Il existe un certain nombre d’options pour les serveurs ASP.NET Core, notamment Kestrel, IIS et HTTP.sys. Chaque serveur offre des options supplémentaires pour la façon dont les requêtes HTTP sont traitées.

Le serveur utilisé par une application ASP.NET Core est configuré dans le code de démarrage de l’application. Le serveur par défaut est Kestrel.

Pour plus d’informations sur les différents serveurs et leurs options de configuration, consultez :

Configurer les options du client

La configuration du client gRPC est définie sur GrpcChannelOptions. Les options de configuration se trouvent dans le package Grpc.Net.Client.

Le tableau suivant décrit les options de configuration des canaux gRPC :

Option	Valeur par défaut	Description
`HttpHandler`	Nouvelle instance	Le `HttpMessageHandler` utilisé pour effectuer des appels gRPC. Un client peut être défini pour configurer un `HttpClientHandler` personnalisé ou ajouter des gestionnaires supplémentaires au pipeline HTTP pour les appels gRPC. Si aucun `HttpMessageHandler` n’est spécifié, une nouvelle instance de `HttpClientHandler` est créée pour le canal avec suppression automatique.
`HttpClient`	`null`	Le `HttpClient` utilisé pour effectuer des appels gRPC. Ce paramètre est une alternative à `HttpHandler`.
`DisposeHttpClient`	`false`	Si la valeur est `true` et qu’un `HttpMessageHandler` ou `HttpClient` est spécifié, le `HttpHandler` ou le `HttpClient`, respectivement, est supprimé lorsque le `GrpcChannel` est supprimé.
`LoggerFactory`	`null`	La `LoggerFactory` utilisé par le client pour consigner les informations sur les appels gRPC. Une instance `LoggerFactory` peut être résolue à partir de l’injection de dépendances ou créée à l’aide de `LoggerFactory.Create`. Pour obtenir des exemples de configuration de la journalisation, consultez Journalisation et diagnostics dans gRPC sur .NET.
`MaxSendMessageSize`	`null`	Taille maximale des messages (en octets) pouvant être envoyés à partir du client. La tentative d’envoi d’un message qui dépasse la taille maximale configurée entraîne une exception. Lorsque la valeur est définie sur `null`, la taille du message est illimitée.
`MaxReceiveMessageSize`	4 Mo	Taille maximale du message en octets pouvant être reçue par le client. Si le client reçoit un message qui dépasse cette limite, il lève une exception. L’augmentation de cette valeur permet au client de recevoir des messages plus volumineux, mais peut avoir un impact négatif sur la consommation de mémoire. Lorsque la valeur est définie sur `null`, la taille du message est illimitée.
`Credentials`	`null`	Instance de `ChannelCredentials`. Les informations d’identification sont utilisées pour ajouter des métadonnées d’authentification aux appels gRPC.
`CompressionProviders`	gzip	Une collection de fournisseurs de compression utilisés pour compresser et décompresser les messages. Des fournisseurs de compression personnalisés peuvent être créés et ajoutés à la collection. Les fournisseurs configurés par défaut prennent en charge la compression gzip.
`ThrowOperationCanceledOnCancellation`	`false`	Si la valeur est `true`, les clients lèvent OperationCanceledException lorsqu’un appel est annulé ou que son échéance est dépassée.
`UnsafeUseInsecureChannelCallCredentials`	`false`	Si la valeur est `true`, les `CallCredentials` sont appliquées aux appels gRPC effectués par un canal non sécurisé. L’envoi d’en-têtes d’authentification sur une connexion non sécurisée a des implications sur la sécurité et ne doit pas être effectué dans les environnements de production.
`MaxRetryAttempts`	5	Le nombre maximal de nouvelles tentatives. Cette valeur limite toutes les nouvelles tentatives et les valeurs de tentative de hedging spécifiées dans la configuration du service. La définition de cette valeur seule n’active pas les nouvelles tentatives. Les nouvelles tentatives sont activées dans la configuration du service, ce qui peut être effectué à l’aide de `ServiceConfig`. Une valeur `null` supprime la limite de nouvelles tentatives. Pour plus d’informations sur les nouvelles tentatives, consultez Gestion des erreurs temporaires avec les nouvelles tentatives gRPC.
`MaxRetryBufferSize`	16 Mo	Taille maximale de la mémoire tampon en octets qui peut être utilisée pour stocker les messages envoyés lors de nouvelles tentatives ou de couverture d’appels. Si la limite de mémoire tampon est dépassée, plus aucune nouvelle tentative n’est effectuée, et tous les appels de couverture, sauf un, sont annulés. Cette limite est appliquée à tous les appels effectués à l’aide du canal. Une valeur `null` supprime la limite de taille de mémoire tampon de nouvelle tentative.
`MaxRetryBufferPerCallSize`	1 Mo	Taille maximale de la mémoire tampon en octets qui peut être utilisée pour stocker les messages envoyés lors de nouvelles tentatives ou de couverture d’appels. Si la limite de mémoire tampon est dépassée, plus aucune nouvelle tentative n’est effectuée, et tous les appels de couverture, sauf un, sont annulés. Cette limite est appliquée par appel. Une valeur `null` supprime la limite de taille de mémoire tampon de nouvelle tentative par appel.
`ServiceConfig`	`null`	Configuration du service pour un canal gRPC. Une configuration de service peut être utilisée pour configurer les nouvelles tentatives gRPC.

Le code suivant :

Définit la taille maximale des messages d’envoi et de réception sur le canal.
Crée un 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);
}

Notez que les intercepteurs clients ne sont pas configurés avec GrpcChannelOptions. Au lieu de cela, ils sont configurés à l’aide de la méthode d’extension Intercept avec un canal. Cette méthode d’extension se trouve dans l’espace de noms Grpc.Core.Interceptors.

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);
}

Options du gestionnaire System.Net

Grpc.Net.Client utilise un transport HTTP dérivé de HttpMessageHandler pour effectuer des requêtes HTTP. Chaque gestionnaire offre des options supplémentaires pour la façon dont les requêtes HTTP sont effectuées.

Le gestionnaire est configuré sur un canal et peut être remplacé en définissant GrpcChannelOptions.HttpHandler. .NET Core 3 et .NET 5 et versions ultérieures utilisent SocketsHttpHandler par défaut. Les applications clientes gRPC sur .NET Framework doivent configurer WinHttpHandler.

Pour plus d’informations sur les différents gestionnaires et leurs options de configuration, consultez :

Share via