Udostępnij za pośrednictwem

Usługi gRPC na platformie ASP.NET Core

  • Artykuł

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

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

Wymagania wstępne

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

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

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

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łączona za pomocą AddGrpc metody .
  • Każda usługa gRPC jest dodawana do potoku routingu MapGrpcService za pośrednictwem metody .
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 Podstawowe oprogramowanie pośredniczące i funkcje współużytkują potok 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
  • TestServer
  • USŁUGI 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:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy protokół HttpRequest.Protocol to HTTP/2.

Kestrelobsł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 opracowywania punkt końcowy zabezpieczony przy użyciu protokołu TLS jest tworzony automatycznie po https://localhost:5001 wystąpieniu certyfikatu dewelopera 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 programie 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 za pomocą Kestrelprogramu , zobacz Kestrel Konfiguracja punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do obsługi więcej niż 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, punkt końcowy ListenOptions.Protocols musi być ustawiony 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 do http/1.1 i 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ą Kestrelprogramu , zobacz Kestrel Konfiguracja 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.

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 HTTP.sys obsługę protokołu HTTP/2 serwera internetowego.

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 go 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 go jako zestawu SDK.
  • Dodaje odwołanie do platformy do Microsoft.AspNetCore.Appelementu .
    • Dokumentacja platformy umożliwia korzystanie z interfejsów API ASP.NET platformy non-ASP.NET Core, takich jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Use the ASP.NET Core shared framework (Korzystanie z platformy udostępnionej Microsoft.AspNetCore.App ASP.NET Core).

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 rejestrowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi di z dowolnym okresem istnienia (Singleton, Scoped lub Przejściowy).

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

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

Wymagania wstępne

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

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

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

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łączona za pomocą AddGrpc metody .
  • Każda usługa gRPC jest dodawana do potoku routingu MapGrpcService za pośrednictwem metody .
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 Podstawowe oprogramowanie pośredniczące i funkcje współużytkują potok 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
  • TestServer
  • USŁUGI 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:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy protokół HttpRequest.Protocol to HTTP/2.

Kestrelobsł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 opracowywania punkt końcowy zabezpieczony przy użyciu protokołu TLS jest tworzony automatycznie po https://localhost:5001 wystąpieniu certyfikatu dewelopera 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 programie 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 za pomocą Kestrelprogramu , zobacz Kestrel Konfiguracja punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do obsługi więcej niż 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, punkt końcowy ListenOptions.Protocols musi być ustawiony 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 do http/1.1 i 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ą Kestrelprogramu , zobacz Kestrel Konfiguracja 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.

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 HTTP.sys obsługę protokołu HTTP/2 serwera internetowego.

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 go 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 go jako zestawu SDK.
  • Dodaje odwołanie do platformy do Microsoft.AspNetCore.Appelementu .
    • Dokumentacja platformy umożliwia korzystanie z interfejsów API ASP.NET platformy non-ASP.NET Core, takich jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Use the ASP.NET Core shared framework (Korzystanie z platformy udostępnionej Microsoft.AspNetCore.App ASP.NET Core).

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 rejestrowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi di z dowolnym okresem istnienia (Singleton, Scoped lub Przejściowy).

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

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

Wymagania wstępne

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

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

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

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łączona za pomocą AddGrpc metody .
  • Każda usługa gRPC jest dodawana do potoku routingu MapGrpcService za pośrednictwem metody .
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 Podstawowe oprogramowanie pośredniczące i funkcje współużytkują potok 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
  • TestServer
  • USŁUGI 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:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy protokół HttpRequest.Protocol to HTTP/2.

Kestrelobsł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 opracowywania punkt końcowy zabezpieczony przy użyciu protokołu TLS jest tworzony automatycznie po https://localhost:5001 wystąpieniu certyfikatu dewelopera 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 programie 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 za pomocą Kestrelprogramu , zobacz Kestrel Konfiguracja punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do obsługi więcej niż 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, punkt końcowy ListenOptions.Protocols musi być ustawiony 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 do http/1.1 i 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ą Kestrelprogramu , zobacz Kestrel Konfiguracja 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.

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 HTTP.sys obsługę protokołu HTTP/2 serwera internetowego.

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 go 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 go jako zestawu SDK.
  • Dodaje odwołanie do platformy do Microsoft.AspNetCore.Appelementu .
    • Dokumentacja platformy umożliwia korzystanie z interfejsów API ASP.NET platformy non-ASP.NET Core, takich jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Use the ASP.NET Core shared framework (Korzystanie z platformy udostępnionej Microsoft.AspNetCore.App ASP.NET Core).

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 rejestrowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi di z dowolnym okresem istnienia (Singleton, Scoped lub Przejściowy).

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

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

