Nguon: Microsoft Learn · .NET 8.0

gRPC services với ASP.NET Core

Nguồn: gRPC services with ASP.NET Core

Tài liệu này hướng dẫn cách bắt đầu với gRPC services sử dụng ASP.NET Core.

Điều kiện tiên quyết

Visual Studio

Visual Studio Code

Các hướng dẫn Visual Studio Code sử dụng .NET CLI cho các chức năng phát triển ASP.NET Core như tạo project. Bạn có thể làm theo các hướng dẫn này trên macOS, Linux, hoặc Windows và với bất kỳ trình soạn thảo code nào. Có thể cần thay đổi nhỏ nếu bạn sử dụng thứ khác ngoài Visual Studio Code.

Bắt đầu với gRPC service trong ASP.NET Core

Xem hoặc tải xuống mã mẫu

Visual Studio

Xem Get started with gRPC services để biết hướng dẫn chi tiết về cách tạo gRPC project.

Visual Studio Code

Chạy dotnet new grpc -o GrpcGreeter từ command line.

Thêm gRPC services vào ứng dụng ASP.NET Core

gRPC yêu cầu package Grpc.AspNetCore.

Cấu hình gRPC

Trong Program.cs:

csharp
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Cần cấu hình thêm để chạy gRPC thành công trên macOS.
// Để biết hướng dẫn cấu hình Kestrel và gRPC clients trên macOS, 
// truy cập https://go.microsoft.com/fwlink/?linkid=2099682

// Thêm services vào container.
builder.Services.AddGrpc();

var app = builder.Build();

// Cấu hình HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Giao tiếp với gRPC endpoints phải được thực hiện thông qua gRPC client. " +
    "Để tìm hiểu cách tạo client, truy cập: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

ASP.NET Core middleware và các tính năng chia sẻ routing pipeline, vì vậy ứng dụng có thể được cấu hình để phục vụ các request handler bổ sung. Các request handler bổ sung, chẳng hạn như MVC controllers, hoạt động song song với các gRPC services đã cấu hình.

Tùy chọn server

gRPC services có thể được host bởi tất cả các server ASP.NET Core tích hợp sẵn.

†Yêu cầu .NET 5 và Windows 11 Build 22000 hoặc Windows Server 2022 Build 20348 trở lên.

Để biết thêm thông tin về việc chọn server phù hợp cho ứng dụng ASP.NET Core, xem Web server implementations in ASP.NET Core.

Kestrel

Kestrel là web server cross-platform (đa nền tảng) cho ASP.NET Core. Kestrel tập trung vào hiệu suất cao và sử dụng bộ nhớ, nhưng không có một số tính năng nâng cao trong HTTP.sys như port sharing.

Kestrel gRPC endpoints:

HTTP/2

gRPC yêu cầu HTTP/2. gRPC cho ASP.NET Core xác thực HttpRequest.Protocol là HTTP/2.

Kestrel hỗ trợ HTTP/2 trên hầu hết các hệ điều hành hiện đại. Kestrel endpoints được cấu hình để hỗ trợ cả kết nối HTTP/1.1 và HTTP/2 theo mặc định.

TLS

Kestrel endpoints dùng cho gRPC nên được bảo mật bằng TLS. Trong môi trường development, một endpoint được bảo mật bằng TLS tự động được tạo tại https://localhost:5001 khi có ASP.NET Core development certificate. Không cần cấu hình. Tiền tố https xác nhận Kestrel endpoint đang sử dụng TLS.

Trong môi trường production, TLS phải được cấu hình tường minh. Trong ví dụ appsettings.json sau, một HTTP/2 endpoint được bảo mật bằng TLS được cung cấp:

json
{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<đường dẫn đến file .pfx>",
          "Password": "<mật khẩu certificate>"
        }
      }
    }
  }
}

Ngoài ra, Kestrel endpoints có thể được cấu hình trong Program.cs:

csharp
var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<đường dẫn đến file .pfx>",
            "<mật khẩu certificate>");
    });
});

Để biết thêm thông tin về việc bật TLS với Kestrel, xem Kestrel HTTPS endpoint configuration.

