Delen via


gRPC-services met ASP.NET Core

Notitie

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie de .NET- en .NET Core-ondersteuningsbeleidvoor meer informatie. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Belangrijk

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikelvoor de huidige release.

In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.

Voorwaarden

Aan de slag met gRPC-service in ASP.NET Core

voorbeeldcode weergeven of downloaden (het downloaden van).

Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.

gRPC-services toevoegen aan een ASP.NET Core-app

gRPC vereist het pakket Grpc.AspNetCore.

gRPC configureren

In Program.cs:

  • gRPC is ingeschakeld met de methode AddGrpc.
  • Elke gRPC-service wordt via de MapGrpcService methode aan de routeringspijplijn toegevoegd.
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();

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

ASP.NET Core middleware en -functies delen de routeringspijplijn. Daarom kan een app worden geconfigureerd voor extra aanvraaghandlers. De aanvullende aanvraaghandlers, zoals MVC-controllers, werken parallel met de geconfigureerde gRPC-services.

Serveropties

gRPC-services kunnen worden gehost door alle ingebouwde ASP.NET Core-servers.

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

†Vereist .NET 5 en Windows 11 Build 22000, of Windows Server 2022 Build 20348 of hoger.

Zie webserver-implementaties in ASP.NET Core-voor meer informatie over het kiezen van de juiste server voor een ASP.NET Core-app.

Kestrel

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is gericht op hoge prestaties en geheugengebruik, maar heeft geen enkele van de geavanceerde functies in HTTP.sys, zoals het delen van poorten.

Kestrel gRPC-eindpunten:

  • HTTP/2 vereisen.
  • Moet worden beveiligd met TLS-(Transport Layer Security).

HTTP/2

gRPC vereist HTTP/2. gRPC voor ASP.NET Core controleert of HttpRequest.ProtocolHTTP/2is.

Kestrel ondersteunt HTTP/2- op de meeste moderne besturingssystemen. Kestrel eindpunten zijn standaard geconfigureerd ter ondersteuning van HTTP/1.1- en HTTP/2-verbindingen.

TLS

Kestrel eindpunten die worden gebruikt voor gRPC, moeten worden beveiligd met TLS. In ontwikkeling wordt automatisch een eindpunt gemaakt dat is beveiligd met TLS op https://localhost:5001 wanneer het ASP.NET Core-ontwikkelingscertificaat aanwezig is. Er is geen configuratie vereist. Een https voorvoegsel controleert of het Kestrel-eindpunt TLS gebruikt.

In productie moet TLS expliciet worden geconfigureerd. In het volgende appsettings.json voorbeeld wordt een HTTP/2-eindpunt dat is beveiligd met TLS opgegeven:

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

U kunt ook Kestrel eindpunten configureren in 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>");
    });
});

Zie Kestrel https-eindpuntconfiguratievoor meer informatie over het inschakelen van TLS met Kestrel.

Protocolonderhandeling

TLS wordt gebruikt voor meer dan het beveiligen van communicatie. De ALPN -handshake (TLSApplication-Layer Protocol Negotiate) wordt gebruikt om te onderhandelen over het verbindingsprotocol tussen de client en de server wanneer een eindpunt meerdere protocollen ondersteunt. Deze onderhandeling bepaalt of de verbinding GEBRUIKMAAKT van HTTP/1.1 of HTTP/2.

Als een HTTP/2-eindpunt is geconfigureerd zonder TLS, moet het eindpunt ListenOptions.Protocols worden ingesteld op HttpProtocols.Http2. Een eindpunt met meerdere protocollen, zoals HttpProtocols.Http1AndHttp2, kan bijvoorbeeld niet worden gebruikt zonder TLS omdat er geen onderhandeling is. Alle verbindingen met het onbeveiligde eindpunt worden standaard ingesteld op HTTP/1.1 en gRPC-aanroepen mislukken.

Zie Kestrel eindpuntconfiguratievoor meer informatie over het inschakelen van HTTP/2 en TLS met Kestrel.

Notitie

macOS biedt geen ondersteuning voor ASP.NET Core gRPC met TLS vóór .NET 8. Aanvullende configuratie is vereist voor het uitvoeren van gRPC-services op macOS wanneer u .NET 7 of eerder gebruikt. Zie Kan ASP.NET Core gRPC-app niet starten op macOS-voor meer informatie.

IIS

IIS- (Internet Information Services) is een flexibele, veilige en beheerbare webserver voor het hosten van web-apps, waaronder ASP.NET Core. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met IIS.

IIS moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Zie Gebruik ASP.NET Core met HTTP/2 op IIS-voor meer informatie.

HTTP.sys

HTTP.sys is een webserver voor ASP.NET Core die alleen in Windows wordt uitgevoerd. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met HTTP.sys.

HTTP.sys moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Voor meer informatie, zie HTTP.sys webserverondersteuning HTTP/2.

Host gRPC in non-ASP.NET Core-projecten

