NuGet Management - DotNET Build Buddy

Overview

DotNET Build Buddy includes powerful NuGet package compatibility features that help you avoid compatibility issues before they cause runtime problems.

Features

Real-time Compatibility Checks

Automatically verifies package compatibility with your target framework using the NuGet.org API.

Inline Diagnostics

See errors and warnings directly in your project files with detailed tooltips.

Smart Version Suggestions

Get recommendations for compatible package versions when you’re using an incompatible one.

Alternative Packages

Discover modern alternatives for deprecated or incompatible packages.

Transitive Dependencies

Check compatibility of dependencies of dependencies (indirect dependencies).

Framework Upgrades

Get suggestions to upgrade your target framework when all packages support newer versions.

How It Works

Compatibility Checking Process

Project File Detection

When you open or update a project file (.csproj, .fsproj, .vbproj), the extension reads:

Target framework (<TargetFramework>)
Package references (<PackageReference>)

Package Validation

For each package, the extension:

Checks the local compatibility rules database
Queries NuGet.org API for package metadata (if enabled)
Verifies framework compatibility
Checks version existence and compatibility

Issue Detection

The extension identifies three types of issues:

Incompatible: Package doesn’t support the target framework
Version Mismatch: Version doesn’t exist or is incompatible
Deprecated: Package or version is deprecated

Enhanced Suggestions

For each issue, the extension provides:

Suggested compatible versions
Alternative package recommendations
Transitive dependency warnings
Framework upgrade suggestions

Visual Feedback

Issues are displayed as:

Red squiggly lines for errors (incompatible)
Yellow squiggly lines for warnings (version mismatch, deprecated)
Detailed tooltips on hover
Entries in the Problems panel (Ctrl+Shift+M)

Inline Diagnostics

Visual Indicators

When you open a project file with compatibility issues:

MyProject.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
    <!-- Red squiggly line under Include attribute -->
    <PackageReference Include="EntityFramework" Version="6.4.4" />
    
    <!-- Yellow squiggly line -->
    <PackageReference Include="Newtonsoft.Json" Version="99.0.0" />
  </ItemGroup>
</Project>

Hover over the underlined package to see detailed information:

Incompatible Package
Version Mismatch
Deprecated Package
Transitive Issues

❌ EntityFramework: Package is not compatible with net8.0

💡 Suggested version: 6.4.4 (if compatible version exists)

🔄 Alternative: Microsoft.EntityFrameworkCore (8.0.0)
   Recommendation: Modern Entity Framework Core for .NET Core/.NET 5+

📝 This package requires: net40, net45, net46, net461, net462, net47, net471, net472, net48

⚠️ Newtonsoft.Json: Package version 99.0.0 not found

💡 Suggested version: 13.0.3

📝 Recommendation: Latest version is 13.0.3

⚠️ Microsoft.AspNet.Mvc: Package is deprecated

🔄 Alternative: Microsoft.AspNetCore.Mvc (8.0.0)
   Recommendation: Modern ASP.NET Core MVC for .NET Core/.NET 5+

📝 Recommendation: Consider using an alternative package

❌ PackageA: Package is not compatible with net8.0

💡 Suggested version: 2.0.0

⚠️ Transitive dependency issues:
  • DependencyB 1.0.0: Not compatible with net8.0
  • DependencyC: Version mismatch

Problems Panel

All issues also appear in the Problems panel:

Open Problems panel: Ctrl+Shift+M
Filter by “DotNET Build Buddy”
Click on an issue to navigate to the source

Package Suggestions

Version Suggestions

When you use an incompatible or non-existent version, the extension suggests compatible versions:

How Versions Are Suggested

The extension:

Fetches all available versions from NuGet.org
Filters versions compatible with your target framework
Suggests the latest compatible version
Falls back to the latest version if compatibility can’t be determined

Example:

<!-- You have -->
<PackageReference Include="Serilog" Version="2.0.0" />

<!-- Suggestion: Upgrade to 3.1.1 (latest compatible) -->

Applying Suggestions

To apply a suggested version:

Hover over the underlined package
Note the suggested version in the tooltip
Manually update the Version attribute

<!-- Before -->
<PackageReference Include="Serilog" Version="2.0.0" />

<!-- After -->
<PackageReference Include="Serilog" Version="3.1.1" />

Auto-fix quick actions are not currently available, but may be added in future versions.

Alternative Packages

For incompatible or deprecated packages, the extension suggests modern alternatives:

EntityFramework → EF Core
ASP.NET → ASP.NET Core
Newtonsoft.Json → System.Text.Json

<!-- Legacy (incompatible with .NET Core/.NET 5+) -->
<PackageReference Include="EntityFramework" Version="6.4.4" />

<!-- Suggested Alternative -->
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />

Why: EntityFramework (classic) only supports .NET Framework. Modern .NET requires Entity Framework Core.

<!-- Legacy -->
<PackageReference Include="Microsoft.AspNet.Mvc" Version="5.2.9" />
<PackageReference Include="System.Web.Mvc" Version="5.2.9" />

<!-- Suggested Alternative -->
<PackageReference Include="Microsoft.AspNetCore.Mvc" Version="8.0.0" />

Why: ASP.NET MVC is legacy. ASP.NET Core MVC is the modern replacement for .NET Core/.NET 5+.

<!-- Common (still compatible) -->
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

<!-- Modern Alternative -->
<PackageReference Include="System.Text.Json" Version="8.0.0" />

Why: System.Text.Json is built into modern .NET and offers better performance. Note: Newtonsoft.Json is still compatible and widely used.

Alternative suggestions are based on a curated database of common migration paths. Not all packages have alternatives suggested.

Framework Upgrade Suggestions

When all your packages support a newer framework, you’ll receive upgrade suggestions.

How It Works

Analysis

The extension checks each package against newer frameworks in the upgrade path:

netcoreapp3.1 → net5.0, net6.0, net7.0, net8.0
net6.0 → net7.0, net8.0
net7.0 → net8.0

Compatibility Check

For each newer framework, the extension verifies that all packages are compatible.

Recommendation

If 80%+ of packages support a newer framework, you’ll see a suggestion:

💡 MyProject.csproj: Consider upgrading from netcoreapp3.1 to net8.0.
   All packages support net8.0

Learn More

Click “Learn More” to open Microsoft’s migration documentation.

Applying Framework Upgrades

To upgrade your target framework:

Review Suggestion

Read the framework upgrade suggestion carefully and consider:

Whether your application is ready for the upgrade
Breaking changes in the new framework
Team and deployment readiness

Update Project File

Edit your .csproj file:

<PropertyGroup>
  <!-- Before -->
  <TargetFramework>netcoreapp3.1</TargetFramework>
  
  <!-- After -->
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

Test Your Application

After upgrading:

Build your project: dotnet build
Run tests: dotnet test
Test application functionality
Review any new warnings or errors

Update Packages (Optional)

Consider updating package versions to take advantage of new framework features:

dotnet list package --outdated
dotnet add package <PackageName>

Always test thoroughly after framework upgrades. Breaking changes may require code modifications.

Transitive Dependency Checking

The extension checks not only direct dependencies but also their dependencies (transitive dependencies).

What Are Transitive Dependencies?

Your Project
├── PackageA (direct dependency)
│   ├── PackageB (transitive dependency)
│   └── PackageC (transitive dependency)
│       └── PackageD (transitive dependency)

How It Helps

Transitive dependency checking warns you when:

A direct dependency relies on incompatible packages
Indirect dependencies have compatibility issues
Version conflicts exist in the dependency tree

Example

<PackageReference Include="LibraryX" Version="2.0.0" />

Tooltip shows:

⚠️ LibraryX: Compatible with net8.0

⚠️ Transitive dependency issues:
  • LibraryY 1.0.0: Not compatible with net8.0
  • LibraryZ: Version mismatch

Transitive dependency checking requires nugetApiEnabled to be true (default) as it queries NuGet.org for package metadata.

Configuration

Enable/Disable Compatibility Checking

settings.json

{
  // Master switch for all NuGet compatibility features
  "dotnetBuildBuddy.nugetCheckEnabled": true,
  
  // Enable real-time NuGet.org API lookups
  "dotnetBuildBuddy.nugetApiEnabled": true
}

Both Enabled (Default)
nugetApiEnabled: false
nugetCheckEnabled: false

Full compatibility checking
API lookups for package metadata
Most accurate results
Requires internet connection

Caching

Reduce API calls and improve performance with caching:

settings.json

{
  // Enable caching of compatibility check results
  "dotnetBuildBuddy.nugetCacheEnabled": true,
  
  // Cache expiry time in seconds (default: 3600 = 1 hour)
  "dotnetBuildBuddy.nugetCacheExpiry": 3600
}

Cache Behavior:

Results are cached per package, version, and target framework
Cache expires after nugetCacheExpiry seconds
Cache is cleared when VS Code restarts
Disable cache to always get fresh results (slower)

API Timeout

Control how long to wait for NuGet API responses:

settings.json

{
  // Timeout in milliseconds (default: 5000 = 5 seconds)
  "dotnetBuildBuddy.nugetApiTimeout": 5000
}

Increase timeout if you have a slow internet connection. Decrease for faster failure on network issues.

Ignoring Packages

Exclude specific packages from compatibility checks:

settings.json

{
  "dotnetBuildBuddy.nugetIgnoredPackages": [
    "MyCustomPackage",          // Exact match
    "Internal.*",               // Wildcard pattern
    "Company.*.Beta"            // Multiple wildcards
  ]
}

