Quản lý tham chiếu Protobuf với dotnet-grpc

Nguồn: Manage Protobuf references with dotnet-grpc

dotnet-grpc là một .NET Global Tool (công cụ toàn cục .NET) để quản lý các tham chiếu Protobuf (.proto) trong một .NET gRPC project. Công cụ có thể được sử dụng để thêm, làm mới, xóa, và liệt kê các tham chiếu Protobuf.

Cài đặt

Để cài đặt dotnet-grpc như một .NET Global Tool, chạy lệnh sau:

dotnetcli

dotnet tool install -g dotnet-grpc

Lưu ý: Theo mặc định, kiến trúc của các .NET binary để cài đặt đại diện cho kiến trúc hệ điều hành đang chạy. Để chỉ định kiến trúc khác, hãy xem cách sử dụng lệnh dotnet tool install với tùy chọn --arch.

Thêm tham chiếu

dotnet-grpc có thể được sử dụng để thêm các tham chiếu Protobuf dưới dạng các mục <Protobuf /> vào file .csproj:

xml

<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />

Các tham chiếu Protobuf được sử dụng để tạo các C# client và/hoặc server assets. Công cụ dotnet-grpc có thể:

Tạo tham chiếu Protobuf từ các file cục bộ trên đĩa.
Tạo tham chiếu Protobuf từ một file từ xa được chỉ định bởi URL.
Đảm bảo các phụ thuộc package gRPC chính xác được thêm vào project.

Ví dụ, package Grpc.AspNetCore được thêm vào một web app. Grpc.AspNetCore chứa các thư viện gRPC server và client cùng với hỗ trợ tooling. Ngoài ra, các package Grpc.Net.Client, Grpc.Tools và Google.Protobuf, chỉ chứa thư viện gRPC client và hỗ trợ tooling, được thêm vào một Console app.

Thêm file

Lệnh add-file được dùng để thêm các file cục bộ trên đĩa dưới dạng tham chiếu Protobuf. Các đường dẫn file được cung cấp:

Có thể là đường dẫn tương đối so với thư mục hiện tại hoặc đường dẫn tuyệt đối.
Có thể chứa ký tự đại diện (wildcards) cho pattern-based file globbing.

Nếu bất kỳ file nào nằm ngoài thư mục project, một phần tử Link được thêm để hiển thị file trong thư mục Protos trong Visual Studio.

Cách sử dụng

dotnetcli

dotnet-grpc add-file [options] <files>...

Tham số

Tham số	Mô tả
files	Các tham chiếu file protobuf. Đây có thể là đường dẫn để glob cho các file protobuf cục bộ.

Tùy chọn

Tùy chọn ngắn	Tùy chọn dài	Mô tả
-p	--project	Đường dẫn đến file project để thao tác. Nếu không có file nào được chỉ định, lệnh sẽ tìm kiếm trong thư mục hiện tại.
-s	--services	Loại gRPC service cần được tạo. Nếu `Default` được chỉ định, `Both` được dùng cho Web project và `Client` được dùng cho non-Web project. Các giá trị được chấp nhận: `Both`, `Client`, `Default`, `None`, `Server`.
-i	--additional-import-dirs	Các thư mục bổ sung để sử dụng khi phân giải imports cho các file protobuf. Đây là danh sách các đường dẫn được phân tách bởi dấu chấm phẩy.
	--access	Access modifier (bộ sửa đổi truy cập) để dùng cho các lớp C# được tạo. Giá trị mặc định là `Public`. Các giá trị được chấp nhận: `Internal` và `Public`.

Thêm URL

Lệnh add-url được dùng để thêm một file từ xa được chỉ định bởi source URL dưới dạng tham chiếu Protobuf. Đường dẫn file phải được cung cấp để chỉ định nơi tải file từ xa về. Đường dẫn file có thể là tương đối so với thư mục hiện tại hoặc tuyệt đối. Nếu đường dẫn file nằm ngoài thư mục project, một phần tử Link được thêm để hiển thị file trong thư mục ảo Protos trong Visual Studio.

