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.

Warnung

AsP.NET Core gRPC hat zusätzliche Anforderungen für die Verwendung mit Azure App Service oder IIS. Weitere Informationen dazu, wo gRPC verwendet werden kann, finden Sie unter gRPC auf .NET-unterstützten Plattformen.

Voraussetzungen

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

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

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

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

gRPC erfordert das Paket Grpc.AspNetCore.

Konfigurieren von gRPC

In Startup.cs:

  • gRPC wird mit der Methode AddGrpc aktiviert.
  • Jeder gRPC-Dienst wird der Routingpipeline durch die MapGrpcService-Methode hinzugefügt.
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>();
        });
    }
}

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 bietet die beste Leistung und Arbeitsspeicherauslastung, verfügt jedoch nicht über einige der erweiterten Features in HTTP.sys wie Portfreigabe.

Kestrel gRPC-Endpunkte:

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:

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

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 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 nicht. Zum erfolgreichen Ausführen von gRPC-Diensten unter macOS ist eine zusätzliche Konfiguration erforderlich. 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.

Kestrel

Kestrel ist ein plattformübergreifender Webserver für ASP.NET Core. Kestrel bietet die beste Leistung und Arbeitsspeicherauslastung, verfügt jedoch nicht über einige der erweiterten Features in HTTP.sys wie Portfreigabe.

Kestrel gRPC-Endpunkte:

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:

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

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 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 nicht. Zum erfolgreichen Ausführen von gRPC-Diensten unter macOS ist eine zusätzliche Konfiguration erforderlich. Weitere Informationen finden Sie unter ASP.NET Core gRPC-App kann unter macOS nicht gestartet werden.

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