dotnet-nuget Plugin Features for Centralized .NET Package Management

The dotnet-nuget plugin provides a comprehensive skill set for converting .NET solutions to NuGet Central Package Management (CPM), featuring automated scope detection, baseline validation, conflict resolution, and detailed reporting.

The dotnet-nuget plugin in the dotnet/skills repository specializes in modernizing dependency management across .NET projects. Located under plugins/dotnet-nuget, this tooling implements a multi-step workflow that safely migrates repositories from distributed package references to a centralized Directory.Packages.props model while preserving build integrity.

Core CPM Conversion Capabilities

The plugin’s primary function is Central Package Management conversion, which consolidates version definitions into a single file. According to the skill definition in plugins/dotnet-nuget/skills/convert-to-cpm/SKILL.md, the plugin handles the entire lifecycle from audit to verification.

Scope Detection and Guard Clauses

The plugin intelligently determines the conversion target through scope detection. As defined in lines 44-49 of SKILL.md, it can process a single project, an entire solution (.sln or .slnx), or a full directory tree.

Before conversion begins, the plugin implements a guard against unsupported projects. At line 52, the workflow detects packages.config-based projects and aborts the operation, requiring users to first migrate to PackageReference format.

Baseline Capture and Safety Validation

The plugin establishes a pre-conversion baseline to ensure no regressions occur. In Step 2 (lines 54-57), the skill runs a clean build and records:

• A binary log: baseline.binlog
• A package manifest: baseline-packages.json

This baseline serves as the source of truth for post-conversion comparison.

Package Audit and Conflict Resolution

Comprehensive Package Analysis

Step 4 (lines 62-66) of the workflow executes a package audit using dotnet package list. The plugin identifies:

• Version conflicts across projects
• Conditional references with complex MSBuild conditions
• Security advisories requiring attention
• MSBuild-property-based versions requiring special handling

Interactive Conflict Resolution

When version conflicts exist, the plugin presents a conflict resolution UI. As detailed in lines 68-73, users can choose to align to the highest version already in use or apply VersionOverride attributes for specific projects. The plugin never upgrades beyond the highest version present in the original codebase.

Automated File Generation and Updates

Directory.Packages.props Creation

In Step 6 (lines 74-77), the plugin generates the central props file. It inserts <PackageVersion> entries for every unique package, maintaining alphabetical order and preserving conditional logic where applicable.

Project File Cleanup

The plugin automatically strips Version attributes from individual <PackageReference> items in project files. Lines 78-84 of SKILL.md specify that all other metadata and conditional groups remain intact, ensuring no functional changes to the build beyond version centralization.

MSBuild Property Handling

For repositories using MSBuild properties to define versions, Step 7 (lines 87-89) handles MSBuild property inlining or retention based on user decisions. The plugin cleans up now-unused properties from Directory.Build.props or other imported files.

Post-Conversion Verification and Reporting

Validation Workflow

After conversion, the plugin executes post-conversion validation (Step 8, lines 91-94). This process:

1. Re-runs a clean restore and build
2. Captures after-cpm.binlog and after-cpm-packages.json
3. Compares the results against the baseline capture

Comprehensive Report Generation

The final Step 9 (lines 97-152) generates a convert-to-cpm.md document. This report includes:

• Conflict resolution summaries
• Package diffs between baseline and post-conversion states
• Risk assessments for complex references
• Follow-up action items for manual review

Reference Documentation Architecture

The plugin ships with extensive documentation under plugins/dotnet-nuget/skills/convert-to-cpm/references/:

• validation-and-errors.md – Maps NuGet error codes (e.g., NU1507) to remediation steps
• msbuild-property-handling.md – Explains version property inlining decisions
• directory-packages-props.md – Details placement rules and inheritance for Directory.Packages.props
• audit-complexities.md – Checklist for detecting conditional references and security issues

The plugin entry point is declared in plugins/dotnet-nuget/plugin.json, which registers the skill with the automation engine.

Typical Workflow Commands

While the plugin automates these operations, the underlying commands illustrate the validation process:

# Capture baseline before conversion

dotnet clean
dotnet build -bl:baseline.binlog
dotnet package list --format json > baseline-packages.json

# Enumerate solution scope

dotnet sln list

# Audit current packages

dotnet package list --format json > audit-packages.json

# Post-conversion validation

dotnet clean
dotnet build -bl:after-cpm.binlog
dotnet package list --format json > after-cpm-packages.json

Summary

• The dotnet-nuget plugin provides automated Central Package Management conversion for .NET solutions via plugins/dotnet-nuget/skills/convert-to-cpm/SKILL.md.
• Safety features include packages.config detection, baseline capture with binary logs, and existing CPM file detection.
• The audit phase identifies version conflicts and security advisories, presenting an interactive resolution UI that respects existing version ceilings.
• Automated file updates generate Directory.Packages.props, strip version attributes from project files, and handle MSBuild property cleanup.
• Post-conversion validation compares binary logs and package lists to ensure build parity, generating a comprehensive convert-to-cpm.md report.

Frequently Asked Questions

What is the minimum .NET version required for the dotnet-nuget plugin?

The plugin targets modern .NET toolchains compatible with Central Package Management. While the skill itself coordinates conversion workflows, successful CPM adoption requires .NET SDK 6.0 or later, with full feature support available in .NET 8.0 and above.

How does the plugin handle version conflicts between projects?

The plugin runs dotnet package list to enumerate all resolved packages, then surfaces conflicts through an interactive UI. Users can align versions to the highest existing version or apply VersionOverride attributes to specific projects. The plugin never automatically upgrades to versions higher than those already present in the codebase.

Will the plugin modify my project files destructively?

No. The plugin preserves all metadata and conditional logic while only removing Version attributes from <PackageReference> elements. Before any changes, it captures a baseline build and binary log, enabling full rollback verification by comparing baseline-packages.json against after-cpm-packages.json.

Where does the plugin place the Directory.Packages.props file?

The plugin follows the rules outlined in directory-packages-props.md, creating the file at the solution root or appropriate directory level based on project hierarchy. It searches for existing Directory.Packages.props files (Step 3, lines 58-61) to prevent duplicate configurations and respects MSBuild directory inheritance patterns.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}