Services gRPC avec ASP.NET Core

  • Article

Ce document montre comment démarrer avec les services gRPC à l’aide de ASP.NET Core.

Prérequis

Bien démarrer avec le service gRPC dans ASP.NET Core

Affichez ou téléchargez un exemple de code (procédure de téléchargement).

Consultez Prise en main des services gRPC pour obtenir des instructions détaillées sur la création d’un projet gRPC.

Ajouter des services gRPC à une application ASP.NET Core

gRPC nécessite le package Grpc.AspNetCore.

Configurer gRPC

Dans Program.cs :

  • gRPC est activé avec la méthode AddGrpc.
  • Chaque service gRPC est ajouté au pipeline de routage via la méthode MapGrpcService.
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

Si vous souhaitez voir les commentaires de code traduits dans une langue autre que l’anglais, dites-le nous dans cette discussion GitHub.

ASP.NET Core middleware et les fonctionnalités partagent le pipeline de routage. Par conséquent, une application peut être configurée pour servir des gestionnaires de requêtes supplémentaires. Les gestionnaires de requêtes supplémentaires, tels que les contrôleurs MVC, fonctionnent en parallèle avec les services gRPC configurés.

Options de serveur

Les services gRPC peuvent être hébergés par tous les serveurs ASP.NET Core intégrés.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†Requiert .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou version ultérieure.

Pour plus d’informations sur le choix du serveur approprié pour une application ASP.NET Core, consultez Implémentations de serveur web dans ASP.NET Core.

Kestrel

Kestrel est un serveur web multiplateforme pour ASP.NET Core. Kestrel se concentre sur les hautes performances et l’utilisation de la mémoire, mais il ne dispose pas de certaines des fonctionnalités avancées dans HTTP.sys telles que le partage de ports.

Points de terminaison gRPC Kestrel :

HTTP/2

gRPC nécessite HTTP/2. gRPC pour ASP.NET Core valide HttpRequest.Protocol est HTTP/2.

Kestrelprend en charge HTTP/2 sur la plupart des systèmes d’exploitation modernes. Les points de terminaison Kestrel sont configurés pour prendre en charge les connexions HTTP/1.1 et HTTP/2 par défaut.

TLS

Les points de terminaison Kestrel utilisés pour gRPC doivent être sécurisés avec TLS. Pendant le développement, un point de terminaison sécurisé avec TLS est automatiquement créé à https://localhost:5001 quand le certificat de développement ASP.NET Core est présent. Aucune configuration n'est requise. Un préfixe https vérifie que le point de terminaison Kestrel utilise TLS.

Pendant la production, TLS doit être explicitement configuré. Dans l’exemple suivant appsettings.json, un point de terminaison HTTP/2 sécurisé avec TLS est fourni :

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Vous pouvez également configurer des points de terminaison Kestrel dans Program.cs :

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Pour plus d’informations sur l’activation de TLS avec Kestrel, consultez Kestrel Configuration du point de terminaison HTTPS.

Négociation de protocole

TLS est utilisé pour plus que la simple sécurisation de la communication. Le protocole ALPN (Application-Layer Protocol Negotiation) d’établissement de liaison de la TLS est utilisé pour négocier le protocole de connexion entre le client et le serveur lorsqu’un point de terminaison prend en charge plusieurs protocoles. Cette négociation détermine si la connexion utilise HTTP/1.1 ou HTTP/2.

Si un point de terminaison HTTP/2 est configuré sans TLS, le paramètre ListenOptions.Protocols du point de terminaison doit être défini sur HttpProtocols.Http2. Un point de terminaison avec plusieurs protocoles, par exemple HttpProtocols.Http1AndHttp2, ne peut pas être utilisé sans TLS, car il n’y a pas de négociation. Toutes les connexions au point de terminaison non sécurisé par défaut sont HTTP/1.1 et les appels gRPC échouent.

Pour plus d’informations sur l’activation de HTTP/2 et TLS avec Kestrel, consultez Configuration du point de terminaison Kestrel.

Remarque

macOS ne prend pas en charge ASP.NET Core gRPC avec TLS avant .NET 8. Une configuration supplémentaire est requise pour exécuter correctement les services gRPC sur macOS lors de l’utilisation de .NET 7 ou version antérieure. Pour plus d’informations, consultez Impossible de démarrer l’application ASP.NET Core gRPC sur MacOS.

IIS

IIS (Internet Information Services) est un serveur web flexible, sécurisé et gérable pour l’hébergement d’applications web, notamment ASP.NET Core. .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 (ou une version ultérieure) sont nécessaires à l’hébergement des services gRPC avec IIS.

IIS doit être configuré pour utiliser TLS et HTTP/2. Pour plus d’informations, consultez Utiliser ASP.NET Core avec HTTP/2 sur IIS.

HTTP.sys

HTTP.sys est un serveur web pour ASP.NET Core qui s’exécute uniquement sous Windows. .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 (ou une version ultérieure) sont nécessaires à l’hébergement des services gRPC avec HTTP.sys.

HTTP.sys devez être configuré pour utiliser TLS et HTTP/2. Pour plus d’informations, consultez Prise en charge de serveur web HTTP.sys HTTP/2.

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

Un serveur gRPC ASP.NET Core est généralement créé à partir du modèle gRPC. Le fichier projet créé par le modèle utilise Microsoft.NET.SDK.Web comme SDK :

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

