Migrer gRPC de C-Core vers gRPC pour .NET

En raison de l’implémentation de la pile sous-jacente, toutes les fonctionnalités ne fonctionnent pas de la même façon entre les applications gRPC basées sur C-Core et gRPC pour .NET. Ce document met en évidence les principales différences de migration entre les deux piles.

Important

gRPC C-Core est en mode maintenance et sera déprécié au profit de gRPC pour .NET. gRPC C-Core n’est pas recommandé pour les nouvelles applications.

Plateforme prise en charge

gRPC C-Core et gRPC pour .NET ne prennent pas en charge les mêmes plateformes :

• gRPC C-Core : implémentation C++ gRPC avec ses propres piles TLS et HTTP/2. Le package Grpc.Core est un wrapper .NET autour de gRPC C-Core et contient un client et un serveur gRPC. Il prend en charge .NET Framework, .NET Core et .NET 5 ou version ultérieure.
• gRPC pour .NET : conçu pour .NET Core 3.x et .NET 5 ou version ultérieure. Il utilise des piles TLS et HTTP/2 intégrées aux versions modernes de .NET. Le package Grpc.AspNetCore contient un serveur gRPC hébergé dans ASP.NET Core et nécessite .NET Core 3.x ou .NET 5 ou version ultérieure. Le package Grpc.Net.Client contient un client gRPC. Le client dans Grpc.Net.Client dispose d’une prise en charge limitée du .NET Framework à l’aide de WinHttpHandler.

Pour plus d’informations, consultez gRPC sur les plateformes prises en charge par .NET.

Configurer le serveur et le canal

Les packages NuGet, la configuration et le code de démarrage doivent être modifiés lors de la migration de gRPC C-Core vers gRPC pour .NET.

gRPC pour .NET dispose de packages NuGet distincts pour son client et son serveur. Les packages ajoutés varient selon qu’une application héberge des services gRPC ou les appelle:

• Grpc.AspNetCore : les services sont hébergés par ASP.NET Core. Pour plus d’informations sur la configuration du serveur, consultez Services gRPC avec ASP.NET Core.
• Grpc.Net.Client : les clients utilisent GrpcChannel, qui utilise en interne des fonctionnalités de mise en réseau intégrées à .NET. Pour plus d’informations sur la configuration du client, consultez Appeler des services gRPC avec le client .NET.

Une fois la migration terminée, le package Grpc.Core doit être supprimé de l’application. Grpc.Core contient des fichiers binaires natifs volumineux, et la suppression du package réduit le temps de restauration NuGet et la taille de l’application.

Services et clients générés par le code

gRPC C-Core et gRPC pour .NET partagent de nombreuses API, et le code généré à partir de fichiers .proto est compatible avec les deux implémentations gRPC. La plupart des clients et du service peuvent être migrés de C-Core vers gRPC pour .NET sans modification.

Durée de vie de l’implémentation du service gRPC

Dans la pile ASP.NET Core, les services gRPC, par défaut, sont créés avec une durée de vie étendue. En revanche, gRPC C-Core est lié par défaut à un service avec une durée de vie singleton.

Une durée de vie étendue permet à l’implémentation du service de résoudre d’autres services avec des durées de vie étendues. Par exemple, une durée de vie étendue peut également résoudre DbContext à partir du conteneur DI via l’injection de constructeur. Utilisation d’une durée de vie étendue :

• Une nouvelle instance de l’implémentation du service est créée pour chaque requête.
• Il n’est pas possible de partager l’état entre les requêtes via instance membres sur le type d’implémentation.
• Il est attendu que des états partagés soient stockés dans un service singleton dans le conteneur DI. Les états partagés stockés sont résolus dans le constructeur de l’implémentation du service gRPC.

Pour plus d’informations sur les durées de vie de service, consultez Injection de dépendances dans ASP.NET Core.

Ajouter un service singleton

Pour faciliter la transition d’une implémentation C-Core gRPC vers ASP.NET Core, il est possible de modifier la durée de vie de l’implémentation du service d’étendue à singleton. Cela implique l’ajout d’une instance de l’implémentation de service au conteneur DI :

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
    services.AddSingleton(new GreeterService());
}

Toutefois, une implémentation de service avec une durée de vie singleton n’est plus en mesure de résoudre les services étendus par l’injection de constructeur.

Configurer les options des services gRPC

Dans les applications basées sur C-Core, les paramètres tels que grpc.max_receive_message_length et grpc.max_send_message_length sont configurés avec ChannelOption lors de la construction de l’instance serveur.

Dans ASP.NET Core, gRPC fournit la configuration via le type GrpcServiceOptions. Par exemple, la taille maximale des messages entrants d’un service gRPC peut être configurée via AddGrpc. L’exemple suivant modifie la valeur MaxReceiveMessageSize par défaut de 4 Mo à 16 Mo :

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc(options =>
    {
        options.MaxReceiveMessageSize = 16 * 1024 * 1024; // 16 MB
    });
}

Pour plus d’informations sur la configuration, consultez gRPC pour la configuration .NET.

Journalisation

Les applications basées sur C-Core s’appuient sur le GrpcEnvironment pour configurer l’enregistreur d’événements à des fins de débogage. La pile ASP.NET Core fournit cette fonctionnalité via l’API de journalisation. Par exemple, un enregistreur d’événements peut être ajouté au service gRPC via l’injection de constructeur :

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

Pour plus d’informations sur la journalisation et les diagnostics gRPC, consultez Journalisation et diagnostics dans gRPC sur .NET.

HTTPS

Les applications basées sur C-Core configurent HTTPS via la propriété Server.Ports. Un concept similaire est utilisé pour configurer des serveurs dans ASP.NET Core. Par exemple, Kestrel utilise la configuration du point de terminaison pour cette fonctionnalité.

Intercepteurs gRPC

L’intergiciel ASP.NET Core offre des fonctionnalités similaires à celles des intercepteurs dans les applications gRPC basées sur C-Core. Les deux étant pris en charge par les applications gRPC d’ASP.NET Core, il n’est pas nécessaire de réécrire les intercepteurs.

Pour plus d’informations sur les différences entre ces fonctionnalités, consultez Intercepteurs gRPC et intergiciel.

Héberger gRPC dans les projets non-ASP.NET Core

Un serveur C-core peut être ajouté à n’importe quel type de projet. Un serveur gRPC pour .NET nécessite ASP.NET Core. ASP.NET Core est généralement disponible, car le fichier projet spécifie Microsoft.NET.SDK.Web comme SDK.

Un serveur gRPC peut être hébergé sur des projets non-ASP.NET Core en ajoutant <FrameworkReference Include="Microsoft.AspNetCore.App" /> à un projet. La référence du framework rend les API ASP.NET Core disponibles et elles peuvent être utilisées pour démarrer un serveur ASP.NET Core.

Pour plus d’informations, consultez Héberger gRPC dans des projets non-ASP.NET Core.

Ressources supplémentaires

• Vue d’ensemble de gRPC sur .NET
• Services gRPC avec C#
• Services gRPC avec ASP.NET Core
• Créer un serveur et un client gRPC .NET Core dans ASP.NET Core