Wymagania wstępne

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

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

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

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Startup.cs:

  • GRPC jest włączona za pomocą AddGrpc metody .
  • Każda usługa gRPC jest dodawana do potoku routingu MapGrpcService za pośrednictwem metody .
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>();
        });
    }
}

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 Podstawowe oprogramowanie pośredniczące i funkcje współużytkują potok 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
  • TestServer
  • USŁUGI 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:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy protokół HttpRequest.Protocol to HTTP/2.

Kestrelobsł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 opracowywania punkt końcowy zabezpieczony przy użyciu protokołu TLS jest tworzony automatycznie po https://localhost:5001 wystąpieniu certyfikatu dewelopera 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 programie 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>();
        });

Aby uzyskać więcej informacji na temat włączania protokołu TLS za pomocą Kestrelprogramu , zobacz Kestrel Konfiguracja punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do obsługi więcej niż 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, punkt końcowy ListenOptions.Protocols musi być ustawiony 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 do http/1.1 i 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ą Kestrelprogramu , zobacz Kestrel Konfiguracja 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.

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 HTTP.sys obsługę protokołu HTTP/2 serwera internetowego.

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 go 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 go jako zestawu SDK.
  • Dodaje odwołanie do platformy do Microsoft.AspNetCore.Appelementu .
    • Dokumentacja platformy umożliwia korzystanie z interfejsów API ASP.NET platformy non-ASP.NET Core, takich jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Use the ASP.NET Core shared framework (Korzystanie z platformy udostępnionej Microsoft.AspNetCore.App ASP.NET Core).

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 rejestrowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi di z dowolnym okresem istnienia (Singleton, Scoped lub Przejściowy).

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

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

Wymagania wstępne

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

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

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

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Startup.cs:

  • GRPC jest włączona za pomocą AddGrpc metody .
  • Każda usługa gRPC jest dodawana do potoku routingu MapGrpcService za pośrednictwem metody .
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>();
        });
    }
}

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 Podstawowe oprogramowanie pośredniczące i funkcje współużytkują potok 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
  • TestServer
  • USŁUGI 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:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy protokół HttpRequest.Protocol to HTTP/2.

Kestrelobsł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 opracowywania punkt końcowy zabezpieczony przy użyciu protokołu TLS jest tworzony automatycznie po https://localhost:5001 wystąpieniu certyfikatu dewelopera 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 programie 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>();
        });

Aby uzyskać więcej informacji na temat włączania protokołu TLS za pomocą Kestrelprogramu , zobacz Kestrel Konfiguracja punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do obsługi więcej niż 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, punkt końcowy ListenOptions.Protocols musi być ustawiony 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 do http/1.1 i 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ą Kestrelprogramu , zobacz Kestrel Konfiguracja 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.

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 go 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 go jako zestawu SDK.
  • Dodaje odwołanie do platformy do Microsoft.AspNetCore.Appelementu .
    • Dokumentacja platformy umożliwia korzystanie z interfejsów API ASP.NET platformy non-ASP.NET Core, takich jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Use the ASP.NET Core shared framework (Korzystanie z platformy udostępnionej Microsoft.AspNetCore.App ASP.NET Core).

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 rejestrowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi di z dowolnym okresem istnienia (Singleton, Scoped lub Przejściowy).

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

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

Wymagania wstępne

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

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

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

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Startup.cs:

  • GRPC jest włączona za pomocą AddGrpc metody .
  • Każda usługa gRPC jest dodawana do potoku routingu MapGrpcService za pośrednictwem metody .
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>();
        });
    }
}

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 Podstawowe oprogramowanie pośredniczące i funkcje współużytkują potok 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
  • TestServer
  • USŁUGI 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:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy protokół HttpRequest.Protocol to HTTP/2.

Kestrelobsł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 opracowywania punkt końcowy zabezpieczony przy użyciu protokołu TLS jest tworzony automatycznie po https://localhost:5001 wystąpieniu certyfikatu dewelopera 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 programie 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>();
        });

Aby uzyskać więcej informacji na temat włączania protokołu TLS za pomocą Kestrelprogramu , zobacz Kestrel Konfiguracja punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do obsługi więcej niż 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, punkt końcowy ListenOptions.Protocols musi być ustawiony 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 do http/1.1 i 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ą Kestrelprogramu , zobacz Kestrel Konfiguracja 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.

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 go 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 go jako zestawu SDK.
  • Dodaje odwołanie do platformy do Microsoft.AspNetCore.Appelementu .
    • Dokumentacja platformy umożliwia korzystanie z interfejsów API ASP.NET platformy non-ASP.NET Core, takich jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Use the ASP.NET Core shared framework (Korzystanie z platformy udostępnionej Microsoft.AspNetCore.App ASP.NET Core).

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 rejestrowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi di z dowolnym okresem istnienia (Singleton, Scoped lub Przejściowy).

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