Een ASP.NET Core gRPC-server wordt doorgaans gemaakt op basis van de gRPC-sjabloon. Het projectbestand dat door de sjabloon is gemaakt, gebruikt 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>

De Microsoft.NET.SDK.Web SDK-waarde voegt automatisch een verwijzing toe naar het ASP.NET Core-framework. Met de verwijzing kan de app gebruikmaken van ASP.NET Core-typen die zijn vereist voor het hosten van een server.

U kunt een gRPC-server toevoegen aan non-ASP.NET Core-projecten met de volgende projectbestandsinstellingen:

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

Het voorgaande projectbestand:

  • Maakt geen gebruik van Microsoft.NET.SDK.Web als sdk.
  • Voegt een frameworkreferentie toe aan Microsoft.AspNetCore.App.
    • Met de frameworkreferentie kunnen non-ASP.NET Core-apps, zoals Windows Services, WPF-apps of WinForms-apps, ASP.NET Core-API's gebruiken.
    • De app kan nu ASP.NET Core-API's gebruiken om een ASP.NET Core-server te starten.
  • Voegt gRPC-vereisten toe:

Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App frameworkreferentie, zie Gebruik het gedeelde frameworkvan ASP.NET Core.

Integratie met ASP.NET Core-API's

gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals afhankelijkheidsinjectie (DI) en logboekregistratie. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen.

Constructorinjectie:

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;

    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }
}

Primaire constructorinjectie (.NET 8 of hoger):

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

Standaard kan de gRPC-service-implementatie andere DI-services oplossen met elke levensduur (Singleton, Scoped of Tijdelijk).

HttpContext in gRPC-methoden oplossen

De gRPC-API biedt toegang tot sommige HTTP/2-berichtgegevens, zoals de methode, host, header en trailers. Access wordt uitgevoerd via het ServerCallContext argument dat wordt doorgegeven aan elke gRPC-methode:

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

ServerCallContext biedt geen volledige toegang tot HttpContext in alle ASP.NET API's. De GetHttpContext-extensiemethode biedt volledige toegang tot de HttpContext dat het onderliggende HTTP/2-bericht in ASP.NET API's vertegenwoordigt.

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

Aanvullende informatiebronnen

In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.

Voorwaarden

Aan de slag met gRPC-service in ASP.NET Core

Voorbeeldcode bekijken of downloaden (hoe te downloaden).

Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.

gRPC-services toevoegen aan een ASP.NET Core-app

gRPC vereist het pakket Grpc.AspNetCore.

gRPC configureren

In Program.cs:

  • gRPC is ingeschakeld met de methode AddGrpc.
  • Elke gRPC-service wordt via de MapGrpcService methode aan de routeringspijplijn toegevoegd.
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();

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

ASP.NET Core middleware en -functies delen de routeringspijplijn. Daarom kan een app worden geconfigureerd voor extra aanvraaghandlers. De aanvullende aanvraaghandlers, zoals MVC-controllers, werken parallel met de geconfigureerde gRPC-services.

Serveropties

gRPC-services kunnen worden gehost door alle ingebouwde ASP.NET Core-servers.

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

†Vereist .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger.

Zie webserver-implementaties in ASP.NET Core-voor meer informatie over het kiezen van de juiste server voor een ASP.NET Core-app.

Kestrel

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is gericht op hoge prestaties en geheugengebruik, maar heeft geen enkele van de geavanceerde functies in HTTP.sys, zoals het delen van poorten.

Kestrel gRPC-eindpunten:

  • HTTP/2 vereisen.
  • Moet worden beveiligd met TLS-(Transport Layer Security).

HTTP/2

gRPC vereist HTTP/2. gRPC voor ASP.NET Core valideert dat HttpRequest.ProtocolHTTP/2is.

Kestrel ondersteunt HTTP/2- op de meeste moderne besturingssystemen. Kestrel eindpunten zijn standaard geconfigureerd ter ondersteuning van HTTP/1.1- en HTTP/2-verbindingen.

TLS

Kestrel eindpunten die worden gebruikt voor gRPC, moeten worden beveiligd met TLS. In ontwikkeling wordt automatisch een eindpunt gemaakt dat is beveiligd met TLS op https://localhost:5001 wanneer het ASP.NET Core-ontwikkelingscertificaat aanwezig is. Er is geen configuratie vereist. Een https voorvoegsel controleert of het Kestrel-eindpunt TLS gebruikt.

In productie moet TLS expliciet worden geconfigureerd. In het volgende appsettings.json voorbeeld wordt een HTTP/2-eindpunt dat is beveiligd met TLS opgegeven:

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

U kunt ook Kestrel eindpunten configureren in 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>");
    });
});

Zie Kestrel https-eindpuntconfiguratievoor meer informatie over het inschakelen van TLS met Kestrel.

Protocolonderhandeling

