gRPC-tjänster med ASP.NET Core

Det här dokumentet visar hur du kommer igång med gRPC-tjänster med hjälp av ASP.NET Core.

Förutsättningar

Visual Studio

• Visual Studio 2022 med ASP.NET och webbutvecklingsarbetsflödet.

  

Visual Studio Code

• Visual Studio Code
• C# för Visual Studio Code (senaste versionen)
• .NET 8.0 SDK

Visual Studio Code-instruktionerna använder .NET CLI för ASP.NET Core-utvecklingsfunktioner som att skapa projekt. Du kan följa dessa instruktioner i macOS, Linux eller Windows och med valfri kodredigerare. Mindre ändringar kan krävas om du använder något annat än Visual Studio Code.

Visual Studio för Mac

• Visual Studio 2022 för Mac (senaste versionen)

  Viktig

  Microsoft har meddelat att Visual Studio för Mac upphör. Visual Studio för Mac stöds inte längre från och med den 31 augusti 2024. Alternativen är:

  • Visual Studio Code med C# Dev Kit och relaterade tillägg, till exempel .NET MAUI och Unity.
  • Visual Studio IDE körs på Windows på en virtuell dator på Mac.
  • Visual Studio IDE som körs på en virtuell dator på Windows i molnet.

  Mer information finns i Visual Studio för Mac-meddelande om pensionering.

Kom igång med gRPC-tjänsten i ASP.NET Core

Visa eller ladda ned exempelkod (hur du laddar ned).

Visual Studio

Mer information om hur du skapar ett gRPC-projekt finns i Komma igång med gRPC-tjänster.

Visual Studio Code/Visual Studio för Mac

Kör dotnet new grpc -o GrpcGreeter från kommandoraden.

Lägga till gRPC-tjänster i en ASP.NET Core-app

gRPC kräver paketet Grpc.AspNetCore.

Konfigurera gRPC

I Program.cs:

• gRPC är aktiverat med metoden AddGrpc.
• Varje gRPC-tjänst läggs till i routningspipelinen via metoden MapGrpcService.

using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

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

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

var app = builder.Build();

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

app.Run();

Om du vill se kodkommentar översatta till andra språk än engelska kan du meddela oss i det här GitHub-diskussionsproblemet.

ASP.NET Core-mellanprogram och funktioner delar routningspipelinen, och därför kan en app konfigureras för att hantera ytterligare begäranhanterare. De ytterligare begärandehanterarna, till exempel MVC-styrenheter, fungerar parallellt med de konfigurerade gRPC-tjänsterna.

Serveralternativ

gRPC-tjänster kan hanteras av alla inbyggda ASP.NET Core-servrar.

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

†Requires .NET 5 och Windows 11 Build 22000 eller Windows Server 2022 Build 20348 eller senare.

Mer information om hur du väljer rätt server för en ASP.NET Core-app finns i webbserverimplementeringar i ASP.NET Core.

Kestrel

Kestrel är en plattformsoberoende webbserver för ASP.NET Core. Kestrel fokuserar på hög prestanda och minnesanvändning, men det har inte några av de avancerade funktionerna i HTTP.sys till exempel portdelning.

Kestrel gRPC-slutpunkter:

• Kräv HTTP/2.
• Bör skyddas med TLS (Transport Layer Security).

HTTP/2

gRPC kräver HTTP/2. gRPC för ASP.NET Core validerar att HttpRequest.Protocol är HTTP/2.

Kestrel stöder HTTP/2- på de flesta moderna operativsystem. Kestrel slutpunkter har konfigurerats för att stödja HTTP/1.1- och HTTP/2-anslutningar som standard.

TLS

Kestrel slutpunkter som används för gRPC ska skyddas med TLS. Under utveckling skapas en slutpunkt som skyddas med TLS automatiskt vid https://localhost:5001 när ASP.NET Core-utvecklingscertifikatet finns. Ingen konfiguration krävs. Ett https-prefix verifierar att slutpunkten Kestrel använder TLS.

I produktion måste TLS konfigureras explicit. I följande appsettings.json exempel tillhandahålls en HTTP/2-slutpunkt som skyddas med TLS:

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

Alternativt kan du konfigurera Kestrel ändpunkter i 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>");
    });
});

Mer information om hur du aktiverar TLS med Kestrelfinns i Kestrel HTTPS-slutpunktskonfiguration.

Protokollförhandling

