nuget-manager

NuGet Manager

Overview

This skill ensures consistent and safe management of NuGet packages across .NET projects. It prioritizes using the dotnet CLI to maintain project integrity and enforces a strict verification and restoration workflow for version updates.

Prerequisites

• .NET SDK installed (typically .NET 8.0 SDK or later, or a version compatible with the target solution).
• dotnet CLI available on your PATH.
• jq (JSON processor) OR PowerShell (for version verification using dotnet package search).

Core Rules

1. NEVER directly edit .csproj, .props, or Directory.Packages.props files to add or remove packages. Always use dotnet add package and dotnet remove package commands.
2. DIRECT EDITING is ONLY permitted for changing versions of existing packages.
3. VERSION UPDATES must follow the mandatory workflow:
   • Verify the target version exists on NuGet.
   • Determine if versions are managed per-project (.csproj) or centrally (Directory.Packages.props).
   • Update the version string in the appropriate file.
   • Immediately run dotnet restore to verify compatibility.
4. INPUT VALIDATION: Before any command runs, check every package name, version, and project value. Package names may contain only letters, digits, dots, hyphens and underscores, and must start with a letter, digit or underscore. Versions may contain only letters, digits, dots, hyphens and plus signs, and must start with a digit. Refuse any value containing quotes, spaces, dollar signs, brackets, angle brackets or other shell or markup characters, and ask the user for a corrected value. The project value must be an existing project or solution file inside the workspace. Quote every argument. Only validated values fill the placeholders in the commands below.
5. TRUSTED WORKSPACES: dotnet restore and dotnet add (which also restores) run build logic and use package sources defined by the repository. Run them only in workspaces the user trusts. Before running, review the shared build property and target files and the NuGet configuration files for unexpected targets or package sources, and ask the user first if the repository is unfamiliar or anything looks unusual.
6. FEED CREDENTIALS: Before search, add or restore, review the configured package sources and confirm any unfamiliar authenticated source with the user. Remove tokens, passwords and other credentials from any command output or error shown to the user.

Workflows

Adding a Package

Use dotnet add [<PROJECT>] package <PACKAGE_NAME> [--version <VERSION>]. Example: dotnet add src/MyProject/MyProject.csproj package Newtonsoft.Json

Before adding:

• Confirm the exact package name with the user and warn about names that differ only slightly from popular packages.
• Use the exact match search to confirm the package exists, and flag deprecated or known vulnerable packages that the tools report.
• When more than one package feed is configured, confirm with the user which feed the package should come from, and prefer mapping each package to one trusted feed.
• When the user gives no version, find the latest stable release that is not a prerelease, show it to the user, and pass it explicitly with --version.

After adding, report any vulnerability or deprecation warnings the tools show.

Removing a Package

Use dotnet remove [<PROJECT>] package <PACKAGE_NAME>. Example: dotnet remove src/MyProject/MyProject.csproj package Newtonsoft.Json

Updating Package Versions

When updating a version, follow these steps:

1. Verify Version Existence: Check if the version exists using the dotnet package search command with exact match and JSON formatting. Using jq: dotnet package search <PACKAGE_NAME> --exact-match --format json | jq -e '.searchResult[].packages[] | select(.version == "<VERSION>")' Using PowerShell: (dotnet package search <PACKAGE_NAME> --exact-match --format json | ConvertFrom-Json).searchResult.packages | Where-Object { $_.version -eq "<VERSION>" } Fill these placeholders only with values that passed the input validation rule. Confirm that the matching result comes from the feed the user intends, and treat a match from an unexpected or unfamiliar source as unverified and ask the user. The search hides prerelease versions by default, so if a prerelease target does not appear, tell the user and ask them to confirm the version before editing.

2. Determine Version Management:

   • Search for Directory.Packages.props in the solution root. If present, versions should be managed there via <PackageVersion Include="Package.Name" Version="1.2.3" />.
   • If absent, check individual .csproj files for <PackageReference Include="Package.Name" Version="1.2.3" />.
   • Versions may also be set through build properties, per project overrides under central management, or shared build property files. Edit the place where the version is actually defined, keeping any property reference in place.
   • Confirm that the file to edit is inside the repository or workspace root. If the governing props file is in a parent folder above the repository root, stop and ask the user before editing it.

3. Apply Changes: Modify the identified file with the new version string.

   • Write only a version that passed the input validation rule, and change only the value of the existing Version attribute for that package; leave all other elements and attributes as they are.
   • If the new version is lower than the current one or is a prerelease, warn the user and get confirmation before editing.
   • Before editing, check that version control shows no unrelated uncommitted changes, list every file and line to be changed, show the user the exact change, and get confirmation.

4. Verify Stability: Run dotnet restore on the project or solution. If errors occur, revert every file touched by the change and investigate. A clean restore alone does not confirm safety: report to the user any security audit, vulnerability or deprecation warnings printed during restore, and suggest listing vulnerable and deprecated packages with the dotnet list package command.

Examples

User: "Add Serilog to the WebApi project"

Action: Execute dotnet add src/WebApi/WebApi.csproj package Serilog after confirming the package name with the user; when no version is given, show the resolved latest stable version and pass it with --version.

User: "Update Newtonsoft.Json to 13.0.3 in the whole solution"

Action:

1. Verify 13.0.3 exists: dotnet package search Newtonsoft.Json --exact-match --format json (and parse output to confirm "13.0.3" is present).
2. Find where it's defined (e.g., Directory.Packages.props).
3. Edit the file to update the version.
4. Run dotnet restore.