Sdílet prostřednictvím


Služby gRPC s ASP.NET Core

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.

Požadavky

Začínáme se službou gRPC v ASP.NET Core

Zobrazení nebo stažení vzorového kódu (postup stažení)

Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.

Přidání služeb gRPC do aplikace ASP.NET Core

Pro gRPC se vyžaduje balíček Grpc.AspNetCore.

Konfigurace gRPC

V Program.cs:

  • Metoda gRPC je povolená AddGrpc .
  • Každá služba gRPC se přidá do kanálu směrování prostřednictvím MapGrpcService 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();

Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.

ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.

Možnosti serveru

Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.

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

†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.

Kestrel

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2.

Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.

Protokol TLS

Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001 při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https ověřuje, že Kestrel koncový bod používá protokol TLS.

V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:

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

Alternativně Kestrel je možné nakonfigurovat koncové body v 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>");
    });
});

Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2 je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.

Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.

Poznámka:

macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.

IIS

Internetová informační služba (IIS) je flexibilní, zabezpečený a spravovatelný webový server pro hostování webových aplikací, včetně ASP.NET Core. K hostování služeb gRPC ve službě IIS se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Služba IIS musí být nakonfigurovaná tak, aby používala protokol TLS a HTTP/2. Další informace naleznete v tématu Použití ASP.NET Core s HTTP/2 ve službě IIS.

HTTP.sys

HTTP.sys je webový server pro ASP.NET Core, který běží jenom ve Windows. K hostování služeb gRPC s HTTP.sys se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

HTTP.sys musí být nakonfigurované tak, aby používaly protokol TLS a HTTP/2. Další informace najdete v tématu HTTP.sys podpora HTTP/2 webového serveru.

Hostování gRPC v projektech non-ASP.NET Core

Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web jako sada 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 Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.

Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru 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>

Předchozí soubor projektu:

  • Nepoužívá Microsoft.NET.SDK.Web se jako sada SDK.
  • Přidá odkaz na architekturu do Microsoft.AspNetCore.App.
    • Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
    • Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
  • Přidá požadavky gRPC:

Další informace o použití referenční informace Microsoft.AspNetCore.App k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.

Integrace s rozhraními API ASP.NET Core

Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:

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

Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).

Řešení httpContext v metodách gRPC

Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext předaného každé metodě 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 neposkytuje úplný přístup ke HttpContext všem rozhraním API ASP.NET. Metoda GetHttpContext rozšíření poskytuje úplný přístup k HttpContext reprezentaci základní zprávy HTTP/2 v rozhraních 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
        });
    }
}

Další materiály

Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.

Požadavky

Začínáme se službou gRPC v ASP.NET Core

Zobrazení nebo stažení vzorového kódu (postup stažení)

Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.

Přidání služeb gRPC do aplikace ASP.NET Core

Pro gRPC se vyžaduje balíček Grpc.AspNetCore.

Konfigurace gRPC

V Program.cs:

  • Metoda gRPC je povolená AddGrpc .
  • Každá služba gRPC se přidá do kanálu směrování prostřednictvím MapGrpcService 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();

Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.

ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.

Možnosti serveru

Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.

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

†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.

Kestrel

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2.

Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.

Protokol TLS

Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001 při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https ověřuje, že Kestrel koncový bod používá protokol TLS.

V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:

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

Alternativně Kestrel je možné nakonfigurovat koncové body v 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>");
    });
});

Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2 je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.

Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.

Poznámka:

macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.

IIS

Internetová informační služba (IIS) je flexibilní, zabezpečený a spravovatelný webový server pro hostování webových aplikací, včetně ASP.NET Core. K hostování služeb gRPC ve službě IIS se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Služba IIS musí být nakonfigurovaná tak, aby používala protokol TLS a HTTP/2. Další informace naleznete v tématu Použití ASP.NET Core s HTTP/2 ve službě IIS.

HTTP.sys

HTTP.sys je webový server pro ASP.NET Core, který běží jenom ve Windows. K hostování služeb gRPC s HTTP.sys se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

HTTP.sys musí být nakonfigurované tak, aby používaly protokol TLS a HTTP/2. Další informace najdete v tématu HTTP.sys podpora HTTP/2 webového serveru.

Hostování gRPC v projektech non-ASP.NET Core

Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web jako sada 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 Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.

Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru 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>

Předchozí soubor projektu:

  • Nepoužívá Microsoft.NET.SDK.Web se jako sada SDK.
  • Přidá odkaz na architekturu do Microsoft.AspNetCore.App.
    • Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
    • Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
  • Přidá požadavky gRPC:

Další informace o použití referenční informace Microsoft.AspNetCore.App k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.

Integrace s rozhraními API ASP.NET Core

Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:

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

Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).

Řešení httpContext v metodách gRPC

Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext předaného každé metodě 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 neposkytuje úplný přístup ke HttpContext všem rozhraním API ASP.NET. Metoda GetHttpContext rozšíření poskytuje úplný přístup k HttpContext reprezentaci základní zprávy HTTP/2 v rozhraních 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
        });
    }
}

Další materiály

Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.

Požadavky

Začínáme se službou gRPC v ASP.NET Core

Zobrazení nebo stažení vzorového kódu (postup stažení)

Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.

Přidání služeb gRPC do aplikace ASP.NET Core

Pro gRPC se vyžaduje balíček Grpc.AspNetCore.

Konfigurace gRPC

V Program.cs:

  • Metoda gRPC je povolená AddGrpc .
  • Každá služba gRPC se přidá do kanálu směrování prostřednictvím MapGrpcService 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();

Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.

ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.

Možnosti serveru

Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.

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

†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.

Kestrel

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2.

Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.

Protokol TLS

Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001 při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https ověřuje, že Kestrel koncový bod používá protokol TLS.

V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:

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

Alternativně Kestrel je možné nakonfigurovat koncové body v 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>");
    });
});

Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2 je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.

Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.

Poznámka:

macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.

IIS

Internetová informační služba (IIS) je flexibilní, zabezpečený a spravovatelný webový server pro hostování webových aplikací, včetně ASP.NET Core. K hostování služeb gRPC ve službě IIS se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Služba IIS musí být nakonfigurovaná tak, aby používala protokol TLS a HTTP/2. Další informace naleznete v tématu Použití ASP.NET Core s HTTP/2 ve službě IIS.

HTTP.sys

HTTP.sys je webový server pro ASP.NET Core, který běží jenom ve Windows. K hostování služeb gRPC s HTTP.sys se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

HTTP.sys musí být nakonfigurované tak, aby používaly protokol TLS a HTTP/2. Další informace najdete v tématu HTTP.sys podpora HTTP/2 webového serveru.

Hostování gRPC v projektech non-ASP.NET Core

Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web jako sada 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 Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.

Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru 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>

Předchozí soubor projektu:

  • Nepoužívá Microsoft.NET.SDK.Web se jako sada SDK.
  • Přidá odkaz na architekturu do Microsoft.AspNetCore.App.
    • Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
    • Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
  • Přidá požadavky gRPC:

Další informace o použití referenční informace Microsoft.AspNetCore.App k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.

Integrace s rozhraními API ASP.NET Core

Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:

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

Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).

Řešení httpContext v metodách gRPC

Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext předaného každé metodě 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 neposkytuje úplný přístup ke HttpContext všem rozhraním API ASP.NET. Metoda GetHttpContext rozšíření poskytuje úplný přístup k HttpContext reprezentaci základní zprávy HTTP/2 v rozhraních 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
        });
    }
}

Další materiály

Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.

Požadavky

Začínáme se službou gRPC v ASP.NET Core

Zobrazení nebo stažení vzorového kódu (postup stažení)

Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.

Přidání služeb gRPC do aplikace ASP.NET Core

Pro gRPC se vyžaduje balíček Grpc.AspNetCore.

Konfigurace gRPC

V Startup.cs:

  • Metoda gRPC je povolená AddGrpc .
  • Každá služba gRPC se přidá do kanálu směrování prostřednictvím MapGrpcService 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>();
        });
    }
}

Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.

ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.

Možnosti serveru

Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.

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

†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.

Kestrel

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2.

Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.

Protokol TLS

Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001 při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https ověřuje, že Kestrel koncový bod používá protokol TLS.

V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:

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

Alternativně Kestrel je možné nakonfigurovat koncové body v 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>();
        });

Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2 je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.

Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.

Poznámka:

macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.

IIS

Internetová informační služba (IIS) je flexibilní, zabezpečený a spravovatelný webový server pro hostování webových aplikací, včetně ASP.NET Core. K hostování služeb gRPC ve službě IIS se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Služba IIS musí být nakonfigurovaná tak, aby používala protokol TLS a HTTP/2. Další informace naleznete v tématu Použití ASP.NET Core s HTTP/2 ve službě IIS.

HTTP.sys

HTTP.sys je webový server pro ASP.NET Core, který běží jenom ve Windows. K hostování služeb gRPC s HTTP.sys se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