TLS wordt gebruikt voor meer dan het beveiligen van communicatie. De ALPN -handshake (TLSApplication-Layer Protocol Negotiate) wordt gebruikt om te onderhandelen over het verbindingsprotocol tussen de client en de server wanneer een eindpunt meerdere protocollen ondersteunt. Deze onderhandeling bepaalt of de verbinding GEBRUIKMAAKT van HTTP/1.1 of HTTP/2.

Als een HTTP/2-eindpunt is geconfigureerd zonder TLS, moet het eindpunt ListenOptions.Protocols worden ingesteld op HttpProtocols.Http2. Een eindpunt met meerdere protocollen, zoals HttpProtocols.Http1AndHttp2, kan bijvoorbeeld niet worden gebruikt zonder TLS omdat er geen onderhandeling is. Alle verbindingen met het onbeveiligde eindpunt worden standaard ingesteld op HTTP/1.1 en gRPC-aanroepen mislukken.

Zie Kestrel eindpuntconfiguratievoor meer informatie over het inschakelen van HTTP/2 en TLS met Kestrel.

Notitie

macOS biedt geen ondersteuning voor ASP.NET Core gRPC met TLS vóór .NET 8. Aanvullende configuratie is vereist voor het uitvoeren van gRPC-services op macOS wanneer u .NET 7 of eerder gebruikt. Zie Kan ASP.NET Core gRPC-app niet starten op macOS-voor meer informatie.

IIS

IIS- (Internet Information Services) is een flexibele, veilige en beheerbare webserver voor het hosten van web-apps, waaronder ASP.NET Core. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met IIS.

IIS moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Zie Gebruik ASP.NET Core met HTTP/2 op IIS-voor meer informatie.

HTTP.sys

HTTP.sys is een webserver voor ASP.NET Core die alleen in Windows wordt uitgevoerd. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met HTTP.sys.

HTTP.sys moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Voor meer informatie, zie HTTP.sys webserver HTTP/2-ondersteuning.

Host gRPC in non-ASP.NET Core-projecten

Een ASP.NET Core gRPC-server wordt doorgaans gemaakt op basis van de gRPC-sjabloon. Het projectbestand dat door de sjabloon is gemaakt, gebruikt 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>

De Microsoft.NET.SDK.Web SDK-waarde voegt automatisch een verwijzing toe naar het ASP.NET Core-framework. Met de verwijzing kan de app gebruikmaken van ASP.NET Core-typen die zijn vereist voor het hosten van een server.

U kunt een gRPC-server toevoegen aan non-ASP.NET Core-projecten met de volgende projectbestandsinstellingen:

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

Het voorgaande projectbestand:

  • Maakt geen gebruik van Microsoft.NET.SDK.Web als sdk.
  • Voegt een frameworkreferentie toe aan Microsoft.AspNetCore.App.
    • Met de frameworkreferentie kunnen non-ASP.NET Core-apps, zoals Windows Services, WPF-apps of WinForms-apps, ASP.NET Core-API's gebruiken.
    • De app kan nu ASP.NET Core-API's gebruiken om een ASP.NET Core-server te starten.
  • Voegt gRPC-vereisten toe:

Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App frameworkreferentie, zie Het gedeelde frameworkvan ASP.NET Core gebruiken.

Integratie met ASP.NET Core-API's

gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:

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

Standaard kan de gRPC-service-implementatie andere DI-services oplossen met elke levensduur (Singleton, Scoped of Tijdelijk).

HttpContext in gRPC-methoden oplossen

De gRPC-API biedt toegang tot sommige HTTP/2-berichtgegevens, zoals de methode, host, header en trailers. Access wordt uitgevoerd via het ServerCallContext argument dat wordt doorgegeven aan elke gRPC-methode:

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

ServerCallContext biedt geen volledige toegang tot HttpContext in alle ASP.NET API's. De GetHttpContext-extensiemethode biedt volledige toegang tot de HttpContext, die het onderliggende HTTP/2-bericht in ASP.NET API's vertegenwoordigt.

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

Aanvullende informatiebronnen

In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.

Voorwaarden

Aan de slag met gRPC-service in ASP.NET Core

Voorbeeldcode bekijken of downloaden (hoe te downloaden).

Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.

gRPC-services toevoegen aan een ASP.NET Core-app

gRPC vereist het pakket Grpc.AspNetCore.

gRPC configureren

In Program.cs:

  • gRPC is ingeschakeld met de methode AddGrpc.
  • Elke gRPC-service wordt via de MapGrpcService methode aan de routeringspijplijn toegevoegd.
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();

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

ASP.NET Core middleware en -functies delen de routeringspijplijn. Daarom kan een app worden geconfigureerd voor extra aanvraaghandlers. De aanvullende aanvraaghandlers, zoals MVC-controllers, werken parallel met de geconfigureerde gRPC-services.

Serveropties

gRPC-services kunnen worden gehost door alle ingebouwde ASP.NET Core-servers.

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

†Requires .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger.

Zie webserver-implementaties in ASP.NET Core-voor meer informatie over het kiezen van de juiste server voor een ASP.NET Core-app.