La valeur du Kit de développement logiciel (SDK) Microsoft.NET.SDK.Web ajoute automatiquement une référence à l’infrastructure ASP.NET Core. La référence permet à l’application d’utiliser ASP.NET types Core requis pour héberger un serveur.

Vous pouvez ajouter un serveur gRPC à des projets non-ASP.NET Core avec les paramètres de fichier projet suivants :

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Le fichier projet précédent :

  • N’utilise pas Microsoft.NET.SDK.Web comme Kit de développement logiciel (SDK).
  • Ajoute une référence de framework à Microsoft.AspNetCore.App.
    • La référence du framework permet aux applications ASP.NET principales, telles que les Windows Services, les applications WPF ou WinForms, d’utiliser les API ASP.NET Core.
    • L’application peut désormais utiliser les API ASP.NET Core pour démarrer un serveur ASP.NET Core.
  • Ajoute les exigences gRPC :

Pour plus d’informations sur l’utilisation de la référence de l’infrastructure Microsoft.AspNetCore.App, consultez Utiliser l’infrastructure partagée ASP.NET Core.

Intégration à ASP.NET Core API

Les services gRPC ont un accès complet aux fonctionnalités ASP.NET Core telles que l’injection de dépendances et la journalisation. Par exemple, l’implémentation du service peut résoudre un service de journal à partir du conteneur d’injection de dépendances via le constructeur :

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

Par défaut, l’implémentation du service gRPC peut résoudre d’autres services d’injection de dépendances avec n’importe quelle durée de vie (Singleton, Délimitée ou Temporaire).

Résoudre HttpContext dans les méthodes gRPC

L’API gRPC permet d’accéder à certaines données de message HTTP/2, telles que la méthode, l’hôte, l’en-tête et les codes de fin. L’accès se fait via l’argument ServerCallContext passé à chaque méthode gRPC :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext ne fournit pas un accès complet à HttpContext dans toutes les API ASP.NET. La méthode d’extension GetHttpContext fournit un accès complet à HttpContext représentant le message HTTP/2 sous-jacent dans ASP.NET API :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Ressources supplémentaires

Ce document montre comment démarrer avec les services gRPC à l’aide de ASP.NET Core.

Prérequis

Bien démarrer avec le service gRPC dans ASP.NET Core

Affichez ou téléchargez un exemple de code (procédure de téléchargement).

Consultez Prise en main des services gRPC pour obtenir des instructions détaillées sur la création d’un projet gRPC.

Ajouter des services gRPC à une application ASP.NET Core

gRPC nécessite le package Grpc.AspNetCore.

Configurer gRPC

Dans Program.cs :

  • gRPC est activé avec la méthode AddGrpc.
  • Chaque service gRPC est ajouté au pipeline de routage via la méthode MapGrpcService.
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

Si vous souhaitez voir les commentaires de code traduits dans une langue autre que l’anglais, dites-le nous dans cette discussion GitHub.

ASP.NET Core middleware et les fonctionnalités partagent le pipeline de routage. Par conséquent, une application peut être configurée pour servir des gestionnaires de requêtes supplémentaires. Les gestionnaires de requêtes supplémentaires, tels que les contrôleurs MVC, fonctionnent en parallèle avec les services gRPC configurés.

Options de serveur

Les services gRPC peuvent être hébergés par tous les serveurs ASP.NET Core intégrés.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†Requiert .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou version ultérieure.

Pour plus d’informations sur le choix du serveur approprié pour une application ASP.NET Core, consultez Implémentations de serveur web dans ASP.NET Core.

Kestrel

Kestrel est un serveur web multiplateforme pour ASP.NET Core. Kestrel se concentre sur les hautes performances et l’utilisation de la mémoire, mais il ne dispose pas de certaines des fonctionnalités avancées dans HTTP.sys telles que le partage de ports.

Points de terminaison gRPC Kestrel :

HTTP/2

gRPC nécessite HTTP/2. gRPC pour ASP.NET Core valide HttpRequest.Protocol est HTTP/2.

Kestrelprend en charge HTTP/2 sur la plupart des systèmes d’exploitation modernes. Les points de terminaison Kestrel sont configurés pour prendre en charge les connexions HTTP/1.1 et HTTP/2 par défaut.

TLS

Les points de terminaison Kestrel utilisés pour gRPC doivent être sécurisés avec TLS. Pendant le développement, un point de terminaison sécurisé avec TLS est automatiquement créé à https://localhost:5001 quand le certificat de développement ASP.NET Core est présent. Aucune configuration n'est requise. Un préfixe https vérifie que le point de terminaison Kestrel utilise TLS.

Pendant la production, TLS doit être explicitement configuré. Dans l’exemple suivant appsettings.json, un point de terminaison HTTP/2 sécurisé avec TLS est fourni :

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Vous pouvez également configurer des points de terminaison Kestrel dans Program.cs :

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Pour plus d’informations sur l’activation de TLS avec Kestrel, consultez Kestrel Configuration du point de terminaison HTTPS.

Négociation de protocole

TLS est utilisé pour plus que la simple sécurisation de la communication. Le protocole ALPN (Application-Layer Protocol Negotiation) d’établissement de liaison de la TLS est utilisé pour négocier le protocole de connexion entre le client et le serveur lorsqu’un point de terminaison prend en charge plusieurs protocoles. Cette négociation détermine si la connexion utilise HTTP/1.1 ou HTTP/2.