HTTP.sys musí být nakonfigurované tak, aby používaly protokol TLS a HTTP/2. Další informace najdete v tématu HTTP.sys podpora HTTP/2 webového serveru.

Hostování gRPC v projektech non-ASP.NET Core

Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web jako sada 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 Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.

Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru 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>

Předchozí soubor projektu:

  • Nepoužívá Microsoft.NET.SDK.Web se jako sada SDK.
  • Přidá odkaz na architekturu do Microsoft.AspNetCore.App.
    • Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
    • Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
  • Přidá požadavky gRPC:

Další informace o použití referenční informace Microsoft.AspNetCore.App k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.

Integrace s rozhraními API ASP.NET Core

Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:

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

Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).

Řešení httpContext v metodách gRPC

Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext předaného každé metodě 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 neposkytuje úplný přístup ke HttpContext všem rozhraním API ASP.NET. Metoda GetHttpContext rozšíření poskytuje úplný přístup k HttpContext reprezentaci základní zprávy HTTP/2 v rozhraních 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
        });
    }
}

Další materiály

Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.

Požadavky

Začínáme se službou gRPC v ASP.NET Core

Zobrazení nebo stažení vzorového kódu (postup stažení)

Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.

Přidání služeb gRPC do aplikace ASP.NET Core

Pro gRPC se vyžaduje balíček Grpc.AspNetCore.

Konfigurace gRPC

V Startup.cs:

  • Metoda gRPC je povolená AddGrpc .
  • Každá služba gRPC se přidá do kanálu směrování prostřednictvím MapGrpcService 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>();
        });
    }
}

Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.

ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.

Možnosti serveru

Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.

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

†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.

Kestrel

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2.

Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.

Protokol TLS

Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001 při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https ověřuje, že Kestrel koncový bod používá protokol TLS.

V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:

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

Alternativně Kestrel je možné nakonfigurovat koncové body v 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>();
        });

Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2 je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.

Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.

Poznámka:

macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.

Hostování gRPC v projektech non-ASP.NET Core

Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web jako sada 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 Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.

Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru 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>

Předchozí soubor projektu:

  • Nepoužívá Microsoft.NET.SDK.Web se jako sada SDK.
  • Přidá odkaz na architekturu do Microsoft.AspNetCore.App.
    • Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
    • Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
  • Přidá požadavky gRPC:

Další informace o použití referenční informace Microsoft.AspNetCore.App k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.

Integrace s rozhraními API ASP.NET Core

Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:

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

Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).

Řešení httpContext v metodách gRPC

Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext předaného každé metodě 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 neposkytuje úplný přístup ke HttpContext všem rozhraním API ASP.NET. Metoda GetHttpContext rozšíření poskytuje úplný přístup k HttpContext reprezentaci základní zprávy HTTP/2 v rozhraních 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
        });
    }
}

Další materiály

Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.

Požadavky

Začínáme se službou gRPC v ASP.NET Core

Zobrazení nebo stažení vzorového kódu (postup stažení)

Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.

Přidání služeb gRPC do aplikace ASP.NET Core

Pro gRPC se vyžaduje balíček Grpc.AspNetCore.

Konfigurace gRPC

V Startup.cs:

  • Metoda gRPC je povolená AddGrpc .
  • Každá služba gRPC se přidá do kanálu směrování prostřednictvím MapGrpcService 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>();
        });
    }
}

Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.

ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.

Možnosti serveru

Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.

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

†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.

Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.

Kestrel

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2.

Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.

Protokol TLS

Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001 při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https ověřuje, že Kestrel koncový bod používá protokol TLS.

V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:

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

Alternativně Kestrel je možné nakonfigurovat koncové body v 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>();
        });

Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2 je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.

Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.

Poznámka:

macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.

Hostování gRPC v projektech non-ASP.NET Core

Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web jako sada 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 Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.

Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru 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>

Předchozí soubor projektu:

  • Nepoužívá Microsoft.NET.SDK.Web se jako sada SDK.
  • Přidá odkaz na architekturu do Microsoft.AspNetCore.App.
    • Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
    • Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
  • Přidá požadavky gRPC:

Další informace o použití referenční informace Microsoft.AspNetCore.App k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.

Integrace s rozhraními API ASP.NET Core

Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:

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

Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).

Řešení httpContext v metodách gRPC

Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext předaného každé metodě 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 neposkytuje úplný přístup ke HttpContext všem rozhraním API ASP.NET. Metoda GetHttpContext rozšíření poskytuje úplný přístup k HttpContext reprezentaci základní zprávy HTTP/2 v rozhraních 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
        });
    }
}

Další materiály