Kestrel

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is gericht op hoge prestaties en geheugengebruik, maar heeft geen enkele van de geavanceerde functies in HTTP.sys, zoals het delen van poorten.

Kestrel gRPC-eindpunten:

  • Vereis HTTP/2.
  • Moet worden beveiligd met TLS-(Transport Layer Security).

HTTP/2

gRPC vereist HTTP/2. gRPC voor ASP.NET Core valideert HttpRequest.Protocol is HTTP/2.

Kestrel ondersteunt HTTP/2- op de meeste moderne besturingssystemen. Kestrel eindpunten zijn standaard geconfigureerd ter ondersteuning van HTTP/1.1- en HTTP/2-verbindingen.

TLS

Kestrel eindpunten die worden gebruikt voor gRPC, moeten worden beveiligd met TLS. In ontwikkeling wordt automatisch een eindpunt gemaakt dat is beveiligd met TLS op https://localhost:5001 wanneer het ASP.NET Core-ontwikkelingscertificaat aanwezig is. Er is geen configuratie vereist. Een https voorvoegsel controleert of het Kestrel-eindpunt TLS gebruikt.

In productie moet TLS expliciet worden geconfigureerd. In het volgende appsettings.json voorbeeld wordt een HTTP/2-eindpunt dat is beveiligd met TLS opgegeven:

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

U kunt ook Kestrel eindpunten configureren in 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>");
    });
});

Zie Kestrel https-eindpuntconfiguratievoor meer informatie over het inschakelen van TLS met Kestrel.

Protocolonderhandeling

TLS wordt gebruikt voor meer dan het beveiligen van communicatie. De ALPN -handshake (TLSApplication-Layer Protocol Negotiate) wordt gebruikt om te onderhandelen over het verbindingsprotocol tussen de client en de server wanneer een eindpunt meerdere protocollen ondersteunt. Deze onderhandeling bepaalt of de verbinding GEBRUIKMAAKT van HTTP/1.1 of HTTP/2.

Als een HTTP/2-eindpunt is geconfigureerd zonder TLS, moet het eindpunt ListenOptions.Protocols worden ingesteld op HttpProtocols.Http2. Een eindpunt met meerdere protocollen, zoals HttpProtocols.Http1AndHttp2, kan bijvoorbeeld niet worden gebruikt zonder TLS omdat er geen onderhandeling is. Alle verbindingen met het onbeveiligde eindpunt worden standaard ingesteld op HTTP/1.1 en gRPC-aanroepen mislukken.

Zie Kestrel eindpuntconfiguratievoor meer informatie over het inschakelen van HTTP/2 en TLS met Kestrel.

Notitie

macOS biedt geen ondersteuning voor ASP.NET Core gRPC met TLS vóór .NET 8. Aanvullende configuratie is vereist voor het uitvoeren van gRPC-services op macOS wanneer u .NET 7 of eerder gebruikt. Zie Kan ASP.NET Core gRPC-app niet starten op macOS-voor meer informatie.

IIS

IIS- (Internet Information Services) is een flexibele, veilige en beheerbare webserver voor het hosten van web-apps, waaronder ASP.NET Core. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met IIS.

IIS moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Zie Gebruik ASP.NET Core met HTTP/2 op IIS-voor meer informatie.

HTTP.sys

HTTP.sys is een webserver voor ASP.NET Core die alleen in Windows wordt uitgevoerd. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met HTTP.sys.

HTTP.sys moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Voor meer informatie, zie HTTP.sys webserver HTTP/2-ondersteuning.

Host gRPC in non-ASP.NET Core-projecten

Een ASP.NET Core gRPC-server wordt doorgaans gemaakt op basis van de gRPC-sjabloon. Het projectbestand dat door de sjabloon is gemaakt, gebruikt 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>

De Microsoft.NET.SDK.Web SDK-waarde voegt automatisch een verwijzing toe naar het ASP.NET Core-framework. Met de verwijzing kan de app gebruikmaken van ASP.NET Core-typen die zijn vereist voor het hosten van een server.

U kunt een gRPC-server toevoegen aan non-ASP.NET Core-projecten met de volgende projectbestandsinstellingen:

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

Het voorgaande projectbestand:

  • Maakt geen gebruik van Microsoft.NET.SDK.Web als sdk.
  • Voegt een frameworkreferentie toe aan Microsoft.AspNetCore.App.
    • Met de frameworkreferentie kunnen non-ASP.NET Core-apps, zoals Windows Services, WPF-apps of WinForms-apps, ASP.NET Core-API's gebruiken.
    • De app kan nu ASP.NET Core-API's gebruiken om een ASP.NET Core-server te starten.
  • Voegt gRPC-vereisten toe:

Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App frameworkreferentie, zie Het gedeelde frameworkvan ASP.NET Core gebruiken.

Integratie met ASP.NET Core-API's

gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:

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

