Freigeben über

gRPC-Dienste mit ASP.NET Core

  • Artikel

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der Supportrichtlinie für .NET und .NET Core. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

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

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 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†

†Erfordert .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher.

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:

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 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit IIS zu hosten.

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 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit HTTP.sys zu hosten.

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.

Hosten von gRPC in Projekten ohne ASP.NET Core

Ein ASP.NET Core-gRPC-Server wird normalerweise aus der gRPC-Vorlage erstellt. Die von der Vorlage erstellte Projektdatei verwendet Microsoft.NET.SDK.Web als 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>

Der Microsoft.NET.SDK.Web SDK-Wert fügt automatisch einen Verweis auf das ASP.NET Core-Framework hinzu. Der Verweis ermöglicht der App die Verwendung von ASP.NET Core-Typen, die zum Hosten eines Servers erforderlich sind.

Sie können einen gRPC-Server zu Projekten ohne ASP.NET Core mit den folgenden Projektdateieinstellungen hinzufügen:

<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>

Die obige Projektdatei:

  • Verwendet nicht Microsoft.NET.SDK.Web als SDK.
  • Fügt einen Frameworkverweis auf Microsoft.AspNetCore.App hinzu
    • Durch den Frameworkverweis können Apps, die nicht unter ASP.NET Core ausgeführt werden (z. B. Windows-Dienste, WPF-Apps oder WinForms-Apps), ASP.NET Core verwenden.
    • Die App kann jetzt ASP.NET Core-APIs verwenden, um einen ASP.NET Core-Server zu starten.
  • Fügt gRPC-Anforderungen hinzu:

Weitere Informationen zum Verwenden der Microsoft.AspNetCore.App-Frameworkreferenz finden Sie unter Verwenden des freigegebenen ASP.NET Core-Frameworks.

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

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

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 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†

†Erfordert .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher.

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:

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 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit IIS zu hosten.

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 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit HTTP.sys zu hosten.

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.

Hosten von gRPC in Projekten ohne ASP.NET Core

Ein ASP.NET Core-gRPC-Server wird normalerweise aus der gRPC-Vorlage erstellt. Die von der Vorlage erstellte Projektdatei verwendet Microsoft.NET.SDK.Web als 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>

Der Microsoft.NET.SDK.Web SDK-Wert fügt automatisch einen Verweis auf das ASP.NET Core-Framework hinzu. Der Verweis ermöglicht der App die Verwendung von ASP.NET Core-Typen, die zum Hosten eines Servers erforderlich sind.

Sie können einen gRPC-Server zu Projekten ohne ASP.NET Core mit den folgenden Projektdateieinstellungen hinzufügen:

<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>

Die obige Projektdatei:

  • Verwendet nicht Microsoft.NET.SDK.Web als SDK.
  • Fügt einen Frameworkverweis auf Microsoft.AspNetCore.App hinzu
    • Durch den Frameworkverweis können Apps, die nicht unter ASP.NET Core ausgeführt werden (z. B. Windows-Dienste, WPF-Apps oder WinForms-Apps), ASP.NET Core verwenden.
    • Die App kann jetzt ASP.NET Core-APIs verwenden, um einen ASP.NET Core-Server zu starten.
  • Fügt gRPC-Anforderungen hinzu:

Weitere Informationen zum Verwenden der Microsoft.AspNetCore.App-Frameworkreferenz finden Sie unter Verwenden des freigegebenen ASP.NET Core-Frameworks.

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

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

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 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†

†Erfordert .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher.

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:

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 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit IIS zu hosten.

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 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit HTTP.sys zu hosten.

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.

Hosten von gRPC in Projekten ohne ASP.NET Core

Ein ASP.NET Core-gRPC-Server wird normalerweise aus der gRPC-Vorlage erstellt. Die von der Vorlage erstellte Projektdatei verwendet Microsoft.NET.SDK.Web als 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>

Der Microsoft.NET.SDK.Web SDK-Wert fügt automatisch einen Verweis auf das ASP.NET Core-Framework hinzu. Der Verweis ermöglicht der App die Verwendung von ASP.NET Core-Typen, die zum Hosten eines Servers erforderlich sind.

Sie können einen gRPC-Server zu Projekten ohne ASP.NET Core mit den folgenden Projektdateieinstellungen hinzufügen:

<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>

Die obige Projektdatei:

  • Verwendet nicht Microsoft.NET.SDK.Web als SDK.
  • Fügt einen Frameworkverweis auf Microsoft.AspNetCore.App hinzu
    • Durch den Frameworkverweis können Apps, die nicht unter ASP.NET Core ausgeführt werden (z. B. Windows-Dienste, WPF-Apps oder WinForms-Apps), ASP.NET Core verwenden.
    • Die App kann jetzt ASP.NET Core-APIs verwenden, um einen ASP.NET Core-Server zu starten.
  • Fügt gRPC-Anforderungen hinzu:

Weitere Informationen zum Verwenden der Microsoft.AspNetCore.App-Frameworkreferenz finden Sie unter Verwenden des freigegebenen ASP.NET Core-Frameworks.

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

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

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†

†Erfordert .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher.

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:

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 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 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit IIS zu hosten.

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 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit HTTP.sys zu hosten.

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.

Hosten von gRPC in Projekten ohne ASP.NET Core

Ein ASP.NET Core-gRPC-Server wird normalerweise aus der gRPC-Vorlage erstellt. Die von der Vorlage erstellte Projektdatei verwendet Microsoft.NET.SDK.Web als 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>

Der Microsoft.NET.SDK.Web SDK-Wert fügt automatisch einen Verweis auf das ASP.NET Core-Framework hinzu. Der Verweis ermöglicht der App die Verwendung von ASP.NET Core-Typen, die zum Hosten eines Servers erforderlich sind.

Sie können einen gRPC-Server zu Projekten ohne ASP.NET Core mit den folgenden Projektdateieinstellungen hinzufügen:

<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>

Die obige Projektdatei:

  • Verwendet nicht Microsoft.NET.SDK.Web als SDK.
  • Fügt einen Frameworkverweis auf Microsoft.AspNetCore.App hinzu
    • Durch den Frameworkverweis können Apps, die nicht unter ASP.NET Core ausgeführt werden (z. B. Windows-Dienste, WPF-Apps oder WinForms-Apps), ASP.NET Core verwenden.
    • Die App kann jetzt ASP.NET Core-APIs verwenden, um einen ASP.NET Core-Server zu starten.
  • Fügt gRPC-Anforderungen hinzu:

Weitere Informationen zum Verwenden der Microsoft.AspNetCore.App-Frameworkreferenz finden Sie unter Verwenden des freigegebenen ASP.NET Core-Frameworks.

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

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

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†

†Erfordert .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher.

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:

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 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.

Hosten von gRPC in Projekten ohne ASP.NET Core

Ein ASP.NET Core-gRPC-Server wird normalerweise aus der gRPC-Vorlage erstellt. Die von der Vorlage erstellte Projektdatei verwendet Microsoft.NET.SDK.Web als 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>

Der Microsoft.NET.SDK.Web SDK-Wert fügt automatisch einen Verweis auf das ASP.NET Core-Framework hinzu. Der Verweis ermöglicht der App die Verwendung von ASP.NET Core-Typen, die zum Hosten eines Servers erforderlich sind.

Sie können einen gRPC-Server zu Projekten ohne ASP.NET Core mit den folgenden Projektdateieinstellungen hinzufügen:

<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>

Die obige Projektdatei:

  • Verwendet nicht Microsoft.NET.SDK.Web als SDK.
  • Fügt einen Frameworkverweis auf Microsoft.AspNetCore.App hinzu
    • Durch den Frameworkverweis können Apps, die nicht unter ASP.NET Core ausgeführt werden (z. B. Windows-Dienste, WPF-Apps oder WinForms-Apps), ASP.NET Core verwenden.
    • Die App kann jetzt ASP.NET Core-APIs verwenden, um einen ASP.NET Core-Server zu starten.
  • Fügt gRPC-Anforderungen hinzu:

Weitere Informationen zum Verwenden der Microsoft.AspNetCore.App-Frameworkreferenz finden Sie unter Verwenden des freigegebenen ASP.NET Core-Frameworks.

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

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

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†

†Erfordert .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher.

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:

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 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.

Hosten von gRPC in Projekten ohne ASP.NET Core

Ein ASP.NET Core-gRPC-Server wird normalerweise aus der gRPC-Vorlage erstellt. Die von der Vorlage erstellte Projektdatei verwendet Microsoft.NET.SDK.Web als 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>

Der Microsoft.NET.SDK.Web SDK-Wert fügt automatisch einen Verweis auf das ASP.NET Core-Framework hinzu. Der Verweis ermöglicht der App die Verwendung von ASP.NET Core-Typen, die zum Hosten eines Servers erforderlich sind.

Sie können einen gRPC-Server zu Projekten ohne ASP.NET Core mit den folgenden Projektdateieinstellungen hinzufügen:

<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>

Die obige Projektdatei:

  • Verwendet nicht Microsoft.NET.SDK.Web als SDK.
  • Fügt einen Frameworkverweis auf Microsoft.AspNetCore.App hinzu
    • Durch den Frameworkverweis können Apps, die nicht unter ASP.NET Core ausgeführt werden (z. B. Windows-Dienste, WPF-Apps oder WinForms-Apps), ASP.NET Core verwenden.
    • Die App kann jetzt ASP.NET Core-APIs verwenden, um einen ASP.NET Core-Server zu starten.
  • Fügt gRPC-Anforderungen hinzu:

Weitere Informationen zum Verwenden der Microsoft.AspNetCore.App-Frameworkreferenz finden Sie unter Verwenden des freigegebenen ASP.NET Core-Frameworks.

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