Si un point de terminaison HTTP/2 est configuré sans TLS, le paramètre ListenOptions.Protocols du point de terminaison doit être défini sur HttpProtocols.Http2. Un point de terminaison avec plusieurs protocoles, par exemple HttpProtocols.Http1AndHttp2, ne peut pas être utilisé sans TLS, car il n’y a pas de négociation. Toutes les connexions au point de terminaison non sécurisé par défaut sont HTTP/1.1 et les appels gRPC échouent.

Pour plus d’informations sur l’activation de HTTP/2 et TLS avec Kestrel, consultez Configuration du point de terminaison Kestrel.

Remarque

macOS ne prend pas en charge ASP.NET Core gRPC avec TLS avant .NET 8. Une configuration supplémentaire est requise pour exécuter correctement les services gRPC sur macOS lors de l’utilisation de .NET 7 ou version antérieure. Pour plus d’informations, consultez Impossible de démarrer l’application ASP.NET Core gRPC sur MacOS.

IIS

IIS (Internet Information Services) est un serveur web flexible, sécurisé et gérable pour l’hébergement d’applications web, notamment ASP.NET Core. .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 (ou une version ultérieure) sont nécessaires à l’hébergement des services gRPC avec IIS.

IIS doit être configuré pour utiliser TLS et HTTP/2. Pour plus d’informations, consultez Utiliser ASP.NET Core avec HTTP/2 sur IIS.

HTTP.sys

HTTP.sys est un serveur web pour ASP.NET Core qui s’exécute uniquement sous Windows. .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 (ou une version ultérieure) sont nécessaires à l’hébergement des services gRPC avec HTTP.sys.

HTTP.sys devez être configuré pour utiliser TLS et HTTP/2. Pour plus d’informations, consultez Prise en charge de serveur web HTTP.sys HTTP/2.

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

Un serveur gRPC ASP.NET Core est généralement créé à partir du modèle gRPC. Le fichier projet créé par le modèle utilise Microsoft.NET.SDK.Web comme SDK :

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

La valeur du Kit de développement logiciel (SDK) Microsoft.NET.SDK.Web ajoute automatiquement une référence à l’infrastructure ASP.NET Core. La référence permet à l’application d’utiliser ASP.NET types Core requis pour héberger un serveur.

Vous pouvez ajouter un serveur gRPC à des projets non-ASP.NET Core avec les paramètres de fichier projet suivants :

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Le fichier projet précédent :

  • N’utilise pas Microsoft.NET.SDK.Web comme Kit de développement logiciel (SDK).
  • Ajoute une référence de framework à Microsoft.AspNetCore.App.
    • La référence du framework permet aux applications ASP.NET principales, telles que les Windows Services, les applications WPF ou WinForms, d’utiliser les API ASP.NET Core.
    • L’application peut désormais utiliser les API ASP.NET Core pour démarrer un serveur ASP.NET Core.
  • Ajoute les exigences gRPC :

Pour plus d’informations sur l’utilisation de la référence de l’infrastructure Microsoft.AspNetCore.App, consultez Utiliser l’infrastructure partagée ASP.NET Core.

Intégration à ASP.NET Core API

Les services gRPC ont un accès complet aux fonctionnalités ASP.NET Core telles que l’injection de dépendances et la journalisation. Par exemple, l’implémentation du service peut résoudre un service de journal à partir du conteneur d’injection de dépendances via le constructeur :

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

Par défaut, l’implémentation du service gRPC peut résoudre d’autres services d’injection de dépendances avec n’importe quelle durée de vie (Singleton, Délimitée ou Temporaire).

Résoudre HttpContext dans les méthodes gRPC

L’API gRPC permet d’accéder à certaines données de message HTTP/2, telles que la méthode, l’hôte, l’en-tête et les codes de fin. L’accès se fait via l’argument ServerCallContext passé à chaque méthode gRPC :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext ne fournit pas un accès complet à HttpContext dans toutes les API ASP.NET. La méthode d’extension GetHttpContext fournit un accès complet à HttpContext représentant le message HTTP/2 sous-jacent dans ASP.NET API :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Ressources supplémentaires

Ce document montre comment démarrer avec les services gRPC à l’aide de ASP.NET Core.

Prérequis

Bien démarrer avec le service gRPC dans ASP.NET Core

Affichez ou téléchargez un exemple de code (procédure de téléchargement).

Consultez Prise en main des services gRPC pour obtenir des instructions détaillées sur la création d’un projet gRPC.

Ajouter des services gRPC à une application ASP.NET Core

gRPC nécessite le package Grpc.AspNetCore.

Configurer gRPC

Dans Program.cs :

  • gRPC est activé avec la méthode AddGrpc.
  • Chaque service gRPC est ajouté au pipeline de routage via la méthode MapGrpcService.
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

Si vous souhaitez voir les commentaires de code traduits dans une langue autre que l’anglais, dites-le nous dans cette discussion GitHub.

ASP.NET Core middleware et les fonctionnalités partagent le pipeline de routage. Par conséquent, une application peut être configurée pour servir des gestionnaires de requêtes supplémentaires. Les gestionnaires de requêtes supplémentaires, tels que les contrôleurs MVC, fonctionnent en parallèle avec les services gRPC configurés.

Options de serveur