Standaard kan de gRPC-service-implementatie andere DI-services met elke levensduur (Singleton, Scoped of Tijdelijk) resolveren.

HttpContext in gRPC-methoden oplossen

De gRPC-API biedt toegang tot sommige HTTP/2-berichtgegevens, zoals de methode, host, header en trailers. Access wordt uitgevoerd via het ServerCallContext argument dat wordt doorgegeven aan elke gRPC-methode:

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

ServerCallContext biedt geen volledige toegang tot HttpContext in alle ASP.NET API's. De GetHttpContext-extensiemethode biedt volledige toegang tot de HttpContext, die het onderliggende HTTP/2-bericht in ASP.NET API's vertegenwoordigt.

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

Aanvullende informatiebronnen

In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.

Voorwaarden

Aan de slag met gRPC-service in ASP.NET Core

voorbeeldcode weergeven of downloaden (hoe te downloaden).

Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.

gRPC-services toevoegen aan een ASP.NET Core-app

gRPC vereist het pakket Grpc.AspNetCore.

gRPC configureren

In Startup.cs:

  • gRPC is ingeschakeld met de methode AddGrpc.
  • Elke gRPC-service wordt via de MapGrpcService methode aan de routeringspijplijn toegevoegd.
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>();
        });
    }
}

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

ASP.NET Core middleware en -functies delen de routeringspijplijn. Daarom kan een app worden geconfigureerd voor extra aanvraaghandlers. De aanvullende aanvraaghandlers, zoals MVC-controllers, werken parallel met de geconfigureerde gRPC-services.

Serveropties

gRPC-services kunnen worden gehost door alle ingebouwde ASP.NET Core-servers.

  • Kestrel
  • Testserver
  • IIS†
  • HTTP.sys†

†Requires .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger.

Zie webserver-implementaties in ASP.NET Core-voor meer informatie over het kiezen van de juiste server voor een ASP.NET Core-app.

Kestrel

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is gericht op hoge prestaties en geheugengebruik, maar heeft geen enkele van de geavanceerde functies in HTTP.sys, zoals het delen van poorten.

Kestrel gRPC-eindpunten:

  • HTTP/2 vereisen.
  • Moet worden beveiligd met TLS-(Transport Layer Security).

HTTP/2

gRPC vereist HTTP/2. gRPC voor ASP.NET Core valideert dat HttpRequest.Protocol is HTTP/2.

Kestrel ondersteunt HTTP/2- op de meeste moderne besturingssystemen. Kestrel eindpunten zijn standaard geconfigureerd ter ondersteuning van HTTP/1.1- en HTTP/2-verbindingen.

TLS

Kestrel eindpunten die worden gebruikt voor gRPC, moeten worden beveiligd met TLS. In ontwikkeling wordt automatisch een eindpunt gemaakt dat is beveiligd met TLS op https://localhost:5001 wanneer het ASP.NET Core-ontwikkelingscertificaat aanwezig is. Er is geen configuratie vereist. Een https voorvoegsel controleert of het Kestrel-eindpunt TLS gebruikt.

In productie moet TLS expliciet worden geconfigureerd. In het volgende appsettings.json voorbeeld wordt een HTTP/2-eindpunt dat is beveiligd met TLS opgegeven:

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

U kunt ook Kestrel eindpunten configureren in 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>();
        });

Zie Kestrel https-eindpuntconfiguratievoor meer informatie over het inschakelen van TLS met Kestrel.

Protocolonderhandeling

TLS wordt gebruikt voor meer dan het beveiligen van communicatie. De ALPN -handshake (TLSApplication-Layer Protocol Negotiate) wordt gebruikt om te onderhandelen over het verbindingsprotocol tussen de client en de server wanneer een eindpunt meerdere protocollen ondersteunt. Deze onderhandeling bepaalt of de verbinding GEBRUIKMAAKT van HTTP/1.1 of HTTP/2.

Als een HTTP/2-eindpunt is geconfigureerd zonder TLS, moet het eindpunt ListenOptions.Protocols worden ingesteld op HttpProtocols.Http2. Een eindpunt met meerdere protocollen, zoals HttpProtocols.Http1AndHttp2, kan bijvoorbeeld niet worden gebruikt zonder TLS omdat er geen onderhandeling is. Alle verbindingen met het onbeveiligde eindpunt worden standaard ingesteld op HTTP/1.1 en gRPC-aanroepen mislukken.

Zie Kestrel eindpuntconfiguratievoor meer informatie over het inschakelen van HTTP/2 en TLS met Kestrel.

Notitie

macOS biedt geen ondersteuning voor ASP.NET Core gRPC met TLS vóór .NET 8. Aanvullende configuratie is vereist voor het uitvoeren van gRPC-services op macOS wanneer u .NET 7 of eerder gebruikt. Zie Kan ASP.NET Core gRPC-app niet starten op macOS-voor meer informatie.

IIS

IIS- (Internet Information Services) is een flexibele, veilige en beheerbare webserver voor het hosten van web-apps, waaronder ASP.NET Core. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met IIS.

