Usługi gRPC na platformie ASP.NET Core

W tym dokumencie pokazano, jak rozpocząć pracę z usługami gRPC przy użyciu ASP.NET Core.

Wymagania wstępne

Visual Studio

• Program Visual Studio 2022 z pakietem roboczym tworzenia aplikacji ASP.NET i webowych.

  

Visual Studio Code

• Visual Studio Code
• Język C# dla programu Visual Studio Code (najnowsza wersja)
• SDK .NET 8

W przypadku funkcji programistycznych platformy ASP.NET Core, takich jak tworzenie projektu, w instrukcjach programu Visual Studio Code wykorzystywany jest interfejs wiersza polecenia platformy .NET. Można postępować według tych instrukcji w systemach macOS, Linux lub Windows oraz w przypadku każdego edytora kodu. Jeśli korzystasz z programu innego niż Visual Studio Code, konieczne mogą być drobne zmiany.

Wprowadzenie do usługi gRPC na platformie ASP.NET Core

Wyświetl lub pobierz przykładowy kod (jak pobrać).

Visual Studio

Aby uzyskać szczegółowe instrukcje dotyczące tworzenia projektu gRPC, zobacz Wprowadzenie do usług gRPC.

Visual Studio Code

Uruchom polecenie dotnet new grpc -o GrpcGreeter z poziomu wiersza polecenia.

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Program.cs:

• gRPC jest włączone za pomocą metody AddGrpc.
• Każda usługa gRPC jest dodawana do potoku routingu za pomocą metody 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();

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

ASP.NET Core middleware i funkcje dzielą się potokiem routingu, dlatego można skonfigurować aplikację do obsługi dodatkowych procedur obsługi żądań. Dodatkowe programy obsługi żądań, takie jak kontrolery MVC, działają równolegle ze skonfigurowanymi usługami gRPC.

Opcje serwera

Usługi gRPC mogą być hostowane przez wszystkie wbudowane serwery ASP.NET Core.

• Kestrel
• Serwer testowy
• IIS
• HTTP.sys†

†Wymaga programu .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowszego.

Aby uzyskać więcej informacji na temat wybierania odpowiedniego serwera dla aplikacji ASP.NET Core, zobacz Implementacje serwera sieci Web w ASP.NET Core.

Kestrel

Kestrel to międzyplatformowy serwer internetowy dla platformy ASP.NET Core. Kestrel koncentruje się na wysokiej wydajności i wykorzystaniu pamięci, ale nie ma niektórych zaawansowanych funkcji w HTTP.sys, takich jak udostępnianie portów.

Kestrel Punkty końcowe gRPC:

• Wymagaj protokołu HTTP/2.
• Należy zabezpieczyć przy użyciu protokołu Transport Layer Security (TLS).

Protokół HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core weryfikuje, czy HttpRequest.Protocol jest HTTP/2.

Kestrel obsługuje protokół HTTP/2 w większości nowoczesnych systemów operacyjnych. Kestrel Punkty końcowe są domyślnie skonfigurowane do obsługi połączeń HTTP/1.1 i HTTP/2.

TLS

Kestrel punkty końcowe używane na potrzeby gRPC powinny być zabezpieczone przy użyciu protokołu TLS. Podczas tworzenia punkt końcowy zabezpieczony protokołem TLS jest automatycznie tworzony pod adresem https://localhost:5001, gdy obecny jest certyfikat deweloperski ASP.NET Core. Nie jest wymagana żadna konfiguracja. Prefiks https sprawdza, Kestrel czy punkt końcowy używa protokołu TLS.

W środowisku produkcyjnym protokół TLS musi być jawnie skonfigurowany. W poniższym appsettings.json przykładzie podano punkt końcowy HTTP/2 zabezpieczony przy użyciu protokołu TLS:

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

Alternatywnie Kestrel punkty końcowe można skonfigurować w 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>");
    });
});

Aby uzyskać więcej informacji na temat włączania protokołu TLS z Kestrel, zobacz Kestrel.

Negocjowanie protokołu

Protokół TLS jest używany nie tylko do zabezpieczania komunikacji. Uzgadnianie negocjacji protokołu TLS w warstwie aplikacji (ALPN) służy do negocjowania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów. Ta negocjacje określają, czy połączenie korzysta z protokołu HTTP/1.1, czy HTTP/2.