Les services gRPC peuvent être hébergés par tous les serveurs ASP.NET Core intégrés.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†Requiert .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou version ultérieure.

Pour plus d’informations sur le choix du serveur approprié pour une application ASP.NET Core, consultez Implémentations de serveur web dans ASP.NET Core.

Kestrel

Kestrel est un serveur web multiplateforme pour ASP.NET Core. Kestrel se concentre sur les hautes performances et l’utilisation de la mémoire, mais il ne dispose pas de certaines des fonctionnalités avancées dans HTTP.sys telles que le partage de ports.

Points de terminaison gRPC Kestrel :

HTTP/2

gRPC nécessite HTTP/2. gRPC pour ASP.NET Core valide HttpRequest.Protocol est HTTP/2.

Kestrelprend en charge HTTP/2 sur la plupart des systèmes d’exploitation modernes. Les points de terminaison Kestrel sont configurés pour prendre en charge les connexions HTTP/1.1 et HTTP/2 par défaut.

TLS

Les points de terminaison Kestrel utilisés pour gRPC doivent être sécurisés avec TLS. Pendant le développement, un point de terminaison sécurisé avec TLS est automatiquement créé à https://localhost:5001 quand le certificat de développement ASP.NET Core est présent. Aucune configuration n'est requise. Un préfixe https vérifie que le point de terminaison Kestrel utilise TLS.

Pendant la production, TLS doit être explicitement configuré. Dans l’exemple suivant appsettings.json, un point de terminaison HTTP/2 sécurisé avec TLS est fourni :

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Vous pouvez également configurer des points de terminaison Kestrel dans Program.cs :

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Pour plus d’informations sur l’activation de TLS avec Kestrel, consultez Kestrel Configuration du point de terminaison HTTPS.

Négociation de protocole

TLS est utilisé pour plus que la simple sécurisation de la communication. Le protocole ALPN (Application-Layer Protocol Negotiation) d’établissement de liaison de la TLS est utilisé pour négocier le protocole de connexion entre le client et le serveur lorsqu’un point de terminaison prend en charge plusieurs protocoles. Cette négociation détermine si la connexion utilise HTTP/1.1 ou HTTP/2.

Si un point de terminaison HTTP/2 est configuré sans TLS, le paramètre ListenOptions.Protocols du point de terminaison doit être défini sur HttpProtocols.Http2. Un point de terminaison avec plusieurs protocoles, par exemple HttpProtocols.Http1AndHttp2, ne peut pas être utilisé sans TLS, car il n’y a pas de négociation. Toutes les connexions au point de terminaison non sécurisé par défaut sont HTTP/1.1 et les appels gRPC échouent.

Pour plus d’informations sur l’activation de HTTP/2 et TLS avec Kestrel, consultez Configuration du point de terminaison Kestrel.

Remarque

macOS ne prend pas en charge ASP.NET Core gRPC avec TLS avant .NET 8. Une configuration supplémentaire est requise pour exécuter correctement les services gRPC sur macOS lors de l’utilisation de .NET 7 ou version antérieure. Pour plus d’informations, consultez Impossible de démarrer l’application ASP.NET Core gRPC sur MacOS.

IIS

IIS (Internet Information Services) est un serveur web flexible, sécurisé et gérable pour l’hébergement d’applications web, notamment ASP.NET Core. .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 (ou une version ultérieure) sont nécessaires à l’hébergement des services gRPC avec IIS.

IIS doit être configuré pour utiliser TLS et HTTP/2. Pour plus d’informations, consultez Utiliser ASP.NET Core avec HTTP/2 sur IIS.

HTTP.sys

HTTP.sys est un serveur web pour ASP.NET Core qui s’exécute uniquement sous Windows. .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 (ou une version ultérieure) sont nécessaires à l’hébergement des services gRPC avec HTTP.sys.

HTTP.sys devez être configuré pour utiliser TLS et HTTP/2. Pour plus d’informations, consultez Prise en charge de serveur web HTTP.sys HTTP/2.

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

Un serveur gRPC ASP.NET Core est généralement créé à partir du modèle gRPC. Le fichier projet créé par le modèle utilise Microsoft.NET.SDK.Web comme SDK :

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

La valeur du Kit de développement logiciel (SDK) Microsoft.NET.SDK.Web ajoute automatiquement une référence à l’infrastructure ASP.NET Core. La référence permet à l’application d’utiliser ASP.NET types Core requis pour héberger un serveur.

Vous pouvez ajouter un serveur gRPC à des projets non-ASP.NET Core avec les paramètres de fichier projet suivants :

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Le fichier projet précédent :

  • N’utilise pas Microsoft.NET.SDK.Web comme Kit de développement logiciel (SDK).
  • Ajoute une référence de framework à Microsoft.AspNetCore.App.
    • La référence du framework permet aux applications ASP.NET principales, telles que les Windows Services, les applications WPF ou WinForms, d’utiliser les API ASP.NET Core.
    • L’application peut désormais utiliser les API ASP.NET Core pour démarrer un serveur ASP.NET Core.
  • Ajoute les exigences gRPC :

Pour plus d’informations sur l’utilisation de la référence de l’infrastructure Microsoft.AspNetCore.App, consultez Utiliser l’infrastructure partagée ASP.NET Core.

Intégration à ASP.NET Core API