IIS moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Zie Gebruik ASP.NET Core met HTTP/2 op IIS-voor meer informatie.

HTTP.sys

HTTP.sys is een webserver voor ASP.NET Core die alleen in Windows wordt uitgevoerd. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met HTTP.sys.

HTTP.sys moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Voor meer informatie, zie HTTP.sys webserver HTTP/2-ondersteuning.

Host gRPC in non-ASP.NET Core-projecten

Een ASP.NET Core gRPC-server wordt doorgaans gemaakt op basis van de gRPC-sjabloon. Het projectbestand dat door de sjabloon is gemaakt, gebruikt 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>

De Microsoft.NET.SDK.Web SDK-waarde voegt automatisch een verwijzing toe naar het ASP.NET Core-framework. Met de verwijzing kan de app gebruikmaken van ASP.NET Core-typen die zijn vereist voor het hosten van een server.

U kunt een gRPC-server toevoegen aan non-ASP.NET Core-projecten met de volgende projectbestandsinstellingen:

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

Het voorgaande projectbestand:

  • Maakt geen gebruik van Microsoft.NET.SDK.Web als sdk.
  • Voegt een frameworkreferentie toe aan Microsoft.AspNetCore.App.
    • Met de frameworkreferentie kunnen non-ASP.NET Core-apps, zoals Windows Services, WPF-apps of WinForms-apps, ASP.NET Core-API's gebruiken.
    • De app kan nu ASP.NET Core-API's gebruiken om een ASP.NET Core-server te starten.
  • Voegt gRPC-vereisten toe:

Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App-frameworkreferentie, zie Het gebruik van het gedeelde framework van ASP.NET Core.

Integratie met ASP.NET Core-API's

gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:

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

Standaard kan de gRPC-service-implementatie andere DI-services oplossen met elke levensduur (Singleton, Scoped of Tijdelijk).

HttpContext in gRPC-methoden oplossen

De gRPC-API biedt toegang tot sommige HTTP/2-berichtgegevens, zoals de methode, host, header en trailers. Access wordt uitgevoerd via het ServerCallContext argument dat wordt doorgegeven aan elke gRPC-methode:

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

ServerCallContext biedt geen volledige toegang tot HttpContext in alle ASP.NET API's. De GetHttpContext-extensiemethode biedt volledige toegang tot de HttpContext dat het onderliggende HTTP/2-bericht in ASP.NET API's vertegenwoordigt.

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

Aanvullende informatiebronnen

In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.

Voorwaarden

Aan de slag met gRPC-service in ASP.NET Core

voorbeeldcode weergeven of downloaden (hoe te downloaden).

Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.

gRPC-services toevoegen aan een ASP.NET Core-app

gRPC vereist het pakket Grpc.AspNetCore.

gRPC configureren

In Startup.cs:

  • gRPC is ingeschakeld met de methode AddGrpc.
  • Elke gRPC-service wordt via de MapGrpcService methode aan de routeringspijplijn toegevoegd.
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>();
        });
    }
}

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

ASP.NET Core middleware en -functies delen de routeringspijplijn. Daarom kan een app worden geconfigureerd voor extra aanvraaghandlers. De aanvullende aanvraaghandlers, zoals MVC-controllers, werken parallel met de geconfigureerde gRPC-services.

Serveropties

gRPC-services kunnen worden gehost door alle ingebouwde ASP.NET Core-servers.

  • Kestrel
  • Testserver
  • IIS†
  • HTTP.sys†

†Vereist .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger.

Zie webserver-implementaties in ASP.NET Core-voor meer informatie over het kiezen van de juiste server voor een ASP.NET Core-app.

Kestrel

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is gericht op hoge prestaties en geheugengebruik, maar heeft geen enkele van de geavanceerde functies in HTTP.sys, zoals het delen van poorten.

Kestrel gRPC-eindpunten:

  • Vereis HTTP/2.
  • Moet worden beveiligd met TLS-(Transport Layer Security).

HTTP/2

gRPC vereist HTTP/2. gRPC voor ASP.NET Core valideert HttpRequest.Protocol is HTTP/2.

Kestrel ondersteunt HTTP/2- op de meeste moderne besturingssystemen. Kestrel eindpunten zijn standaard geconfigureerd ter ondersteuning van HTTP/1.1- en HTTP/2-verbindingen.

TLS

Kestrel eindpunten die worden gebruikt voor gRPC, moeten worden beveiligd met TLS. In ontwikkeling wordt automatisch een eindpunt gemaakt dat is beveiligd met TLS op https://localhost:5001 wanneer het ASP.NET Core-ontwikkelingscertificaat aanwezig is. Er is geen configuratie vereist. Een https voorvoegsel controleert of het Kestrel-eindpunt TLS gebruikt.

In productie moet TLS expliciet worden geconfigureerd. In het volgende appsettings.json voorbeeld wordt een HTTP/2-eindpunt dat is beveiligd met TLS opgegeven:

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

