Claude code command to update nuget packages. Will both update packages and eventually create a PR using the gh CLI. Store this command at .claude/commands/ in your project.

nugetupdate.md

Update NuGet Packages

Objective

Update all NuGet packages in the MyApp solution to their latest stable versions. Use dotnet list package --outdated to discover updates, research breaking changes, update code as needed, and ensure all builds and tests pass.

License Compliance

MANDATORY: Before updating any package, check if it has license restrictions. Some packages have changed from open-source to commercial licenses, which may violate organizational policies or incur unexpected costs.

License Restrictions Table

Package	Max Safe Version	Blocked From	New License	Previous License	Alternative	Notes
FluentAssertions	5.10.3	6.0.0	Commercial (Xceed)	Apache 2.0	Shouldly	Version 6.0+ requires commercial license for organizations

How to Handle License-Restricted Packages

1. SKIP any package in the restrictions table where the latest version >= Blocked From version
2. LOG the skip with the reason: "Skipped [Package] - license changed to [New License] in version [Blocked From]"
3. SUGGEST the alternative package if one exists
4. INCLUDE in PR description under "License Compliance" section

Adding New Restrictions

If you discover a package has changed its license during the update process:

1. Research the license change thoroughly (changelog, GitHub issues, official announcements)
2. Add a new row to this table with all relevant details
3. Document the finding in the PR description
4. Suggest alternatives if known

Project Context

This is a .NET 10 ASP.NET Core application.

Source Projects

• src/MyApp.Web/MyApp.Web.csproj - Main web application
• src/MyApp.Core/MyApp.Core.csproj - Core business logic and domain models
• src/MyApp.Infrastructure/MyApp.Infrastructure.csproj - External service integrations
• src/MyApp.DevSetup/MyApp.DevSetup.csproj - Development setup utilities

Test Projects

• test/MyApp.UnitTests/MyApp.UnitTests.csproj - Unit tests
• test/MyApp.IntegrationTests/MyApp.IntegrationTests.csproj - Integration tests

Critical Requirements:

• Tests may require Docker for Testcontainers
• Follow C# 12+ conventions (see CLAUDE.md for collection expressions, primary constructors, etc.)
• All tests must pass before creating PR

Step-by-Step Instructions

1. Discovery Phase - Find ALL Outdated Packages

Use the dotnet list package --outdated command to authoritatively discover all packages that have updates available. This is more reliable than manually checking nuget.org.

1.1. Run the command to get structured JSON output:

dotnet list MyApp.sln package --outdated --format json

1.2. The JSON output provides for each outdated package:

• id: Package name
• requestedVersion: Version specified in csproj
• resolvedVersion: Actual resolved version
• latestVersion: Latest stable version available

1.3. For packages already using prerelease versions, also run:

dotnet list MyApp.sln package --outdated --include-prerelease --format json

1.4. Create an update list grouped by package category

2. Validate and Filter Updates

2.1. From the dotnet list package --outdated output, filter packages:

• SKIP packages in the License Restrictions Table (e.g., FluentAssertions >= 6.0.0)
• SKIP packages showing "Not found at the sources" (unless prerelease check is needed)
• INCLUDE all others for update

2.2. License Compliance Check (MANDATORY):

• Check each outdated package against the License Restrictions Table
• If restricted: log skip reason and add to PR's "Skipped Due to License" section

2.3. Group packages for incremental updates (same groups as Step 3)

3. Update Packages Incrementally

Update packages in logical groups to isolate breaking changes:

Group 1: Microsoft.Extensions. packages* (typically compatible together) Group 2: Microsoft.AspNetCore. packages* Group 3: Azure packages (Azure., Microsoft.Azure.) Group 4: Testing packages (xunit, Shouldly, Moq, Verify, Testcontainers) Group 5: Other packages (one at a time)

For each group:

3.1. Update version numbers in .csproj file(s) using Edit tool

3.2. Build the solution:

dotnet build MyApp.sln --configuration Release

3.3. Run tests:

dotnet test MyApp.sln --configuration Release

3.4. If build or tests fail, proceed to Step 4 (Fix Breaking Changes)

3.5. If successful, commit the changes:

git add .
git commit -m "chore(deps): update [package group name] packages"

4. Fix Breaking Changes

If build or tests fail after updating a package/group:

4.1. Research Breaking Changes

• Use WebSearch to find: "[PackageName] [OldVersion] to [NewVersion] breaking changes"
• Use WebSearch to find: "[PackageName] [NewVersion] release notes"
• Use WebFetch to read official migration guides or changelogs
• Look for:
  • API changes (renamed methods, changed signatures)
  • Removed features
  • New required configuration
  • Changed behavior

4.2. Identify Errors

• Read build error messages carefully
• Read test failure messages and stack traces
• Use Grep to find usages of problematic APIs in the codebase

4.3. Apply Fixes

• Update code to use new APIs or patterns
• Fix compilation errors
• Update tests if needed
• Follow existing code style (see CLAUDE.md)

4.4. Verify Fixes

• Rebuild: dotnet build MyApp.sln --configuration Release
• Retest: dotnet test MyApp.sln --configuration Release

4.5. Iteration Limit

• Attempt up to 3 fix iterations per package group
• If still failing after 3 attempts, document the issue and move to next group
• Keep failing package updates in place to document the attempt in PR

5. Create Feature Branch and PR

5.1. After completing all updates, build a branch name from the groups that were actually updated. Use lowercase, hyphenated group short-names joined by hyphens. If the name would exceed 60 characters, truncate to the most significant groups. Create the branch:

