gRPC services with ASP.NET Core
This document shows how to get started with gRPC services using ASP.NET Core.
Warning
ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. The HTTP/2 implementation of Http.Sys does not support HTTP response trailing headers which gRPC relies on. For more information, see this GitHub issue.
Prerequisites
- Visual Studio 2019 with the ASP.NET and web development workload
- .NET Core 3.0 SDK or later
Get started with gRPC service in ASP.NET Core
View or download sample code (how to download).
See Get started with gRPC services for detailed instructions on how to create a gRPC project.
Add gRPC services to an ASP.NET Core app
gRPC requires the Grpc.AspNetCore package.
Configure gRPC
In Startup.cs:
- gRPC is enabled with the
AddGrpc
method. - Each gRPC service is added to the routing pipeline through the
MapGrpcService
method.
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>();
});
}
}
If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.
ASP.NET Core middleware and features share the routing pipeline, therefore an app can be configured to serve additional request handlers. The additional request handlers, such as MVC controllers, work in parallel with the configured gRPC services.
Configure Kestrel
Kestrel gRPC endpoints:
- Require HTTP/2.
- Should be secured with Transport Layer Security (TLS).
HTTP/2
gRPC requires HTTP/2. gRPC for ASP.NET Core validates HttpRequest.Protocol is HTTP/2
.
Kestrel supports HTTP/2 on most modern operating systems. Kestrel endpoints are configured to support HTTP/1.1 and HTTP/2 connections by default.
TLS
Kestrel endpoints used for gRPC should be secured with TLS. In development, an endpoint secured with TLS is automatically created at https://localhost:5001
when the ASP.NET Core development certificate is present. No configuration is required. An https
prefix verifies the Kestrel endpoint is using TLS.
In production, TLS must be explicitly configured. In the following appsettings.json example, an HTTP/2 endpoint secured with TLS is provided:
{
"Kestrel": {
"Endpoints": {
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Protocols": "Http2",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
Alternatively, Kestrel endpoints can be configured in 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>();
});
Protocol negotiation
TLS is used for more than securing communication. The TLS Application-Layer Protocol Negotiation (ALPN) handshake is used to negotiate the connection protocol between the client and the server when an endpoint supports multiple protocols. This negotiation determines whether the connection uses HTTP/1.1 or HTTP/2.
If an HTTP/2 endpoint is configured without TLS, the endpoint's ListenOptions.Protocols must be set to HttpProtocols.Http2
. An endpoint with multiple protocols (for example, HttpProtocols.Http1AndHttp2
) can't be used without TLS because there's no negotiation. All connections to the unsecured endpoint default to HTTP/1.1, and gRPC calls fail.
For more information on enabling HTTP/2 and TLS with Kestrel, see Kestrel endpoint configuration.
Note
macOS doesn't support ASP.NET Core gRPC with TLS. Additional configuration is required to successfully run gRPC services on macOS. For more information, see Unable to start ASP.NET Core gRPC app on macOS.
Configure Kestrel
Kestrel gRPC endpoints:
- Require HTTP/2.
- Should be secured with Transport Layer Security (TLS).
HTTP/2
gRPC requires HTTP/2. gRPC for ASP.NET Core validates HttpRequest.Protocol is HTTP/2
.
Kestrel supports HTTP/2 on most modern operating systems. Kestrel endpoints are configured to support HTTP/1.1 and HTTP/2 connections by default.
TLS
Kestrel endpoints used for gRPC should be secured with TLS. In development, an endpoint secured with TLS is automatically created at https://localhost:5001
when the ASP.NET Core development certificate is present. No configuration is required. An https
prefix verifies the Kestrel endpoint is using TLS.
In production, TLS must be explicitly configured. In the following appsettings.json example, an HTTP/2 endpoint secured with TLS is provided:
{
"Kestrel": {
"Endpoints": {
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Protocols": "Http2",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
Alternatively, Kestrel endpoints can be configured in 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>();
});
Protocol negotiation
TLS is used for more than securing communication. The TLS Application-Layer Protocol Negotiation (ALPN) handshake is used to negotiate the connection protocol between the client and the server when an endpoint supports multiple protocols. This negotiation determines whether the connection uses HTTP/1.1 or HTTP/2.
If an HTTP/2 endpoint is configured without TLS, the endpoint's ListenOptions.Protocols must be set to HttpProtocols.Http2
. An endpoint with multiple protocols (for example, HttpProtocols.Http1AndHttp2
) can't be used without TLS because there's no negotiation. All connections to the unsecured endpoint default to HTTP/1.1, and gRPC calls fail.
For more information on enabling HTTP/2 and TLS with Kestrel, see Kestrel endpoint configuration.
Note
macOS doesn't support ASP.NET Core gRPC with TLS. Additional configuration is required to successfully run gRPC services on macOS. For more information, see Unable to start ASP.NET Core gRPC app on macOS.
Integration with ASP.NET Core APIs
gRPC services have full access to the ASP.NET Core features such as Dependency Injection (DI) and Logging. For example, the service implementation can resolve a logger service from the DI container via the constructor:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
By default, the gRPC service implementation can resolve other DI services with any lifetime (Singleton, Scoped, or Transient).
Resolve HttpContext in gRPC methods
The gRPC API provides access to some HTTP/2 message data, such as the method, host, header, and trailers. Access is through the ServerCallContext
argument passed to each gRPC method:
public class GreeterService : Greeter.GreeterBase
{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
ServerCallContext
doesn't provide full access to HttpContext
in all ASP.NET APIs. The GetHttpContext
extension method provides full access to the HttpContext
representing the underlying HTTP/2 message in ASP.NET APIs:
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
});
}
}