Incremental Builds for .NET Projects

The @nx/dotnet plugin automatically configures projects to use the --no-dependencies flag when executing .NET build commands. This optimization allows Nx to manage build orchestration through its task graph, preventing duplicate compilations and maximizing cache efficiency.

How it works

When building outside of Nx, the .NET CLI typically handles dependency resolution and builds all project references automatically. However, this approach conflicts with Nx task orchestration and caching mechanisms. By using --no-dependencies, the plugin delegates dependency management to Nx, which has full visibility into the project graph and can optimize build execution.

Target dependencies

All .NET build targets generated by the plugin include a dependsOn configuration that ensures dependencies are built in the correct order:

{
  "targets": {
    "build": {
      "command": "dotnet build",
      "dependsOn": ["^build"]
    }
  }
}

The ^build dependency tells Nx to build all upstream dependencies before building the current project. This replaces the .NET CLI's built-in dependency resolution with Nx more sophisticated task orchestration.

Why restore is not in dependsOn

The restore target is not included in the dependsOn array because Nx requires NuGet package restoration to be completed before running any tasks. Running restore through Nx task graph would create a circular dependency since Nx needs restoration completed to analyze project structure and dependencies.

Avoiding duplicate builds

Consider a workspace with the following structure:

• apps/WebApi
• libs/ClassLib

If WebApi depends on ClassLib, running commands without --no-dependencies would result in:

Without --no-dependencies

nx build WebApi

1. Nx analyzes the dependency graph and schedules nx build ClassLib
2. Nx executes dotnet build libs/ClassLib/ClassLib.csproj
   • .NET CLI builds ClassLib
3. Nx executes dotnet build apps/WebApi/WebApi.csproj
   • .NET CLI detects the ClassLib project reference
   • .NET CLI builds ClassLib again (duplicate build)
   • .NET CLI builds WebApi

nx affected -t build

1. Nx determines both WebApi and ClassLib need to be built
2. Nx runs nx build ClassLib first (due to dependency graph)
   • .NET CLI builds ClassLib
3. Nx runs nx build WebApi
   • .NET CLI builds ClassLib again (duplicate build)
   • .NET CLI builds WebApi

This means ClassLib is compiled twice during affected builds, and the duplication scales with the number of project references.

With --no-dependencies (default)

The @nx/dotnet plugin automatically adds --no-dependencies to build commands, eliminating duplicate builds:

nx build WebApi

1. Nx analyzes the dependency graph and schedules nx build ClassLib
2. Nx executes dotnet build libs/ClassLib/ClassLib.csproj --no-dependencies
   • .NET CLI builds ClassLib
3. Nx executes dotnet build apps/WebApi/WebApi.csproj --no-dependencies
   • .NET CLI builds only WebApi (skips ClassLib)

nx affected -t build

1. Nx determines both WebApi and ClassLib need to be built
2. Nx runs nx build ClassLib first
   • .NET CLI builds ClassLib
3. Nx runs nx build WebApi
   • .NET CLI builds only WebApi (no duplicate compilation)

Optimizing cache hits

The benefits extend beyond avoiding duplicate builds—--no-dependencies also maximizes cache effectiveness.

Consider a scenario where you modify only WebApi, leaving ClassLib unchanged:

Without --no-dependencies

nx affected -t build

1. Nx determines only WebApi needs rebuilding
2. Since ClassLib hasn't changed, Nx restores it from cache
3. Nx runs nx build WebApi
   • .NET CLI detects the ClassLib project reference
   • .NET CLI rebuilds ClassLib from source (ignoring the cache)
   • .NET CLI builds WebApi

The cached ClassLib output is effectively wasted because the .NET CLI rebuilds it anyway.

With --no-dependencies (default)

nx affected -t build

1. Nx determines only WebApi needs rebuilding
2. Since ClassLib hasn't changed, Nx restores it from cache
3. Nx runs nx build WebApi --no-dependencies
   • .NET CLI builds only WebApi, using the cached ClassLib output

The cache is fully utilized, dramatically improving build performance in incremental scenarios.

Target configuration

The plugin automatically configures all .NET projects with appropriate target dependencies. For example, a typical library project configuration looks like:

{
  "name": "ClassLib",
  "targets": {
    "build": {
      "command": "dotnet build",
      "options": {
        "cwd": "{projectRoot}",
        "args": ["--no-restore", "--no-dependencies"]
      },
      "dependsOn": ["^build"],
      "cache": true,
      "inputs": ["default", "^production"],
      "outputs": ["{projectRoot}/bin", "{projectRoot}/obj"]
    },
    "restore": {
      "command": "dotnet restore",
      "options": {
        "cwd": "{projectRoot}",
        "args": ["--no-dependencies"]
      },
      "dependsOn": ["^restore"],
      "cache": true
    }
  }
}

Key configuration points

• --no-dependencies: Prevents .NET from building project references
• dependsOn: ["^build"]: Ensures dependencies are built first through Nx
• cache: true: Enables Nx computation caching for the target

Build commands

Build a single project

nx build my-project

Builds the specified project and all its dependencies in the correct order.

Build all affected projects

nx affected -t build

Builds only projects affected by recent changes, along with their dependencies.

Build with parallelization

nx run-many -t build --parallel=3

Builds multiple projects in parallel when possible, respecting dependency constraints.

Best practices

Use the default configuration

The plugin automatically configures --no-dependencies for all targets. Avoid overriding this unless you have a specific reason.

Verify target dependencies

Ensure all build targets include "dependsOn": ["^build"] so Nx knows to build dependencies first. The plugin handles this automatically during project detection.

Leverage Nx cache

Enable Nx Cloud to share build cache across your team and CI/CD pipelines, maximizing the performance benefits of incremental builds.

Monitor build performance

Use the Nx graph visualization to understand your project dependencies:

nx graph

This helps identify opportunities to further optimize your build graph.

Troubleshooting

Build errors referencing missing dependencies

If you see errors like "Could not find project reference", ensure:

1. The referenced project exists in the workspace
2. The dependsOn: ["^build"] configuration is present
3. Run nx reset to clear the cache if stale