build-and-test

• 只需在本地运行 UnitTest 项目；IntegrationTests 需要外部依赖。
• 有关项目结构的详细信息，请参阅 ../project-structure/SKILL.md。

构建、测试和代码检查命令

# From dotnet/ directory
dotnet restore --tl:off   # Restore dependencies for all projects
dotnet build --tl:off     # Build all projects
dotnet test               # Run all tests
dotnet format             # Auto-fix formatting for all projects

# Build/test/format a specific project (preferred for isolated/internal changes)
dotnet build src/Microsoft.Agents.AI.<Package> --tl:off
dotnet test --project tests/Microsoft.Agents.AI.<Package>.UnitTests
dotnet format src/Microsoft.Agents.AI.<Package>

# Run a single test
# Replace the filter values with the appropriate assembly, namespace, class, and method names for the test you want to run and use * as a wildcard elsewhere, e.g. "/*/*/HttpClientTests/GetAsync_ReturnsSuccessStatusCode"
# Use `--ignore-exit-code 8` to avoid failing the build when no tests are found for some projects
dotnet test --filter-query "/<assemblyFilter>/<namespaceFilter>/<classFilter>/<methodFilter>" --ignore-exit-code 8

# Run unit tests only
# Use `--ignore-exit-code 8` to avoid failing the build when no tests are found for integration test projects
dotnet test --filter-query "/*UnitTests*/*/*/*" --ignore-exit-code 8

构建时使用 --tl:off，以避免在 Agent 中运行命令时出现闪烁。

加快构建和测试

整个解决方案规模较大。请使用以下快捷方式：

更改类型	操作
独立/内部逻辑	仅构建受影响的项目及其 *.UnitTests 项目。修复问题后，再构建整个解决方案并运行所有单元测试。
公共 API 表面	立即构建整个解决方案并运行所有单元测试。

示例：为所有目标框架构建单个代码项目

# From dotnet/ directory
dotnet build ./src/Microsoft.Agents.AI.Abstractions

示例：仅针对 .NET 10 构建单个代码项目。

# From dotnet/ directory
dotnet build ./src/Microsoft.Agents.AI.Abstractions -f net10.0

示例：使用 .NET 10 运行单个项目的测试。

# From dotnet/ directory
dotnet test --project ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0

示例：使用 .NET 10 运行特定项目中的单个测试。 请提供要运行的测试的完整命名空间、类名和方法名：

# From dotnet/ directory
dotnet test --project ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0 --filter-query "/*/Microsoft.Agents.AI.Abstractions.UnitTests/AgentRunOptionsTests/CloningConstructorCopiesProperties"

多目标框架提示

大多数项目面向多个 .NET 框架。如果受影响的代码不使用 #if 指令处理特定框架的逻辑，请传入 -f net10.0，以加快构建和测试。

包还原提示

每次构建时，dotnet build 都会尝试还原所有项目的包，这可能会很慢。 除非包有变更，或这是首次构建解决方案，否则请在构建命令中添加 --no-restore，跳过此步骤并加快构建。

请记得在拉取更改、修改项目引用或首次构建时运行 dotnet restore。

在 Linux 上测试提示

单元测试面向 .NET Framework 和 .NET Core。由于 Linux 不支持 .NET Framework，在 Linux 上运行时只能运行 .NET Core 测试。

若要仅运行 .NET Core 测试，请在 dotnet test 中使用 -f net10.0 选项。

Microsoft Testing Platform（MTP）

测试通过 xUnit v3 使用 Microsoft Testing Platform。与旧版 VSTest 运行程序的主要区别如下：

• dotnet test 需要使用 --project 直接指定测试项目（不再支持位置参数）。

• 测试输出采用 MTP 格式（例如，进度显示 [✓112/x0/↓0]，测试运行摘要显示 Test run summary: Passed!）。

• TRX 报告使用 --report-xunit-trx，而非 --logger trx。

• 代码覆盖率使用 Microsoft.Testing.Extensions.CodeCoverage 和 --coverage --coverage-output-format cobertura。

• 直接运行测试项目受支持，可通过 dotnet run --project <test-project> 实现。这会绕过 dotnet test 基础设施，直接使用 MTP 命令行运行测试可执行文件。

• 使用筛选条件跨解决方案运行测试可能会导致某些项目匹配到零个测试，而 MTP 会将其视为失败（退出代码 8）。使用 --ignore-exit-code 8 可忽略此情况：

# Run all unit tests across the solution, ignoring projects with no matching tests
dotnet test --solution ./agent-framework-dotnet.slnx --no-build -f net10.0 --ignore-exit-code 8

• 使用 --solution 为特定 TFM 运行测试要求解决方案中的所有项目都支持该 TFM。并非所有项目都面向每个框架（例如，某些项目仅面向 net10.0）。请使用 ./dotnet/eng/scripts/New-FilteredSolution.ps1 生成筛选后的解决方案：

# Generate a filtered solution for net472 and run tests
$filtered = ./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net472
dotnet test --solution $filtered --no-build -f net472 --ignore-exit-code 8

# Exclude samples and keep only unit test projects
./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net10.0 -ExcludeSamples -TestProjectNameFilter "*UnitTests*" -OutputPath dotnet/filtered-unit.slnx

# Run tests via dotnet test (uses MTP under the hood)
dotnet test --project ./tests/Microsoft.Agents.AI.UnitTests -f net10.0

# Run tests with code coverage (Cobertura format)
dotnet test --project ./tests/Microsoft.Agents.AI.UnitTests -f net10.0 --coverage --coverage-output-format cobertura --coverage-settings ./tests/coverage.runsettings

# Run tests directly via dotnet run (MTP native command line)
dotnet run --project ./tests/Microsoft.Agents.AI.UnitTests -f net10.0

# Show MTP command line help
dotnet run --project ./tests/Microsoft.Agents.AI.UnitTests -f net10.0 -- -?