Jeśli punkt końcowy HTTP/2 jest skonfigurowany bez protokołu TLS, ListenOptions.Protocols musi być ustawione na HttpProtocols.Http2wartość. Punkt końcowy z wieloma protokołami, na HttpProtocols.Http1AndHttp2 przykład, nie może być używany bez protokołu TLS, ponieważ nie ma negocjacji. Wszystkie połączenia z niezabezpieczonym punktem końcowym domyślnie używają protokołu HTTP/1.1, a wywołania gRPC kończą się niepowodzeniem.

Aby uzyskać więcej informacji na temat włączania protokołu HTTP/2 i protokołu TLS za pomocą Kestrel, zobacz Kestrel konfigurację punktu końcowego.

Uwaga

System macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS przed platformą .NET 8. Dodatkowa konfiguracja jest wymagana do pomyślnego uruchomienia usług gRPC w systemie macOS w przypadku korzystania z platformy .NET 7 lub starszej wersji. Aby uzyskać więcej informacji, zobacz Nie można uruchomić aplikacji gRPC platformy ASP.NET Core w systemie macOS.

USŁUGI IIS

Internet Information Services (IIS) to elastyczny, bezpieczny i zarządzany serwer sieci Web do hostowania aplikacji internetowych, w tym ASP.NET Core. Do hostowania usług gRPC przy użyciu usług IIS są wymagane programy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze.

Usługi IIS muszą być skonfigurowane do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz Use ASP.NET Core with HTTP/2 on IIS (Używanie ASP.NET Core z protokołem HTTP/2 w usługach IIS).

HTTP.sys

HTTP.sys jest serwerem sieci Web dla platformy ASP.NET Core, który działa tylko w systemie Windows. Platformy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze są wymagane do hostowania usług gRPC z HTTP.sys.

HTTP.sys należy skonfigurować do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz obsługę protokołu HTTP/2 przez serwer internetowy HTTP.sys.

Hostowanie usługi gRPC w projektach non-ASP.NET Core

Serwer gRPC platformy ASP.NET Core jest zwykle tworzony na podstawie szablonu gRPC. Plik projektu utworzony przez szablon używa Microsoft.NET.SDK.Web jako zestawu 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>

Microsoft.NET.SDK.Web Wartość zestawu SDK automatycznie dodaje odwołanie do platformy ASP.NET Core. Odwołanie umożliwia aplikacji używanie typów ASP.NET Core wymaganych do hostowania serwera.

Serwer gRPC można dodać do projektów non-ASP.NET Core przy użyciu następujących ustawień pliku projektu:

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

Poprzedni plik projektu:

• Nie używa Microsoft.NET.SDK.Web jako zestawu SDK.
• Dodaje odwołanie do frameworku do Microsoft.AspNetCore.App elementu.
  • Odwołanie do frameworka umożliwia aplikacjom spoza ASP.NET Core, takim jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms, korzystanie z interfejsów API ASP.NET Core.
  • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
• Dodaje wymagania dotyczące korzystania z usługi gRPC:
  • Odwołanie do pakietu NuGet Grpc.AspNetCore.
  • .proto plik.

Aby uzyskać więcej informacji na temat korzystania z dokumentacji frameworka, zobacz Microsoft.AspNetCore.App.

Integracja z interfejsami API platformy ASP.NET Core

Usługi gRPC mają pełny dostęp do funkcji ASP.NET Core, takich jak wstrzykiwanie zależności (DI) i logowanie . Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI.

Wstrzykiwanie konstruktora:

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

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

Iniekcja konstruktora podstawowego (.NET 8 lub nowszy):

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi DI o dowolnym cyklu życia (Singleton, Scoped lub Transient).

Rozwiązywanie problemów z protokołem HttpContext w metodach gRPC

Interfejs API gRPC zapewnia dostęp do niektórych danych komunikatów HTTP/2, takich jak metoda, host, nagłówek i przyczepy. Dostęp odbywa się za pośrednictwem argumentu przekazanego ServerCallContext do każdej metody gRPC:

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

ServerCallContext nie zapewnia pełnego dostępu do HttpContext wszystkich interfejsów API ASP.NET. GetHttpContext Metoda rozszerzenia zapewnia pełny dostęp do reprezentującego HttpContext podstawowy komunikat HTTP/2 w interfejsach API ASP.NET:

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

Dodatkowe zasoby

• Tworzenie klienta i serwera gRPC platformy .NET Core na platformie ASP.NET Core
• Omówienie usługi gRPC na platformie .NET
• usługi gRPC z językiem C#
• Kestrel serwer internetowy w programie ASP.NET Core