gRPC-Dienste mit ASP.NET Core

In diesem Dokument wird gezeigt, wie Sie mit gRPC-Diensten unter Verwendung von ASP.NET Core die ersten Schritte unternehmen können.

Voraussetzungen

Visual Studio

• Visual Studio 2019 mit der Workload ASP.NET- und Webentwicklung
• .NET Core 3.0 SDK

Visual Studio Code

• Visual Studio Code
• C# für Visual Studio Code (neueste Version)
• .NET Core 3.0 SDK

In den Visual Studio Code-Anweisungen wird die .NET Core-CLI für ASP.NET Core-Entwicklungsfunktionen wie die Projekterstellung verwendet. Sie können diesen Anweisungen auf jeder beliebigen Plattform (macOS, Linux oder Windows) und in jedem beliebigen Code-Editor folgen. Kleinere Änderungen sind möglicherweise erforderlich, wenn Sie ein anderes Programm als Visual Studio Code verwenden.

Visual Studio für Mac

• Visual Studio für Mac, Version 8.0 oder höher
• .NET Core 3.0 SDK

Erste Schritte mit dem gRPC-Dienst in ASP.NET Core

Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).

Visual Studio

Ausführliche Informationen zum Erstellen eines gRPC-Projekts finden Sie unter Erste Schritte mit gRPC-Diensten.

Visual Studio Code / Visual Studio für Mac

Führen Sie dotnet new grpc -o GrpcGreeter über die Befehlszeile aus.

Hinzufügen von gRPC-Diensten zu einer ASP.NET Core-App

gRPC erfordert das Paket Grpc.AspNetCore.

Konfigurieren von gRPC

In Program.cs:

• gRPC wird mit der Methode AddGrpc aktiviert.
• Jeder gRPC-Dienst wird der Routingpipeline durch die MapGrpcService-Methode hinzugefügt.

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

Wenn Sie möchten, dass Codekommentare in anderen Sprachen als Englisch angezeigt werden, informieren Sie uns in diesem GitHub-Issue.

ASP.NET Core-Middleware und -Features teilen sich die Routingpipeline, daher kann eine App so konfiguriert werden, dass sie zusätzliche Anforderungshandler bedient. Die zusätzlichen Anforderungshandler wie MVC-Controller arbeiten parallel zu den konfigurierten gRPC-Diensten.

Serveroptionen

gRPC-Dienste können von allen integrierten ASP.NET Core-Servern gehostet werden.

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

†IIS erfordert .NET 5 und Windows 10 Build 20300.1000 oder höher.
†HTTP.sys erfordert .NET 5 und Windows 10 Build 19529 oder höher.

Die vorherigen Windows 10-Buildversionen erfordern möglicherweise die Verwendung eines Windows-Insider-Builds.

Weitere Informationen zum Auswählen des richtigen Servers für eine ASP.NET Core-App finden Sie unter Webserverimplementierungen in ASP.NET Core.

Kestrel

Kestrel ist ein plattformübergreifender Webserver für ASP.NET Core. Kestrel legt den Fokus auf Hochleistungs- und Speichernutzung, verfügt jedoch nicht über einige der erweiterten Features in HTTP.sys wie die Portfreigabe.

Kestrel gRPC-Endpunkte:

• Erfordert HTTP/2.
• Sollte mit Transport Layer Security (TLS) gesichert werden.

HTTP/2

gRPC erfordert HTTP/2. gRPC für ASP.NET Core überprüft HttpRequest.Protocol zu HTTP/2.

Kestrelunterstützt HTTP/2 auf den meisten modernen Betriebssystemen. Kestrel-Endpunkte sind standardmäßig für die Unterstützung von HTTP/1.1- und HTTP/2-Verbindungen konfiguriert.

TLS

Die für gRPC verwendeten Kestrel-Endpunkte sollten mit TLS gesichert werden. In der Entwicklung wird ein mit TLS gesicherter Endpunkt automatisch bei https://localhost:5001 erstellt, wenn das ASP.NET Core-Entwicklungszertifikat vorhanden ist. Es ist keine Konfiguration erforderlich. Ein https-Präfix prüft, ob der Kestrel-Endpunkt TLS verwendet.

In der Produktion muss TLS explizit konfiguriert sein. Im folgenden appsettings.json -Beispiel wird ein mit TLS gesicherter HTTP/2-Endpunkt bereitgestellt:

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