Les services gRPC ont un accès complet aux fonctionnalités ASP.NET Core telles que l’injection de dépendances et la journalisation. Par exemple, l’implémentation du service peut résoudre un service de journal à partir du conteneur d’injection de dépendances via le constructeur :

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

Par défaut, l’implémentation du service gRPC peut résoudre d’autres services d’injection de dépendances avec n’importe quelle durée de vie (Singleton, Délimitée ou Temporaire).

Résoudre HttpContext dans les méthodes gRPC

L’API gRPC permet d’accéder à certaines données de message HTTP/2, telles que la méthode, l’hôte, l’en-tête et les codes de fin. L’accès se fait via l’argument ServerCallContext passé à chaque méthode gRPC :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext ne fournit pas un accès complet à HttpContext dans toutes les API ASP.NET. La méthode d’extension GetHttpContext fournit un accès complet à HttpContext représentant le message HTTP/2 sous-jacent dans ASP.NET API :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Ressources supplémentaires

Ce document montre comment démarrer avec les services gRPC à l’aide de ASP.NET Core.

Prérequis

Bien démarrer avec le service gRPC dans ASP.NET Core

Affichez ou téléchargez un exemple de code (procédure de téléchargement).

Consultez Prise en main des services gRPC pour obtenir des instructions détaillées sur la création d’un projet gRPC.

Ajouter des services gRPC à une application ASP.NET Core

gRPC nécessite le package Grpc.AspNetCore.

Configurer gRPC

Dans Startup.cs :

  • gRPC est activé avec la méthode AddGrpc.
  • Chaque service gRPC est ajouté au pipeline de routage via la méthode MapGrpcService.
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

Si vous souhaitez voir les commentaires de code traduits dans une langue autre que l’anglais, dites-le nous dans cette discussion GitHub.

ASP.NET Core middleware et les fonctionnalités partagent le pipeline de routage. Par conséquent, une application peut être configurée pour servir des gestionnaires de requêtes supplémentaires. Les gestionnaires de requêtes supplémentaires, tels que les contrôleurs MVC, fonctionnent en parallèle avec les services gRPC configurés.

Options de serveur

Les services gRPC peuvent être hébergés par tous les serveurs ASP.NET Core intégrés.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†Requiert .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou version ultérieure.

Pour plus d’informations sur le choix du serveur approprié pour une application ASP.NET Core, consultez Implémentations de serveur web dans ASP.NET Core.

Kestrel

Kestrel est un serveur web multiplateforme pour ASP.NET Core. Kestrel se concentre sur les hautes performances et l’utilisation de la mémoire, mais il ne dispose pas de certaines des fonctionnalités avancées dans HTTP.sys telles que le partage de ports.

Points de terminaison gRPC Kestrel :

HTTP/2

gRPC nécessite HTTP/2. gRPC pour ASP.NET Core valide HttpRequest.Protocol est HTTP/2.

Kestrelprend en charge HTTP/2 sur la plupart des systèmes d’exploitation modernes. Les points de terminaison Kestrel sont configurés pour prendre en charge les connexions HTTP/1.1 et HTTP/2 par défaut.

TLS

Les points de terminaison Kestrel utilisés pour gRPC doivent être sécurisés avec TLS. Pendant le développement, un point de terminaison sécurisé avec TLS est automatiquement créé à https://localhost:5001 quand le certificat de développement ASP.NET Core est présent. Aucune configuration n'est requise. Un préfixe https vérifie que le point de terminaison Kestrel utilise TLS.

Pendant la production, TLS doit être explicitement configuré. Dans l’exemple suivant appsettings.json, un point de terminaison HTTP/2 sécurisé avec TLS est fourni :

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Vous pouvez également configurer des points de terminaison Kestrel dans Program.cs :

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Pour plus d’informations sur l’activation de TLS avec Kestrel, consultez Kestrel Configuration du point de terminaison HTTPS.

Négociation de protocole

TLS est utilisé pour plus que la simple sécurisation de la communication. Le protocole ALPN (Application-Layer Protocol Negotiation) d’établissement de liaison de la TLS est utilisé pour négocier le protocole de connexion entre le client et le serveur lorsqu’un point de terminaison prend en charge plusieurs protocoles. Cette négociation détermine si la connexion utilise HTTP/1.1 ou HTTP/2.

Si un point de terminaison HTTP/2 est configuré sans TLS, le paramètre ListenOptions.Protocols du point de terminaison doit être défini sur HttpProtocols.Http2. Un point de terminaison avec plusieurs protocoles, par exemple HttpProtocols.Http1AndHttp2, ne peut pas être utilisé sans TLS, car il n’y a pas de négociation. Toutes les connexions au point de terminaison non sécurisé par défaut sont HTTP/1.1 et les appels gRPC échouent.

Pour plus d’informations sur l’activation de HTTP/2 et TLS avec Kestrel, consultez Configuration du point de terminaison Kestrel.

Remarque

macOS ne prend pas en charge ASP.NET Core gRPC avec TLS avant .NET 8. Une configuration supplémentaire est requise pour exécuter correctement les services gRPC sur macOS lors de l’utilisation de .NET 7 ou version antérieure. Pour plus d’informations, consultez Impossible de démarrer l’application ASP.NET Core gRPC sur MacOS.

IIS

IIS (Internet Information Services) est un serveur web flexible, sécurisé et gérable pour l’hébergement d’applications web, notamment ASP.NET Core. .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 (ou une version ultérieure) sont nécessaires à l’hébergement des services gRPC avec IIS.

