build-and-test

• ローカルで実行する必要があるのは UnitTest プロジェクトのみです。IntegrationTests には外部依存関係が必要です。
• プロジェクト構造の詳細については、../project-structure/SKILL.md を参照してください。

ビルド、テスト、Lint コマンド

# 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 を使用してください。

ビルドとテストを高速化する

ソリューション全体は大規模です。次の方法で時間を短縮できます。

変更の種類	対応方法
限定的／内部ロジック	影響を受けるプロジェクトとその *.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 がサポートされていないため、.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 レポートには --logger trx ではなく --report-xunit-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

• 特定の TFM に対して --solution を使ってテストを実行するには、ソリューション内のすべてのプロジェクトがその 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 -- -?