Protocol negotiation (đàm phán giao thức)

TLS được sử dụng không chỉ để bảo mật giao tiếp. Handshake Application-Layer Protocol Negotiation (ALPN) của TLS được sử dụng để đàm phán giao thức kết nối giữa client và server khi endpoint hỗ trợ nhiều giao thức. Quá trình đàm phán này xác định liệu kết nối sử dụng HTTP/1.1 hay HTTP/2.

Nếu một HTTP/2 endpoint được cấu hình mà không có TLS, ListenOptions.Protocols của endpoint phải được đặt thành HttpProtocols.Http2. Một endpoint với nhiều giao thức, chẳng hạn như HttpProtocols.Http1AndHttp2, không thể được sử dụng mà không có TLS vì không có đàm phán. Tất cả các kết nối đến endpoint không bảo mật mặc định là HTTP/1.1 và các lệnh gọi gRPC thất bại.

Để biết thêm thông tin về việc bật HTTP/2 và TLS với Kestrel, xem Kestrel endpoint configuration.

macOS không hỗ trợ ASP.NET Core gRPC với TLS trước .NET 8. Cần cấu hình thêm để chạy thành công gRPC services trên macOS khi sử dụng .NET 7 hoặc trước đó. Để biết thêm thông tin, xem Unable to start ASP.NET Core gRPC app on macOS.

IIS

Internet Information Services (IIS) là Web Server linh hoạt, bảo mật và có thể quản lý để host các web app, bao gồm ASP.NET Core. Cần .NET 5 và Windows 11 Build 22000 hoặc Windows Server 2022 Build 20348 trở lên để host gRPC services với IIS.

IIS phải được cấu hình để sử dụng TLS và HTTP/2. Để biết thêm thông tin, xem Use ASP.NET Core with HTTP/2 on IIS.

HTTP.sys

HTTP.sys là web server cho ASP.NET Core chỉ chạy trên Windows. Cần .NET 5 và Windows 11 Build 22000 hoặc Windows Server 2022 Build 20348 trở lên để host gRPC services với HTTP.sys.

HTTP.sys phải được cấu hình để sử dụng TLS và HTTP/2. Để biết thêm thông tin, xem HTTP.sys web server HTTP/2 support.

Host gRPC trong các project không phải ASP.NET Core

Một ASP.NET Core gRPC server thường được tạo từ gRPC template. File project được tạo bởi template sử dụng Microsoft.NET.SDK.Web làm SDK:

xml
<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

Giá trị Microsoft.NET.SDK.Web SDK tự động thêm tham chiếu đến ASP.NET Core framework. Tham chiếu cho phép ứng dụng sử dụng các ASP.NET Core type cần thiết để host server.

Bạn có thể thêm gRPC server vào các project không phải ASP.NET Core với các cài đặt file project sau:

xml
<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>

File project trên:

Để biết thêm thông tin về việc sử dụng Microsoft.AspNetCore.App framework reference, xem Use the ASP.NET Core shared framework.

Tích hợp với ASP.NET Core APIs

gRPC services có toàn quyền truy cập vào các tính năng ASP.NET Core như dependency injection (DI - tiêm phụ thuộc) và logging (ghi nhật ký). Ví dụ: triển khai service có thể resolve một logger service từ DI container.

Constructor injection (tiêm qua constructor):

csharp
public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;

    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }
}

Primary constructor injection (.NET 8 trở lên):

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

Theo mặc định, triển khai gRPC service có thể resolve các DI service khác với bất kỳ lifetime nào (Singleton, Scoped, hoặc Transient).

Resolve HttpContext trong các gRPC method

gRPC API cung cấp quyền truy cập vào một số dữ liệu HTTP/2 message, chẳng hạn như method, host, header và trailer. Truy cập thông qua tham số ServerCallContext được truyền vào mỗi gRPC method:

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

ServerCallContext không cung cấp toàn quyền truy cập vào HttpContext trong tất cả các ASP.NET API. Phương thức mở rộng GetHttpContext cung cấp toàn quyền truy cập vào HttpContext đại diện cho HTTP/2 message cơ bản trong các ASP.NET API:

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