IIS doit être configuré pour utiliser TLS et HTTP/2. Pour plus d’informations, consultez Utiliser ASP.NET Core avec HTTP/2 sur IIS.

HTTP.sys

HTTP.sys est un serveur web pour ASP.NET Core qui s’exécute uniquement sous Windows. .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 (ou une version ultérieure) sont nécessaires à l’hébergement des services gRPC avec HTTP.sys.

HTTP.sys devez être configuré pour utiliser TLS et HTTP/2. Pour plus d’informations, consultez Prise en charge de serveur web HTTP.sys HTTP/2.

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

Un serveur gRPC ASP.NET Core est généralement créé à partir du modèle gRPC. Le fichier projet créé par le modèle utilise Microsoft.NET.SDK.Web comme SDK :

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

La valeur du Kit de développement logiciel (SDK) Microsoft.NET.SDK.Web ajoute automatiquement une référence à l’infrastructure ASP.NET Core. La référence permet à l’application d’utiliser ASP.NET types Core requis pour héberger un serveur.

Vous pouvez ajouter un serveur gRPC à des projets non-ASP.NET Core avec les paramètres de fichier projet suivants :

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Le fichier projet précédent :

  • N’utilise pas Microsoft.NET.SDK.Web comme Kit de développement logiciel (SDK).
  • Ajoute une référence de framework à Microsoft.AspNetCore.App.
    • La référence du framework permet aux applications ASP.NET principales, telles que les Windows Services, les applications WPF ou WinForms, d’utiliser les API ASP.NET Core.
    • L’application peut désormais utiliser les API ASP.NET Core pour démarrer un serveur ASP.NET Core.
  • Ajoute les exigences gRPC :

Pour plus d’informations sur l’utilisation de la référence de l’infrastructure Microsoft.AspNetCore.App, consultez Utiliser l’infrastructure partagée ASP.NET Core.

Intégration à ASP.NET Core API

Les services gRPC ont un accès complet aux fonctionnalités ASP.NET Core telles que l’injection de dépendances et la journalisation. Par exemple, l’implémentation du service peut résoudre un service de journal à partir du conteneur d’injection de dépendances via le constructeur :

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

Par défaut, l’implémentation du service gRPC peut résoudre d’autres services d’injection de dépendances avec n’importe quelle durée de vie (Singleton, Délimitée ou Temporaire).

Résoudre HttpContext dans les méthodes gRPC

L’API gRPC permet d’accéder à certaines données de message HTTP/2, telles que la méthode, l’hôte, l’en-tête et les codes de fin. L’accès se fait via l’argument ServerCallContext passé à chaque méthode gRPC :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext ne fournit pas un accès complet à HttpContext dans toutes les API ASP.NET. La méthode d’extension GetHttpContext fournit un accès complet à HttpContext représentant le message HTTP/2 sous-jacent dans ASP.NET API :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Ressources supplémentaires

Ce document montre comment démarrer avec les services gRPC à l’aide de ASP.NET Core.

Prérequis

Bien démarrer avec le service gRPC dans ASP.NET Core

Affichez ou téléchargez un exemple de code (procédure de téléchargement).

Consultez Prise en main des services gRPC pour obtenir des instructions détaillées sur la création d’un projet gRPC.

Ajouter des services gRPC à une application ASP.NET Core

gRPC nécessite le package Grpc.AspNetCore.

Configurer gRPC

Dans Startup.cs :

  • gRPC est activé avec la méthode AddGrpc.
  • Chaque service gRPC est ajouté au pipeline de routage via la méthode MapGrpcService.
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

Si vous souhaitez voir les commentaires de code traduits dans une langue autre que l’anglais, dites-le nous dans cette discussion GitHub.

ASP.NET Core middleware et les fonctionnalités partagent le pipeline de routage. Par conséquent, une application peut être configurée pour servir des gestionnaires de requêtes supplémentaires. Les gestionnaires de requêtes supplémentaires, tels que les contrôleurs MVC, fonctionnent en parallèle avec les services gRPC configurés.

Options de serveur

Les services gRPC peuvent être hébergés par tous les serveurs ASP.NET Core intégrés.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†Requiert .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou version ultérieure.

Pour plus d’informations sur le choix du serveur approprié pour une application ASP.NET Core, consultez Implémentations de serveur web dans ASP.NET Core.

Kestrel

Kestrel est un serveur web multiplateforme pour ASP.NET Core. Kestrel se concentre sur les hautes performances et l’utilisation de la mémoire, mais il ne dispose pas de certaines des fonctionnalités avancées dans HTTP.sys telles que le partage de ports.

Points de terminaison gRPC Kestrel :

HTTP/2

gRPC nécessite HTTP/2. gRPC pour ASP.NET Core valide HttpRequest.Protocol est HTTP/2.

Kestrelprend en charge HTTP/2 sur la plupart des systèmes d’exploitation modernes. Les points de terminaison Kestrel sont configurés pour prendre en charge les connexions HTTP/1.1 et HTTP/2 par défaut.

TLS

Les points de terminaison Kestrel utilisés pour gRPC doivent être sécurisés avec TLS. Pendant le développement, un point de terminaison sécurisé avec TLS est automatiquement créé à https://localhost:5001 quand le certificat de développement ASP.NET Core est présent. Aucune configuration n'est requise. Un préfixe https vérifie que le point de terminaison Kestrel utilise TLS.