TLS används för mer än att skydda kommunikationen. TLS Application-Layer Protocol Negotiation (ALPN) handskakning används för att förhandla om anslutningsprotokollet mellan klienten och servern när en slutpunkt stöder flera protokoll. Den här förhandlingen avgör om anslutningen använder HTTP/1.1 eller HTTP/2.

Om en HTTP/2-slutpunkt har konfigurerats utan TLS måste slutpunktens ListenOptions.Protocols anges till HttpProtocols.Http2. En slutpunkt med flera protokoll, till exempel HttpProtocols.Http1AndHttp2, kan inte användas utan TLS eftersom det inte finns någon förhandling. Alla anslutningar till den oskyddade slutpunkten är som standard HTTP/1.1 och gRPC-anrop misslyckas.

Mer information om hur du aktiverar HTTP/2 och TLS med Kestrelfinns i Kestrel slutpunktskonfiguration.

Not

macOS stöder inte ASP.NET Core gRPC med TLS före .NET 8. Ytterligare konfiguration krävs för att köra gRPC-tjänster på macOS när du använder .NET 7 eller tidigare. Mer information finns i Det går inte att starta ASP.NET Core gRPC-appen på macOS-.

IIS

Internet Information Services (IIS) är en flexibel, säker och hanterbar webbserver som är värd för webbappar, inklusive ASP.NET Core. .NET 5 och Windows 11 Build 22000 eller Windows Server 2022 Build 20348 eller senare krävs för att vara värd för gRPC-tjänster med IIS.

IIS måste konfigureras för att använda TLS och HTTP/2. Mer information finns i Use ASP.NET Core with HTTP/2 on IIS.

HTTP.sys

HTTP.sys är en webbserver för ASP.NET Core som bara körs i Windows. .NET 5 och Windows 11 Build 22000 eller Windows Server 2022 Build 20348 eller senare krävs för att vara värd för gRPC-tjänster med HTTP.sys.

HTTP.sys måste konfigureras för att använda TLS och HTTP/2. Mer information finns i HTTP.sys http/2-stöd för webbservern.

Värd för gRPC i non-ASP.NET Core-projekt

En ASP.NET Core gRPC-server skapas vanligtvis från gRPC-mallen. Projektfilen som skapas av mallen använder Microsoft.NET.SDK.Web som 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>

Värdet Microsoft.NET.SDK.Web SDK lägger automatiskt till en referens till ASP.NET Core-ramverket. Referensen gör att appen kan använda ASP.NET Core-typer som krävs för att vara värd för en server.

Du kan lägga till en gRPC-server i non-ASP.NET Core-projekt med följande projektfilinställningar:

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

Föregående projektfil:

• Använder inte Microsoft.NET.SDK.Web som SDK.
• Lägger till en ramverksreferens till Microsoft.AspNetCore.App.
  • Med ramverksreferensen kan non-ASP.NET Core-appar, till exempel Windows Services, WPF-appar eller WinForms-appar, använda ASP.NET Core-API:er.
  • Appen kan nu använda ASP.NET Core-API:er för att starta en ASP.NET Core-server.
• Lägger till gRPC-krav:
  • NuGet-paketreferens till Grpc.AspNetCore.
  • .proto fil.

Mer information om hur du använder referensen för Microsoft.AspNetCore.App-ramverket finns i Använd det delade ASP.NET Core-ramverket.

Integrering med api:er för ASP.NET Core

gRPC-tjänster har fullständig åtkomst till ASP.NET Core-funktionerna, till exempel beroendeinmatning (DI) och loggning. Tjänstimplementeringen kan till exempel lösa en loggningstjänst från DI-containern.

Konstruktorinmatning:

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

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

Primär konstruktorinmatning (.NET 8 eller senare):

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

Som standard kan gRPC-tjänstimplementeringen lösa upp andra DI-tjänster med vilken livslängd som helst (Singleton, Scoped eller Transient).

Lösa HttpContext med gRPC-metoder

GRPC-API:et ger åtkomst till vissa HTTP/2-meddelandedata, till exempel metod, värd, rubrik och trailers. Åtkomst sker via argumentet ServerCallContext som skickas till varje gRPC-metod:

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

ServerCallContext ger inte fullständig åtkomst till HttpContext i alla ASP.NET API:er. Metoden GetHttpContext-tillägg ger fullständig åtkomst till HttpContext som representerar det underliggande HTTP/2-meddelandet i ASP.NET API:er:

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

Ytterligare resurser

• Skapa en .NET Core gRPC-klient och -server i ASP.NET Core
• Översikt över gRPC på .NET
• gRPC-tjänster med C#
• Kestrel webbserver i ASP.NET Core