Služby gRPC s ASP.NET Core

  • Článek
  • 3 min ke čtení

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

Upozornění

ASP.NET Core gRPC má další požadavky pro použití s Azure App Service nebo službou IIS. Další informace o tom, kde lze použít gRPC, naleznete v tématu gRPC na platformách podporovaných .NET .

Požadavky

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

Zobrazení nebo stažení ukázkového kódu (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 ASP.NET Core aplikace

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

Konfigurace gRPC

V souboru Startup.cs:

  • GRPC je povoleno s metodou 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ž angličtiny, dejte nám vědět v tomto problému diskuze na GitHubu.

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

Možnosti serveru

Služby gRPC mohou být hostovány všemi integrovanými ASP.NET Core servery.

  • Kestrel
  • Testovací server
  • IIS†
  • HTTP.sys‡

†Služba IIS vyžaduje .NET 5 a Windows 10 Build 20300.1000 nebo novější.
‡HTTP.sys vyžaduje .NET 5 a Windows 10 Build 19529 nebo novější.

Předchozí verze Windows 10 sestavení mohou vyžadovat použití sestavení Windows Insider.

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

Kestrel

Kestrelje webový server pro více platforem pro ASP.NET Core. Kestrel poskytuje nejlepší výkon a využití 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ěří, že HttpRequest.Protocol je HTTP/2 .

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

TLS

Kestrel Koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Ve vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří v , když https://localhost:5001 ASP.NET Core certifikát pro vývoj. 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>"
        }
      }
    }
  }
}

Další možností je Kestrel nakonfigurovat koncové body v souboru 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í tls s najdete v Kestrel tématu Konfigurace Kestrel koncového bodu HTTPS.

Vyjednávání protokolu

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

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být protokol ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2 . Koncový bod s více protokoly (například ) není možné použít bez protokolu TLS, protože neexistuje HttpProtocols.Http1AndHttp2 žádné vyjednávání. Všechna připojení k nezabezpečenému koncovému bodu ve výchozím nastavení http/1.1 a volání gRPC selžou.

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

Poznámka

MacOS nepodporuje gRPC ASP.NET Core TLS. K úspěšnému spuštění služeb gRPC v macOS se vyžaduje další konfigurace. Další informace najdete v tématu Nelze spustit 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 se službou IIS se vyžaduje .NET 5 a Windows 10 Build 20300.1000 nebo novější, který může vyžadovat použití sestavení Windows Insider.

Služba IIS musí být nakonfigurovaná na používání 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 na Windows. K hostování služeb gRPC pomocí služby HTTP.sys se vyžaduje .NET 5 a Windows 10 Build 19529 nebo novější, což může vyžadovat použití sestavení Windows Insider.

HTTP.sys musí být nakonfigurované na používání protokolů TLS a HTTP/2. Další informace najdete v tématu HTTP.sys http/2 webového serveru.

Kestrel

Kestrelje webový server pro více platforem pro ASP.NET Core. Kestrel poskytuje nejlepší výkon a využití 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ěří, že HttpRequest.Protocol je HTTP/2 .

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

TLS

Kestrel Koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Ve vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří v , když https://localhost:5001 ASP.NET Core certifikát pro vývoj. 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>"
        }
      }
    }
  }
}

Další možností je Kestrel nakonfigurovat koncové body v souboru 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í tls s najdete v Kestrel tématu Konfigurace Kestrel koncového bodu HTTPS.

Vyjednávání protokolu

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

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být protokol ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2 . Koncový bod s více protokoly (například ) není možné použít bez protokolu TLS, protože neexistuje HttpProtocols.Http1AndHttp2 žádné vyjednávání. Všechna připojení k nezabezpečenému koncovému bodu ve výchozím nastavení http/1.1 a volání gRPC selžou.

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

Poznámka

MacOS nepodporuje gRPC ASP.NET Core TLS. K úspěšnému spuštění služeb gRPC v macOS se vyžaduje další konfigurace. Další informace najdete v tématu Nelze spustit ASP.NET Core gRPC v systému macOS.

Integrace s ASP.NET Core API

Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako jsou 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 IN 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 překládá další služby PRO 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 upoutávky. Přístup je prostřednictvím ServerCallContext argumentu 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
        });
    }
}

ServerCallContextneposkytuje úplný přístup ke všem HttpContext rozhraním API ASP.NET rozhraní API. Metoda rozšíření poskytuje úplný přístup k reprezentující podkladovou zprávu GetHttpContext HttpContext HTTP/2 v ASP.NET rozhraní API:

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