# Example: git checkout -b nuget-update/microsoft-testing
git checkout -b nuget-update/<slugified-group-names>

5.2. Push branch:

git push -u origin nuget-update/<slugified-group-names>

5.3. Create Pull Request using gh CLI:

PR Title: chore(deps): update <comma-separated group names> packages Example: chore(deps): update Microsoft.Extensions, Testing packages

PR Body Template:

IMPORTANT: Keep the PR description concise. ONLY list packages that were actually updated. Do NOT list packages that are already at their latest version.

## Summary

Updated [X] NuGet package(s) to their latest stable versions.

## Updated Packages

### [Package Group Name]
- **PackageName**: `1.0.0` → `2.0.0`
  - [Brief summary of changes from release notes]
  - Reference: [link to release notes]

### Failed Updates (if any)
- **ProblematicPackage**: `1.0.0` → `2.0.0`
  - Issue: [description of failure]
  - Iterations attempted: 3

## License Compliance

### Packages Skipped Due to License Restrictions
- **FluentAssertions**: Skipped (license changed to Commercial in v6.0.0)
  - Current: `5.10.3` | Latest: `7.x.x`
  - Alternative: Shouldly (Apache 2.0)

### New License Restrictions Discovered (if any)
- **[PackageName]**: License changed from [Previous] to [New] in v[Version]
  - Added to restrictions table

## Breaking Changes Fixed (if any)

1. **PackageName 2.0.0**
   - Change: [description]
   - Fix applied: [code changes made]

## Test Results

- Build: Passed (0 warnings, 0 errors)
- Tests: All [X] tests passed

5.4. Create the PR:

gh pr create --title "chore(deps): update <comma-separated group names> packages" --body "$(cat <<'EOF'
[Use template above with actual data filled in]
EOF
)"

Important Notes

• Use dotnet list package --outdated: This is the authoritative way to find updates (not WebSearch/WebFetch)
• WebSearch/WebFetch for research only: Use for breaking changes, release notes, migration guides
• Research before updating: Major version bumps likely have breaking changes
• Test after each group: Isolate which package causes issues
• Document everything: PR should be a complete record of changes
• Follow project style: See CLAUDE.md for coding conventions
• Docker may be required: Some tests use Testcontainers
• Prefer stable versions: Avoid preview/RC unless already using them
• Understand semantic versioning: Respect $ARGUMENTS scope (e.g., "minor" = only minor and patch updates)
• Check license restrictions: ALWAYS check the License Restrictions Table before updating any package
• Report new license changes: If you discover a package has changed to a commercial/restrictive license, add it to the restrictions table

Success Criteria

• All packages checked for latest versions using dotnet list package --outdated
• License restrictions checked for ALL packages before updating
• License-restricted packages correctly skipped with logged reason
• Packages updated to latest stable versions where possible (excluding license-restricted)
• Build succeeds with no warnings
• All tests pass
• Breaking changes researched and fixed
• PR created with comprehensive summary including License Compliance section
• Clear documentation of any failed updates and skipped packages

Error Handling

• If dotnet list package --outdated fails: Fall back to reading .csproj files and checking nuget.org manually
• If breaking changes are too complex: Document in PR, suggest manual review
• If tests fail after 3 fix attempts: Document issue, note in PR body
• If Docker is not available: Note in PR that integration tests couldn't run
• If package has license restriction: Skip update, log reason, include in PR License Compliance section
• If new license change discovered: Add to License Restrictions Table, document in PR, suggest alternative if known

Example Workflow

# 1. Discover ALL outdated packages (authoritative source)
Bash: dotnet list MyApp.sln package --outdated --format json
# JSON output shows:
# - Microsoft.AspNetCore.OpenApi: 10.0.1 → 10.0.2
# - Serilog: 4.0.0 → 4.1.0
# - etc.

# 2. For prerelease packages, check with --include-prerelease
Bash: dotnet list MyApp.sln package --outdated --include-prerelease --format json

# 3. Filter out license-restricted packages (FluentAssertions >= 6.0.0)
# Skip: FluentAssertions 5.10.3 → 8.8.0 (license changed to Commercial)

# 4. Update first group (e.g., Microsoft packages)
Edit src/MyApp.Web/MyApp.Web.csproj
# Change: Version="10.0.1" → Version="10.0.2" for Microsoft.AspNetCore.* packages

# 5. Build and test
Bash: dotnet build MyApp.sln --configuration Release
Bash: dotnet test MyApp.sln --configuration Release
# Success!

# 6. Commit
Bash: git add . && git commit -m "chore(deps): update Microsoft.AspNetCore packages"

# 7. If build had failed, research breaking changes
WebSearch "Microsoft.AspNetCore.OpenApi 10.0.1 to 10.0.2 breaking changes"
# Found: No breaking changes in patch version

# 8. Continue with next group...

Package Groups Reference

Microsoft.Extensions Packages

• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Configuration
• Microsoft.Extensions.Logging
• (other Microsoft.Extensions.* packages)

Microsoft.AspNetCore Packages

• Microsoft.AspNetCore.OpenApi
• Microsoft.AspNetCore.Authentication
• (other Microsoft.AspNetCore.* packages)

Testing Packages

• xunit
• xunit.runner.visualstudio
• Shouldly
• FluentAssertions
• Moq
• NSubstitute
• Verify.Xunit
• Testcontainers
• AutoBogus
• Bogus
• (other test packages)