Alternativ können Kestrel-Endpunkte in Program.cs konfiguriert werden:

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

Weitere Informationen zum Aktivieren von TLS mit Kestrel finden Sie unter Kestrel-HTTPS-Endpunktkonfiguration.

Protokollaushandlung

TLS wird für mehr als nur die Sicherung der Kommunikation verwendet. Der TLS Application-Layer Protocol Negotiation (ALPN)-Handshake wird zur Aushandlung des Verbindungsprotokolls zwischen dem Client und dem Server verwendet, wenn ein Endpunkt mehrere Protokolle unterstützt. Diese Aushandlung bestimmt, ob die Verbindung HTTP/1.1 oder HTTP/2 verwendet.

Wenn ein HTTP/2-Endpunkt ohne TLS konfiguriert wird, muss bei diesem Endpunkt für ListenOptions.ProtocolsHttpProtocols.Http2 festgelegt werden. Ein Endpunkt mit mehreren Protokollen, z. B. HttpProtocols.Http1AndHttp2, kann ohne die TLS nicht verwendet werden, da keine Aushandlung erfolgt. Für alle Verbindungen zum ungesicherten Endpunkt wird standardmäßig HTTP/1.1 festgelegt, und gRPC-Aufrufe schlagen fehl.

Weitere Informationen zum Aktivieren von HTTP/2 und TLS mit Kestrel finden Sie unter Kestrel-Endpunktkonfiguration.

Hinweis

macOS unterstützt ASP.NET Core gRPC mit TLS vor .NET 8 nicht. Es ist eine zusätzliche Konfiguration erforderlich, um gRPC-Dienste unter macOS erfolgreich auszuführen, wenn .NET 7 oder früher verwendet wird. Weitere Informationen finden Sie unter ASP.NET Core gRPC-App kann unter macOS nicht gestartet werden.

IIS

IIS (Internet Information Services, Internetinformationsdienste) stellen einen flexiblen, sicheren und verwaltbaren Webserver für das Hosten von Web-Apps (einschließlich ASP.NET Core) dar. .NET 5 und Windows 10, Build 20300.1000 oder höher, sind erforderlich, um gRPC-Dienste mit IIS zu hosten. Dies kann die Verwendung eines Windows-Insider-Builds erfordern.

IIS muss für die Verwendung von TLS und HTTP/2 konfiguriert sein. Weitere Informationen finden Sie unter Verwenden von ASP.NET Core mit HTTP/2 in IIS.

HTTP.sys

HTTP.sys ist ein Webserver für ASP.NET Core, der nur unter Windows ausgeführt werden kann. .NET 5 und Windows 10, Build 19529 oder höher, sind erforderlich, um gRPC-Dienste mit HTTP.sys zu hosten. Dies kann die Verwendung eines Windows-Insider-Builds erfordern.

HTTP.sys muss für die Verwendung von TLS und HTTP/2 konfiguriert sein. Weitere Informationen finden Sie unter HTTP/2-Unterstützung des HTTP.sys-Webservers.

Integration mit ASP.NET Core-APIs

gRPC-Dienste haben vollen Zugriff auf die ASP.NET Core-Features wie Abhängigkeitsinjektion und Protokollierung. So kann die Dienstimplementierung z. B. einen Protokollierungsdienst aus dem Container der Abhängigkeitsinjektion über den Konstruktor auflösen:

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

Standardmäßig kann die gRPC-Dienstimplementierung andere Abhängigkeitsinjektionsdienste mit beliebiger Lebensdauer (Singleton, Bereichsbezogen oder Vorübergehend) auflösen.

Auflösen von HttpContext in gRPC-Methoden

Die gRPC-API bietet Zugriff auf einige HTTP/2-Nachrichtendaten, z. B. Methode, Host, Header und Nachspanne. Der Zugriff erfolgt über das Argument ServerCallContext, das an jede gRPC-Methode übergeben wird:

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

ServerCallContext bietet nicht in allen ASP.NET-APIs vollen Zugriff auf HttpContext. Die GetHttpContext-Erweiterungsmethode bietet vollen Zugriff auf HttpContext, das die zugrunde liegende HTTP/2-Nachricht in ASP.NET-APIs darstellt:

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

Zusätzliche Ressourcen

• Erstellen eines .NET Core-gRPC-Clients und -Servers in ASP.NET Core
• Übersicht für gRPC auf .NET
• gRPC-Dienste mit C#
• Kestrel-Webserver in ASP.NET Core