Use Cases:

Internal packages not on NuGet.org
Custom package sources
Packages with incorrect metadata
False positives you want to suppress

Known Compatibility Rules

The extension includes built-in rules for popular packages:

ASP.NET Core

Microsoft.AspNetCore.App: Requires netcoreapp2.1 or higher
Microsoft.AspNetCore.Mvc: Framework-version alignment required
Microsoft.AspNetCore.***: Modern .NET only

Entity Framework

Microsoft.EntityFrameworkCore: Requires netstandard2.0 or higher
EntityFramework: .NET Framework only (max net48)

Extensions

Microsoft.Extensions.Hosting: Requires netcoreapp2.1 or higher
Microsoft.Extensions.DependencyInjection: Requires netstandard1.0 or higher
Microsoft.Extensions.Logging: Requires netstandard1.1 or higher

Blazor

Microsoft.AspNetCore.Components.Web: Requires netcoreapp3.1 or higher
Microsoft.AspNetCore.Components.WebAssembly: Requires netstandard2.1 or higher

Testing

xunit: Requires netstandard1.1 or higher
NUnit: Requires netstandard1.6 or higher
Moq: Requires netstandard2.0 or higher

These rules are maintained in the extension source code at src/nugetCompatibilityChecker.ts:561.

Troubleshooting

No Diagnostics Appearing

Check Settings

Verify compatibility checking is enabled:

{
  "dotnetBuildBuddy.nugetCheckEnabled": true
}

Open Project File

Diagnostics only appear when the project file is open in the editor. Open your .csproj file.

Check Problems Panel

Open Problems panel (Ctrl+Shift+M) and look for issues under “DotNET Build Buddy”.

Reload Window

Sometimes diagnostics need a refresh. Reload VS Code (Ctrl+R).

False Positives

If a package is marked incompatible but works fine:

Verify Actual Compatibility

Test build and runtime behavior:

dotnet build
dotnet run

Check NuGet.org

Visit the package page on NuGet.org to verify supported frameworks.

Add to Ignore List

If it’s a false positive:

{
  "dotnetBuildBuddy.nugetIgnoredPackages": [
    "ProblematicPackage"
  ]
}

Report Issue

If you believe the rule is incorrect, report an issue with details.

API Timeouts

If you see timeout errors in the Output panel:

settings.json

{
  // Increase timeout
  "dotnetBuildBuddy.nugetApiTimeout": 10000,
  
  // Or disable API and use local rules only
  "dotnetBuildBuddy.nugetApiEnabled": false
}

Best Practices

Review Suggestions

Don’t blindly apply all suggestions. Review alternatives and consider your application’s specific needs.

Test After Changes

Always test your application after changing packages or frameworks. Compatibility checking can’t catch all issues.

Keep Cache Enabled

Leave caching enabled unless you’re troubleshooting. It significantly improves performance.

Monitor Output Panel

Watch the Output panel for detailed compatibility reports and API errors.

Next Steps

Configuration Reference

Explore all NuGet-related configuration options.

Troubleshooting

Find solutions to common NuGet compatibility issues.

Get Started

Core Features

Configuration

Guides

​Overview

​Features

Real-time Compatibility Checks

Inline Diagnostics

Smart Version Suggestions

Alternative Packages

Transitive Dependencies

Framework Upgrades

​How It Works

​Compatibility Checking Process

​Inline Diagnostics

​Visual Indicators

​Tooltip Information

​Problems Panel

​Package Suggestions

​Version Suggestions

​Alternative Packages

​Framework Upgrade Suggestions

​How It Works

​Applying Framework Upgrades

​Transitive Dependency Checking

​What Are Transitive Dependencies?

​How It Helps

​Example

​Configuration

​Enable/Disable Compatibility Checking

​Caching

​API Timeout

​Ignoring Packages

​Known Compatibility Rules

​Troubleshooting

​No Diagnostics Appearing

​False Positives

​API Timeouts

​Best Practices

Review Suggestions

Test After Changes

Keep Cache Enabled

Monitor Output Panel

​Next Steps

Configuration Reference

Troubleshooting

Build docs developers (and LLMs) love

Overview

Features

How It Works

Compatibility Checking Process

Inline Diagnostics

Visual Indicators

Tooltip Information

Problems Panel

Package Suggestions

Version Suggestions

Alternative Packages

Framework Upgrade Suggestions

How It Works

Applying Framework Upgrades

Transitive Dependency Checking

What Are Transitive Dependencies?

How It Helps

Example

Configuration

Enable/Disable Compatibility Checking

Caching

API Timeout

Ignoring Packages

Known Compatibility Rules

Troubleshooting

No Diagnostics Appearing

False Positives

API Timeouts

Best Practices

Next Steps