Cách sử dụng

dotnetcli

dotnet-grpc add-url [options] <url>

Tham số

Tham số	Mô tả
url	URL đến file protobuf từ xa.

Tùy chọn

Tùy chọn ngắn	Tùy chọn dài	Mô tả
-o	--output	Chỉ định đường dẫn tải xuống cho file protobuf từ xa. Đây là tùy chọn bắt buộc.
-p	--project	Đường dẫn đến file project để thao tác. Nếu không có file nào được chỉ định, lệnh tìm kiếm trong thư mục hiện tại.
-s	--services	Loại gRPC service cần được tạo. Nếu `Default` được chỉ định, `Both` được dùng cho Web project và `Client` được dùng cho non-Web project. Các giá trị được chấp nhận: `Both`, `Client`, `Default`, `None`, `Server`.
-i	--additional-import-dirs	Các thư mục bổ sung để sử dụng khi phân giải imports cho các file protobuf. Đây là danh sách đường dẫn được phân tách bởi dấu chấm phẩy.
	--access	Access modifier để dùng cho các lớp C# được tạo. Giá trị mặc định là `Public`. Các giá trị được chấp nhận: `Internal` và `Public`.

Xóa

Lệnh remove được dùng để xóa các tham chiếu Protobuf khỏi file .csproj. Lệnh chấp nhận tham số là đường dẫn và source URL. Công cụ:

Chỉ xóa tham chiếu Protobuf.
Không xóa file .proto, ngay cả khi file đó ban đầu được tải xuống từ một URL từ xa.

Cách sử dụng

dotnetcli

dotnet-grpc remove [options] <references>...

Tham số

Tham số	Mô tả
references	Các URL hoặc đường dẫn file của các tham chiếu protobuf cần xóa.

Tùy chọn

Tùy chọn ngắn	Tùy chọn dài	Mô tả
-p	--project	Đường dẫn đến file project để thao tác. Nếu không có file nào được chỉ định, lệnh tìm kiếm trong thư mục hiện tại.

Làm mới

Lệnh refresh được dùng để cập nhật một tham chiếu từ xa với nội dung mới nhất từ source URL. Cả đường dẫn file tải xuống và source URL đều có thể được dùng để chỉ định tham chiếu cần cập nhật. Lưu ý:

Hash của nội dung file được so sánh để xác định xem file cục bộ có cần cập nhật không.
Không có thông tin timestamp nào được so sánh.

Công cụ luôn thay thế file cục bộ bằng file từ xa nếu cần cập nhật.

Cách sử dụng

dotnetcli

dotnet-grpc refresh [options] [<references>...]

Tham số

Tham số	Mô tả
references	Các URL hoặc đường dẫn file đến các tham chiếu protobuf từ xa cần cập nhật. Để trống tham số này để làm mới tất cả các tham chiếu từ xa.

Tùy chọn

Tùy chọn ngắn	Tùy chọn dài	Mô tả
-p	--project	Đường dẫn đến file project để thao tác. Nếu không có file nào được chỉ định, lệnh tìm kiếm trong thư mục hiện tại.
	--dry-run	Xuất ra danh sách các file sẽ được cập nhật mà không tải xuống nội dung mới.

Liệt kê

Lệnh list được dùng để hiển thị tất cả các tham chiếu Protobuf trong file project. Nếu tất cả các giá trị của một cột là giá trị mặc định, cột đó có thể bị bỏ qua.

Cách sử dụng

dotnetcli

dotnet-grpc list [options]

Tùy chọn

Tùy chọn ngắn	Tùy chọn dài	Mô tả
-p	--project	Đường dẫn đến file project để thao tác. Nếu không có file nào được chỉ định, lệnh tìm kiếm trong thư mục hiện tại.