Pendant la production, TLS doit être explicitement configuré. Dans l’exemple suivant appsettings.json, un point de terminaison HTTP/2 sécurisé avec TLS est fourni :

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Vous pouvez également configurer des points de terminaison Kestrel dans Program.cs :

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Pour plus d’informations sur l’activation de TLS avec Kestrel, consultez Kestrel Configuration du point de terminaison HTTPS.

Négociation de protocole

TLS est utilisé pour plus que la simple sécurisation de la communication. Le protocole ALPN (Application-Layer Protocol Negotiation) d’établissement de liaison de la TLS est utilisé pour négocier le protocole de connexion entre le client et le serveur lorsqu’un point de terminaison prend en charge plusieurs protocoles. Cette négociation détermine si la connexion utilise HTTP/1.1 ou HTTP/2.

Si un point de terminaison HTTP/2 est configuré sans TLS, le paramètre ListenOptions.Protocols du point de terminaison doit être défini sur HttpProtocols.Http2. Un point de terminaison avec plusieurs protocoles, par exemple HttpProtocols.Http1AndHttp2, ne peut pas être utilisé sans TLS, car il n’y a pas de négociation. Toutes les connexions au point de terminaison non sécurisé par défaut sont HTTP/1.1 et les appels gRPC échouent.

Pour plus d’informations sur l’activation de HTTP/2 et TLS avec Kestrel, consultez Configuration du point de terminaison Kestrel.

Remarque

macOS ne prend pas en charge ASP.NET Core gRPC avec TLS avant .NET 8. Une configuration supplémentaire est requise pour exécuter correctement les services gRPC sur macOS lors de l’utilisation de .NET 7 ou version antérieure. Pour plus d’informations, consultez Impossible de démarrer l’application ASP.NET Core gRPC sur MacOS.

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

Un serveur gRPC ASP.NET Core est généralement créé à partir du modèle gRPC. Le fichier projet créé par le modèle utilise Microsoft.NET.SDK.Web comme SDK :

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

La valeur du Kit de développement logiciel (SDK) Microsoft.NET.SDK.Web ajoute automatiquement une référence à l’infrastructure ASP.NET Core. La référence permet à l’application d’utiliser ASP.NET types Core requis pour héberger un serveur.

Vous pouvez ajouter un serveur gRPC à des projets non-ASP.NET Core avec les paramètres de fichier projet suivants :

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Le fichier projet précédent :

  • N’utilise pas Microsoft.NET.SDK.Web comme Kit de développement logiciel (SDK).
  • Ajoute une référence de framework à Microsoft.AspNetCore.App.
    • La référence du framework permet aux applications ASP.NET principales, telles que les Windows Services, les applications WPF ou WinForms, d’utiliser les API ASP.NET Core.
    • L’application peut désormais utiliser les API ASP.NET Core pour démarrer un serveur ASP.NET Core.
  • Ajoute les exigences gRPC :

Pour plus d’informations sur l’utilisation de la référence de l’infrastructure Microsoft.AspNetCore.App, consultez Utiliser l’infrastructure partagée ASP.NET Core.

Intégration à ASP.NET Core API

Les services gRPC ont un accès complet aux fonctionnalités ASP.NET Core telles que l’injection de dépendances et la journalisation. Par exemple, l’implémentation du service peut résoudre un service de journal à partir du conteneur d’injection de dépendances via le constructeur :

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

Par défaut, l’implémentation du service gRPC peut résoudre d’autres services d’injection de dépendances avec n’importe quelle durée de vie (Singleton, Délimitée ou Temporaire).

Résoudre HttpContext dans les méthodes gRPC

L’API gRPC permet d’accéder à certaines données de message HTTP/2, telles que la méthode, l’hôte, l’en-tête et les codes de fin. L’accès se fait via l’argument ServerCallContext passé à chaque méthode gRPC :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext ne fournit pas un accès complet à HttpContext dans toutes les API ASP.NET. La méthode d’extension GetHttpContext fournit un accès complet à HttpContext représentant le message HTTP/2 sous-jacent dans ASP.NET API :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Ressources supplémentaires

Ce document montre comment démarrer avec les services gRPC à l’aide de ASP.NET Core.

Prérequis

Bien démarrer avec le service gRPC dans ASP.NET Core

Affichez ou téléchargez un exemple de code (procédure de téléchargement).

Consultez Prise en main des services gRPC pour obtenir des instructions détaillées sur la création d’un projet gRPC.

Ajouter des services gRPC à une application ASP.NET Core

gRPC nécessite le package Grpc.AspNetCore.

Configurer gRPC

Dans Startup.cs :

  • gRPC est activé avec la méthode AddGrpc.
  • Chaque service gRPC est ajouté au pipeline de routage via la méthode MapGrpcService.
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

Si vous souhaitez voir les commentaires de code traduits dans une langue autre que l’anglais, dites-le nous dans cette discussion GitHub.

ASP.NET Core middleware et les fonctionnalités partagent le pipeline de routage. Par conséquent, une application peut être configurée pour servir des gestionnaires de requêtes supplémentaires. Les gestionnaires de requêtes supplémentaires, tels que les contrôleurs MVC, fonctionnent en parallèle avec les services gRPC configurés.

Options de serveur

Les services gRPC peuvent être hébergés par tous les serveurs ASP.NET Core intégrés.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†Requiert .NET 5 et Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou version ultérieure.