U kunt ook Kestrel eindpunten configureren in 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>();
        });

Zie Kestrel https-eindpuntconfiguratievoor meer informatie over het inschakelen van TLS met Kestrel.

Protocolonderhandeling

TLS wordt gebruikt voor meer dan het beveiligen van communicatie. De ALPN -handshake (TLSApplication-Layer Protocol Negotiate) wordt gebruikt om te onderhandelen over het verbindingsprotocol tussen de client en de server wanneer een eindpunt meerdere protocollen ondersteunt. Deze onderhandeling bepaalt of de verbinding GEBRUIKMAAKT van HTTP/1.1 of HTTP/2.

Als een HTTP/2-eindpunt is geconfigureerd zonder TLS, moet het eindpunt ListenOptions.Protocols worden ingesteld op HttpProtocols.Http2. Een eindpunt met meerdere protocollen, zoals HttpProtocols.Http1AndHttp2, kan bijvoorbeeld niet worden gebruikt zonder TLS omdat er geen onderhandeling is. Alle verbindingen met het onbeveiligde eindpunt worden standaard ingesteld op HTTP/1.1 en gRPC-aanroepen mislukken.

Zie Kestrel eindpuntconfiguratievoor meer informatie over het inschakelen van HTTP/2 en TLS met Kestrel.

Notitie

macOS biedt geen ondersteuning voor ASP.NET Core gRPC met TLS vóór .NET 8. Aanvullende configuratie is vereist voor het uitvoeren van gRPC-services op macOS wanneer u .NET 7 of eerder gebruikt. Zie Kan ASP.NET Core gRPC-app niet starten op macOS-voor meer informatie.

Host gRPC in non-ASP.NET Core-projecten

Een ASP.NET Core gRPC-server wordt doorgaans gemaakt op basis van de gRPC-sjabloon. Het projectbestand dat door de sjabloon is gemaakt, gebruikt 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>

De Microsoft.NET.SDK.Web SDK-waarde voegt automatisch een verwijzing toe naar het ASP.NET Core-framework. Met de verwijzing kan de app gebruikmaken van ASP.NET Core-typen die zijn vereist voor het hosten van een server.

U kunt een gRPC-server toevoegen aan non-ASP.NET Core-projecten met de volgende projectbestandsinstellingen:

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

Het voorgaande projectbestand:

  • Maakt geen gebruik van Microsoft.NET.SDK.Web als sdk.
  • Voegt een frameworkreferentie toe aan Microsoft.AspNetCore.App.
    • Met de frameworkreferentie kunnen non-ASP.NET Core-apps, zoals Windows Services, WPF-apps of WinForms-apps, ASP.NET Core-API's gebruiken.
    • De app kan nu ASP.NET Core-API's gebruiken om een ASP.NET Core-server te starten.
  • Voegt gRPC-vereisten toe:

Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App frameworkreferentie, zie Gebruik het gedeelde framework van ASP.NET Core.

Integratie met ASP.NET Core-API's

gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:

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

Standaard kan de gRPC-service-implementatie andere DI-services oplossen met elke levensduur (Singleton, Scoped of Tijdelijk).

HttpContext in gRPC-methoden oplossen

De gRPC-API biedt toegang tot sommige HTTP/2-berichtgegevens, zoals de methode, host, header en trailers. Access wordt uitgevoerd via het ServerCallContext argument dat wordt doorgegeven aan elke gRPC-methode:

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

ServerCallContext biedt geen volledige toegang tot HttpContext in alle ASP.NET API's. De GetHttpContext-extensiemethode biedt volledige toegang tot de HttpContext die het onderliggende HTTP/2-bericht in ASP.NET API's vertegenwoordigt.

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

Aanvullende informatiebronnen

In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.

Voorwaarden

Aan de slag met gRPC-service in ASP.NET Core

Voorbeeldcode bekijken of downloaden (hoe te downloaden).

Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.

gRPC-services toevoegen aan een ASP.NET Core-app

gRPC vereist het pakket Grpc.AspNetCore.

gRPC configureren

In Startup.cs:

  • gRPC is ingeschakeld met de methode AddGrpc.
  • Elke gRPC-service wordt via de MapGrpcService methode aan de routeringspijplijn toegevoegd.
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>();
        });
    }
}

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

ASP.NET Core middleware en -functies delen de routeringspijplijn. Daarom kan een app worden geconfigureerd voor extra aanvraaghandlers. De aanvullende aanvraaghandlers, zoals MVC-controllers, werken parallel met de geconfigureerde gRPC-services.

Serveropties

gRPC-services kunnen worden gehost door alle ingebouwde ASP.NET Core-servers.

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

Vereist .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger.

Zie webserver-implementaties in ASP.NET Core-voor meer informatie over het kiezen van de juiste server voor een ASP.NET Core-app.

Kestrel

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is gericht op hoge prestaties en geheugengebruik, maar heeft geen enkele van de geavanceerde functies in HTTP.sys, zoals het delen van poorten.

