Služby gRPC s ASP.NET Core

Článek
11/30/2023

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

Požadavky

Sada Visual Studio 2022 se sadou funkcí Vývoj pro ASP.NET a web

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

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

Visual Studio
Visual Studio Code / Visual Studio pro Mac

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:

Vyžaduje HTTP/2.
Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).

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:
- Odkaz na balíček NuGet na Grpc.AspNetCore.
- .proto Soubor.

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

Sada Visual Studio 2022 se sadou funkcí Vývoj pro ASP.NET a web

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

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

Visual Studio
Visual Studio Code / Visual Studio pro Mac

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.

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:

Vyžaduje HTTP/2.
Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).

HTTP/2

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

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

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

Poznámka:

IIS

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 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:
- Odkaz na balíček NuGet na Grpc.AspNetCore.
- .proto Soubor.

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

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

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

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

Sada Visual Studio 2022 se sadou funkcí Vývoj pro ASP.NET a web
Sada .NET 6.0 SDK

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

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

Visual Studio
Visual Studio Code / Visual Studio pro Mac

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.

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:

Vyžaduje HTTP/2.
Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).

HTTP/2

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

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

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

Poznámka:

IIS

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 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:
- Odkaz na balíček NuGet na Grpc.AspNetCore.
- .proto Soubor.

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

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

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

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

Sada Visual Studio 2019 16.8 nebo novější se sadou funkcí Vývoj pro ASP.NET a web
Sada .NET 5.0 SDK

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

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

Visual Studio
Visual Studio Code / Visual Studio pro Mac

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.

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:

Vyžaduje HTTP/2.
Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).

HTTP/2

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

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

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

Poznámka:

IIS

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 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:
- Odkaz na balíček NuGet na Grpc.AspNetCore.
- .proto Soubor.

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

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

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

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

Sada Visual Studio 2019 16.4 nebo novější se sadou funkcí Vývoj pro ASP.NET a web
Sada .NET Core 3.1 SDK

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

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

Visual Studio
Visual Studio Code / Visual Studio pro Mac

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.

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:

Vyžaduje HTTP/2.
Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).

HTTP/2

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

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

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

Poznámka:

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:
- Odkaz na balíček NuGet na Grpc.AspNetCore.
- .proto Soubor.

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

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

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

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

Visual Studio 2019 s úlohou vývoje pro ASP.NET a web
.NET Core 3.0 SDK

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

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

Visual Studio
Visual Studio Code / Visual Studio pro Mac

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.

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:

Vyžaduje HTTP/2.
Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).

HTTP/2

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

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

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

Poznámka:

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:
- Odkaz na balíček NuGet na Grpc.AspNetCore.
- .proto Soubor.

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

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

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

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