.NET CLI là thứ giống nhau ở mọi nơi bạn làm việc: laptop Windows, container Linux, runner CI không có giao diện. Visual Studio 2026, VS Code hay Rider đều gọi cùng một chuỗi dotnet build, dotnet test, dotnet publish ở bên dưới. Hiểu CLI nghĩa là biết chính xác điều gì xảy ra khi bạn bấm nút Build — và tái tạo được nó ở nơi không có nút nào để bấm.
Bài này bám vào .NET 10 LTS (bản vá 10.0.14): lệnh nào còn dùng được, lệnh nào đã đổi, và những chỗ dễ sai nhất khi viết script.
Mục lục
Cập nhật 2026
- .NET 10 là bản LTS đang dùng cho production; .NET 8 và .NET 9 hết hỗ trợ ngày 10/11/2026. Project mới nên target
net10.0. dotnet testcó thêm mode Microsoft.Testing.Platform (MTP), bật bằngglobal.json. Cú pháp lọc test và logger khác VSTest.- File-based app:
dotnet run app.csvàdotnet publish app.cs, Native AOT bật mặc định. Thêmdnxvàdotnet tool execđể chạy tool một lần. - Lệnh dạng noun-first (
dotnet package add,dotnet reference add) và--cli-schemađể lấy mô tả CLI dạng JSON.
Mô hình: .NET CLI là hợp đồng của SDK
dotnet là driver; mọi thứ sau nó là subcommand, đối số project/solution, rồi option. Cú pháp chung: dotnet <command> [<project|solution|file>] [options]. Không có “lệnh của IDE” và “lệnh của CI” — chỉ có cùng một SDK, phiên bản khác nhau.
Ba thói quen loại bỏ phần lớn lỗi:
- Luôn thử
--helpở đúng cấp:dotnet --help,dotnet build --help,dotnet new webapi -h. Đừng đoán flag từ bài viết cũ. - Dùng
--để tách option của CLI khỏi tham số truyền cho ứng dụng hoặc test app. - Restore là ngầm định:
new,build,run,test,publish,packđều restore.--no-restoretắt bước đó;--no-buildkéo theo--no-restore.
Trước khi debug bất kỳ lỗi build nào, xác nhận môi trường:
dotnet --version # SDK đang được chọn, có tính global.json
dotnet --info # SDK, runtime, OS, RID
dotnet --list-sdks
dotnet --list-runtimes
dotnet --list-runtimes --arch arm64 # --arch có từ .NET 10
Pin SDK cho cả team bằng global.json ở gốc repo:
{
"sdk": {
"version": "10.0.100",
"rollForward": "latestFeature"
}
}
latestFeature cho phép máy dev dùng feature band mới hơn trong cùng dòng 10.0.x, nên người có 10.0.4xx vẫn build được. dotnet --version đọc file này; nếu in ra số lạ, kiểm tra xem có global.json nào gần thư mục hiện tại hơn không.
Cho tool khác đọc CLI
--cli-schema in cây lệnh dạng JSON: arguments, options, subcommands. Dùng khi viết script sinh lệnh, shell completion, hoặc kiểm tra một flag có thật trước khi đưa vào pipeline:
dotnet build --cli-schema
dotnet completions script pwsh # bash, zsh, fish, nushell, powershell
Tạo project: dotnet new
Template của SDK 10 đã target net10.0. Chỉ định rõ khi bạn muốn kiểm soát tên, thư mục hoặc framework:
dotnet new list
dotnet new webapi -n Shop.Api -o src/Shop.Api -f net10.0
dotnet new classlib -n Shop.Domain -o src/Shop.Domain
dotnet new xunit -n Shop.Tests -o tests/Shop.Tests --dry-run
dotnet new sln -n Shop
-o là thư mục output, -n là tên assembly/namespace, -f nhận TFM. --dry-run liệt kê file sẽ được tạo mà không ghi gì; --force cần thiết khi template định ghi đè file đang có.
Hai lệnh hay bị dùng sai:
dotnet new --listlà cú pháp cũ. Từ .NET 7,--list,--search,--installđã thành subcommand:dotnet new list,dotnet new search,dotnet new install.dotnet new details <package>xem metadata của một template package trên NuGet, không phải option của template. Muốn xem option, chạydotnet new xunit -h.
Đừng chạy dotnet new khi đang đứng trong thư mục đã có project nếu không có -o: template sẽ đặt file cạnh project cũ và trộn hai cấu trúc vào nhau.
Ghép repo: solution, reference, package
dotnet sln add src/Shop.Api/Shop.Api.csproj src/Shop.Domain/Shop.Domain.csproj tests/Shop.Tests/Shop.Tests.csproj
dotnet reference add src/Shop.Domain/Shop.Domain.csproj --project src/Shop.Api/Shop.Api.csproj
dotnet package add Microsoft.EntityFrameworkCore --version 10.0.14 --project src/Shop.Api/Shop.Api.csproj
dotnet package list --project src/Shop.Api/Shop.Api.csproj
Từ .NET 10, dạng noun-first là chuẩn mới: dotnet package add, dotnet package list, dotnet reference add. Dạng cũ dotnet add package vẫn chạy nhưng đã thành alias; script mới nên dùng dạng mới để dễ đọc và dễ grep. --project cho phép đứng ở đâu cũng thao tác đúng project, thay vì phải cd vào thư mục.
Nếu repo dùng Central Package Management (Directory.Packages.props với ManagePackageVersionsCentrally), dotnet package add không cần --version; version nằm một chỗ và mọi project dùng chung.
dotnet pack -c Release tạo file .nupkg cho classlib; version lấy từ Version trong csproj hoặc -p:PackageVersion=1.2.3.
Đừng thêm reference từ app sang test. Chiều phụ thuộc đúng là test → app; nếu bạn cần ngược lại, vấn đề nằm ở ranh giới kiến trúc, không phải ở CLI.
Vòng lặp hằng ngày: restore, build, run, watch
dotnet restore Shop.sln
dotnet build Shop.sln -c Release --no-restore
dotnet build src/Shop.Api -f net10.0
dotnet run --project src/Shop.Api
dotnet run --project src/Shop.Api -c Release -- --urls http://localhost:5080
dotnet watch --project src/Shop.Api
dotnet watch test --project tests/Shop.Tests
-cchọn Debug/Release.dotnet buildvàdotnet runmặc định Debug.dotnet publishđã mặc định Release cho project target từnet8.0trở lên, nên-c Releaseở publish là để nói rõ chứ không phải bắt buộc.-fchỉ cần khi project multi-target; thiếu nó, CLI dùng target framework đầu tiên.--no-restoredùng khi restore đã chạy riêng;--no-builddùng khi binary đã build, và nó cũng bỏ luôn restore.--rất quan trọng: nó ngăn CLI diễn giải nhầm tham số của app. Viếtdotnet run --project src/Shop.Api -- --urls http://localhost:5080chứ không phảidotnet run --project src/Shop.Api --urls ....dotnet watchmặc định chạyrunvới hot reload;dotnet watch testchạy lại test khi file đổi. Gặp “rude edit” nó sẽ hỏi có restart không — trong CI hoặc script, thêm--non-interactiveđể không bị treo.
Output mặc định nằm ở bin/<config>/<tfm> và obj/. Với repo nhiều project, đặt ArtifactsPath trong Directory.Build.props hoặc dùng --artifacts-path ./artifacts để gom toàn bộ output vào một cây thư mục, tránh lẫn lộn giữa các project và tránh commit nhầm.
Test: một lệnh, hai runner
Trong .NET 10 SDK, dotnet test vẫn mặc định chạy VSTest. Để dùng MTP, khai báo trong global.json và bảo đảm mọi test project đều dùng MTP runner (MTP 1.7 trở lên):
{
"test": {
"runner": "Microsoft.Testing.Platform"
}
}
Chế độ MTP chạy song song theo test module và chọn phạm vi bằng --project / --solution / --test-modules. Các option build như -c, -f, --no-build, --no-restore giữ nguyên. Nếu bật MTP mà có một project còn VSTest, cả lần chạy báo lỗi — không có chuyện trộn lẫn.
| Runner | Lọc test | Ghi chú |
|---|---|---|
| VSTest (mặc định) | --filter "FullyQualifiedName~OrderService&TestCategory!=Integration" |
Toán tử =, !=, ~, !~, &, | |
| MTP + MSTest/NUnit | vẫn --filter như trên |
Hai framework này giữ cú pháp VSTest |
| MTP + xUnit v3 | --filter-class, --filter-method, --filter-trait |
Không nhận cú pháp VSTest |
| MTP core | --treenode-filter, --filter-uid |
Lọc theo path hoặc theo UID |
Ví dụ cùng một ý định “chỉ chạy test của OrderService”, nhưng cú pháp phụ thuộc runner:
# VSTest, hoặc MTP với MSTest/NUnit
dotnet test --filter "FullyQualifiedName~OrderService"
# MTP với xUnit v3
dotnet test --filter-class OrderServiceTests
dotnet test --filter-trait "Category=Integration"
dotnet test --filter-not-trait "Category=Slow"
# MTP core: path <Assembly>/<Namespace>/<Class>/<Method>
dotnet test --treenode-filter "/*/*/OrderServiceTests/*"
Cạm bẫy lớn nhất: dotnet test --filter "Name~Calculate" là cú pháp VSTest. Trên xUnit v3 + MTP, --filter không được framework đó đăng ký; option lạ thường khiến test app trả exit code 5 (unrecognized option) thay vì lọc đúng. Kiểm tra bằng dotnet test --help — danh sách option in ra phụ thuộc đúng các extension mà test project đăng ký.
Logger cũng đổi: --logger trx của VSTest thành --report-trx, cần package Microsoft.Testing.Extensions.TrxReport. Và MTP coi lần chạy 0 test là thất bại (exit code 8), trong khi VSTest coi là thành công — nếu bạn có project test rỗng, thêm --ignore-exit-code 8 hoặc sửa cho đúng. Với CI, --minimum-expected-tests N là cách chặn pipeline “xanh” mà không chạy test nào.
Tool: global, local manifest và dnx
dotnet ef không nằm trong SDK. Nó là tool dotnet-ef cài từ NuGet, và version của tool phải khớp dòng EF Core bạn dùng (10.x với EF Core 10). Cài local để cả team và CI dùng đúng một version:
dotnet new tool-manifest # tạo .config/dotnet-tools.json
dotnet tool install dotnet-ef --version 10.0.14
dotnet tool list
dotnet tool restore # bắt buộc trong CI sau khi clone
dotnet ef migrations add InitialCreate --project src/Shop.Api
dotnet tool update dotnet-ef
- Manifest là file commit vào repo.
dotnet tool install --globalcài vào máy, không ai khác có; version trôi theo thời gian và là nguồn lỗi “máy tôi chạy được”. dotnet tool run dotnet-efchạy tool đã cài local; với tool têndotnet-ef,dotnet eflà cách gọi quen thuộc và cũng hợp lệ.dotnet tool exec dotnet-ef -- --versiontải và chạy tool một lần, không cài, không đổiPATH. Nó tự dùng manifest local nếu có, nên version vẫn reproducible.dnx dotnet-ef --versionlà cách viết ngắn của cùng cơ chế. Lần đầu sẽ hỏi xác nhận tải package; trong CI offline, hãy pre-warm cache hoặc dùngdotnet tool restore.
File-based app: một file .cs là đủ
Từ .NET 10, bạn có thể viết, chạy và publish một ứng dụng C# từ một file duy nhất, không cần .csproj. Cấu hình nằm ngay trong file bằng các directive #::
// File: tools/hello.cs
#:package Spectre.Console@0.57.2
using Spectre.Console;
AnsiConsole.MarkupLine("[bold green]Hello from a single file[/]");
dotnet run tools/hello.cs
dotnet tools/hello.cs # shorthand
dotnet publish tools/hello.cs # Native AOT mặc định
dotnet pack tools/hello.cs # PackAsTool=true mặc định
dotnet project convert tools/hello.cs # chuyển sang project đầy đủ
#:packagecần version cụ thể, trừ khi repo dùng Central Package Management;@*để lấy bản mới nhất nhưng đừng dùng trong script cần lặp lại kết quả.#:sdk Microsoft.NET.Sdk.Webbiến file thành app ASP.NET Core;#:propertyđặt MSBuild property;#:projecttham chiếu project khác.#:includecó từ SDK 10.0.300 để gộp thêm file.- Native AOT bật mặc định khi publish. Nếu package dùng reflection/serialization không tương thích, thêm
#:property PublishAot=falsevà kiểm tra lại kích thước, thời gian build. - Không đặt file trong thư mục có
.csproj: khi đódotnet run app.cssẽ chạy project và truyềnapp.csnhư một argument. Dùng--file app.csđể chỉ định chắc chắn. Build cache của file-based app có thể gây khó hiểu; xóa bằngdotnet clean file-based-apps. - Dùng cho script, prototype, CLI nội bộ. Cần nhiều project, test project, DI phức tạp hoặc publish container nhiều tầng — quay lại
.csproj.
Publish và container image
dotnet publish src/Shop.Api -c Release -r linux-x64 --self-contained false -o artifacts/api
dotnet publish src/Shop.Api -c Release -r linux-x64 -p:PublishAot=true
dotnet publish src/Shop.Api -c Release --os linux --arch x64 /t:PublishContainer \
-p:ContainerRepository=shop/api \
-p:ContainerFamily=alpine \
-p:ContainerImageTags='"1.2.3;latest"'
-otính từ thư mục hiện tại, không phải từ thư mục project — đây là lỗi hay gặp khi chạy từ gốc repo.-rphải đi kèm--self-containedhoặc--no-self-contained;--os/--archlà cách viết tắt của RID.- AOT và trimming chỉ hữu ích khi đã test kỹ: reflection, serializer động, DI theo tên đều có thể vỡ lúc runtime. Đo bằng thời gian khởi động và kích thước thật, không tin benchmark trên blog.
/t:PublishContainerđể SDK tự build OCI image, không cần Dockerfile; Docker/Podman chỉ cần khi muốn chạy image.ContainerFamilycó từ .NET 8 (ví dụalpine),ContainerImageTagstạo nhiều tag, cònContainerImageFormat=OCImới có trong .NET 10.- Trong .NET 10, console app publish container được mà không cần
EnableSdkContainerSupport. Muốn quét image trước khi push, dùng-p:ContainerArchiveOutputPath=./images/api.tar.gz; muốn đẩy thẳng, thêm-p:ContainerRegistry=ghcr.io.
Các nhóm lệnh còn lại
- workload:
dotnet workload list,dotnet workload search,dotnet workload install maui,dotnet workload update. Chỉ cài workload bạn thật sự dùng; chúng chiếm dung lượng lớn và có thể làm lệch môi trường giữa các máy. - nuget:
dotnet nuget list source,dotnet nuget add source <url> --name internal,dotnet nuget push <file.nupkg> --source internal,dotnet nuget locals all --clear. - ef:
dotnet ef migrations add <name>,dotnet ef database update,dotnet ef migrations list. Nhớ rằng migration chạy qua tool, không qua SDK. - format:
dotnet format --verify-no-changestrong CI để chặn diff định dạng;dotnet formatở máy dev để sửa. - dev-certs:
dotnet dev-certs https --trustkhi HTTPS local báo lỗi chứng chỉ.
Một ngày làm việc thực tế
# 1. Dựng solution
dotnet new sln -n Shop
dotnet new webapi -n Shop.Api -o src/Shop.Api -f net10.0
dotnet new classlib -n Shop.Domain -o src/Shop.Domain
dotnet new xunit -n Shop.Tests -o tests/Shop.Tests
dotnet sln add src/Shop.Api/Shop.Api.csproj src/Shop.Domain/Shop.Domain.csproj tests/Shop.Tests/Shop.Tests.csproj
dotnet reference add src/Shop.Domain/Shop.Domain.csproj --project src/Shop.Api/Shop.Api.csproj
# 2. Vòng lặp dev
dotnet watch test --project tests/Shop.Tests
dotnet watch --project src/Shop.Api
# 3. Trước khi push
dotnet format --verify-no-changes
dotnet build Shop.sln -c Release
dotnet test tests/Shop.Tests -c Release --no-build
dotnet package list --vulnerable
# 4. Xuất bản
dotnet publish src/Shop.Api -c Release -r linux-x64 --self-contained false -o artifacts/api
dotnet publish src/Shop.Api -c Release --os linux --arch x64 /t:PublishContainer -p:ContainerRepository=shop/api
Cạm bẫy thường gặp
| Triệu chứng | Nguyên nhân | Cách sửa |
|---|---|---|
dotnet run app.cs chạy nhầm project |
Thư mục hiện tại có .csproj |
Dùng --file app.cs hoặc chuyển file ra thư mục riêng |
--no-build báo thiếu project.assets.json |
--no-build kéo theo --no-restore |
Chạy dotnet restore hoặc bỏ --no-build |
| Filter không lọc gì, exit code 5 | Cú pháp VSTest dùng trên MTP + xUnit v3 | Dùng --filter-class/--filter-trait, xem dotnet test --help |
| Máy này chạy, máy kia lỗi | Global tool hoặc SDK khác version | Pin global.json + local tool manifest + dotnet tool restore |
| Publish ra sai thư mục | -o tính từ cwd, không phải project |
Dùng đường dẫn tuyệt đối hoặc chạy từ gốc repo |
Checklist trước khi đưa vào CI
- Pin SDK trong
global.jsonvà commit.config/dotnet-tools.json. - Target
net10.0; lên kế hoạch bỏnet8.0/net9.0trước ngày 10/11/2026. - Chốt runner test: VSTest hay MTP. Nếu MTP, kiểm tra cú pháp filter của đúng framework và thêm
--minimum-expected-tests. - CI chạy
dotnet restoremột lần, sau đóbuild --no-restorevàtest --no-build; không để mỗi bước restore lại. - Pin
ContainerImageTags, chọnContainerFamilyphù hợp, quétdotnet package list --vulnerablevà image scan trước khi push. - Script dùng dạng noun-first và luôn có
--khi truyền tham số cho app/test.
Nhìn sang 2027
.NET 11 đang ở RC3 và dự kiến GA trong tháng 11/2026, nhưng là bản STS chỉ được hỗ trợ hai năm; .NET 12 LTS mới là mốc tiếp theo cho production. Về CLI, hướng đi khá rõ: MTP dần thay VSTest làm runner mặc định, file-based app được mở rộng, và --cli-schema trở thành đầu vào cho các công cụ AI/agent cần biết chính xác flag nào tồn tại. Hiểu CLI ngay bây giờ vẫn rẻ hơn sửa pipeline sau này.