Kestrel gRPC-eindpunten:

  • Vereist HTTP/2.
  • Moet worden beveiligd met TLS-(Transport Layer Security).

HTTP/2

gRPC vereist HTTP/2. gRPC voor ASP.NET Core valideert HttpRequest.Protocol is HTTP/2.

Kestrel ondersteunt HTTP/2- op de meeste moderne besturingssystemen. Kestrel eindpunten zijn standaard geconfigureerd ter ondersteuning van HTTP/1.1- en HTTP/2-verbindingen.

TLS

Kestrel eindpunten die worden gebruikt voor gRPC, moeten worden beveiligd met TLS. In ontwikkeling wordt automatisch een eindpunt gemaakt dat is beveiligd met TLS op https://localhost:5001 wanneer het ASP.NET Core-ontwikkelingscertificaat aanwezig is. Er is geen configuratie vereist. Een https voorvoegsel controleert of het Kestrel-eindpunt TLS gebruikt.

In productie moet TLS expliciet worden geconfigureerd. In het volgende appsettings.json voorbeeld wordt een HTTP/2-eindpunt dat is beveiligd met TLS opgegeven:

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

U kunt ook Kestrel eindpunten configureren in 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>();
        });

Zie Kestrel https-eindpuntconfiguratievoor meer informatie over het inschakelen van TLS met Kestrel.

Protocolonderhandeling

TLS wordt gebruikt voor meer dan het beveiligen van communicatie. De ALPN -handshake (TLSApplication-Layer Protocol Negotiate) wordt gebruikt om te onderhandelen over het verbindingsprotocol tussen de client en de server wanneer een eindpunt meerdere protocollen ondersteunt. Deze onderhandeling bepaalt of de verbinding GEBRUIKMAAKT van HTTP/1.1 of HTTP/2.

Als een HTTP/2-eindpunt is geconfigureerd zonder TLS, moet het eindpunt ListenOptions.Protocols worden ingesteld op HttpProtocols.Http2. Een eindpunt met meerdere protocollen, zoals HttpProtocols.Http1AndHttp2, kan bijvoorbeeld niet worden gebruikt zonder TLS omdat er geen onderhandeling is. Alle verbindingen met het onbeveiligde eindpunt worden standaard ingesteld op HTTP/1.1 en gRPC-aanroepen mislukken.

Zie Kestrel eindpuntconfiguratievoor meer informatie over het inschakelen van HTTP/2 en TLS met Kestrel.

Notitie

macOS biedt geen ondersteuning voor ASP.NET Core gRPC met TLS vóór .NET 8. Aanvullende configuratie is vereist voor het uitvoeren van gRPC-services op macOS wanneer u .NET 7 of eerder gebruikt. Zie Kan ASP.NET Core gRPC-app niet starten op macOS-voor meer informatie.

Host gRPC in non-ASP.NET Core-projecten

Een ASP.NET Core gRPC-server wordt doorgaans gemaakt op basis van de gRPC-sjabloon. Het projectbestand dat door de sjabloon is gemaakt, gebruikt 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>

De Microsoft.NET.SDK.Web SDK-waarde voegt automatisch een verwijzing toe naar het ASP.NET Core-framework. Met de verwijzing kan de app gebruikmaken van ASP.NET Core-typen die zijn vereist voor het hosten van een server.

U kunt een gRPC-server toevoegen aan non-ASP.NET Core-projecten met de volgende projectbestandsinstellingen:

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

Het voorgaande projectbestand:

  • Maakt geen gebruik van Microsoft.NET.SDK.Web als sdk.
  • Voegt een frameworkreferentie toe aan Microsoft.AspNetCore.App.
    • Met de frameworkreferentie kunnen non-ASP.NET Core-apps, zoals Windows Services, WPF-apps of WinForms-apps, ASP.NET Core-API's gebruiken.
    • De app kan nu ASP.NET Core-API's gebruiken om een ASP.NET Core-server te starten.
  • Voegt gRPC-vereisten toe:

Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App-referentie naar het framework, zie Gebruik het gedeelde frameworkvan ASP.NET Core.

Integratie met ASP.NET Core-API's

gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:

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

Standaard kan de gRPC-service-implementatie andere DI-services oplossen met elke levensduur (Singleton, Scoped of Tijdelijk).

HttpContext in gRPC-methoden oplossen

De gRPC-API biedt toegang tot sommige HTTP/2-berichtgegevens, zoals de methode, host, header en trailers. Access wordt uitgevoerd via het ServerCallContext argument dat wordt doorgegeven aan elke gRPC-methode:

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

ServerCallContext biedt geen volledige toegang tot HttpContext in alle ASP.NET API's. De GetHttpContext-extensiemethode biedt volledige toegang tot de HttpContext die het onderliggende HTTP/2-bericht vertegenwoordigt in ASP.NET API's.

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

Aanvullende informatiebronnen