Pour plus d’informations sur le choix du serveur approprié pour une application ASP.NET Core, consultez Implémentations de serveur web dans ASP.NET Core.

Kestrel

Kestrel est un serveur web multiplateforme pour ASP.NET Core. Kestrel se concentre sur les hautes performances et l’utilisation de la mémoire, mais il ne dispose pas de certaines des fonctionnalités avancées dans HTTP.sys telles que le partage de ports.

Points de terminaison gRPC Kestrel :

HTTP/2

gRPC nécessite HTTP/2. gRPC pour ASP.NET Core valide HttpRequest.Protocol est HTTP/2.

Kestrelprend en charge HTTP/2 sur la plupart des systèmes d’exploitation modernes. Les points de terminaison Kestrel sont configurés pour prendre en charge les connexions HTTP/1.1 et HTTP/2 par défaut.

TLS

Les points de terminaison Kestrel utilisés pour gRPC doivent être sécurisés avec TLS. Pendant le développement, un point de terminaison sécurisé avec TLS est automatiquement créé à https://localhost:5001 quand le certificat de développement ASP.NET Core est présent. Aucune configuration n'est requise. Un préfixe https vérifie que le point de terminaison Kestrel utilise TLS.

Pendant la production, TLS doit être explicitement configuré. Dans l’exemple suivant appsettings.json, un point de terminaison HTTP/2 sécurisé avec TLS est fourni :

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Vous pouvez également configurer des points de terminaison Kestrel dans Program.cs :

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Pour plus d’informations sur l’activation de TLS avec Kestrel, consultez Kestrel Configuration du point de terminaison HTTPS.

Négociation de protocole

TLS est utilisé pour plus que la simple sécurisation de la communication. Le protocole ALPN (Application-Layer Protocol Negotiation) d’établissement de liaison de la TLS est utilisé pour négocier le protocole de connexion entre le client et le serveur lorsqu’un point de terminaison prend en charge plusieurs protocoles. Cette négociation détermine si la connexion utilise HTTP/1.1 ou HTTP/2.

Si un point de terminaison HTTP/2 est configuré sans TLS, le paramètre ListenOptions.Protocols du point de terminaison doit être défini sur HttpProtocols.Http2. Un point de terminaison avec plusieurs protocoles, par exemple HttpProtocols.Http1AndHttp2, ne peut pas être utilisé sans TLS, car il n’y a pas de négociation. Toutes les connexions au point de terminaison non sécurisé par défaut sont HTTP/1.1 et les appels gRPC échouent.

Pour plus d’informations sur l’activation de HTTP/2 et TLS avec Kestrel, consultez Configuration du point de terminaison Kestrel.

Remarque

macOS ne prend pas en charge ASP.NET Core gRPC avec TLS avant .NET 8. Une configuration supplémentaire est requise pour exécuter correctement les services gRPC sur macOS lors de l’utilisation de .NET 7 ou version antérieure. Pour plus d’informations, consultez Impossible de démarrer l’application ASP.NET Core gRPC sur MacOS.

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

Un serveur gRPC ASP.NET Core est généralement créé à partir du modèle gRPC. Le fichier projet créé par le modèle utilise Microsoft.NET.SDK.Web comme SDK :

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

La valeur du Kit de développement logiciel (SDK) Microsoft.NET.SDK.Web ajoute automatiquement une référence à l’infrastructure ASP.NET Core. La référence permet à l’application d’utiliser ASP.NET types Core requis pour héberger un serveur.

Vous pouvez ajouter un serveur gRPC à des projets non-ASP.NET Core avec les paramètres de fichier projet suivants :

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Le fichier projet précédent :

  • N’utilise pas Microsoft.NET.SDK.Web comme Kit de développement logiciel (SDK).
  • Ajoute une référence de framework à Microsoft.AspNetCore.App.
    • La référence du framework permet aux applications ASP.NET principales, telles que les Windows Services, les applications WPF ou WinForms, d’utiliser les API ASP.NET Core.
    • L’application peut désormais utiliser les API ASP.NET Core pour démarrer un serveur ASP.NET Core.
  • Ajoute les exigences gRPC :

Pour plus d’informations sur l’utilisation de la référence de l’infrastructure Microsoft.AspNetCore.App, consultez Utiliser l’infrastructure partagée ASP.NET Core.

Intégration à ASP.NET Core API

Les services gRPC ont un accès complet aux fonctionnalités ASP.NET Core telles que l’injection de dépendances et la journalisation. Par exemple, l’implémentation du service peut résoudre un service de journal à partir du conteneur d’injection de dépendances via le constructeur :

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

Par défaut, l’implémentation du service gRPC peut résoudre d’autres services d’injection de dépendances avec n’importe quelle durée de vie (Singleton, Délimitée ou Temporaire).

Résoudre HttpContext dans les méthodes gRPC

L’API gRPC permet d’accéder à certaines données de message HTTP/2, telles que la méthode, l’hôte, l’en-tête et les codes de fin. L’accès se fait via l’argument ServerCallContext passé à chaque méthode gRPC :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext ne fournit pas un accès complet à HttpContext dans toutes les API ASP.NET. La méthode d’extension GetHttpContext fournit un accès complet à HttpContext représentant le message HTTP/2 sous-jacent dans ASP.NET API :

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Ressources supplémentaires