NuGet Compatibility Settings - DotNET Build Buddy

DotNET Build Buddy includes intelligent NuGet package compatibility checking that verifies packages against your target framework and provides smart suggestions. This page explains how to configure and use this feature effectively.

Overview

The NuGet compatibility checker:

Verifies package compatibility with target frameworks
Fetches real-time data from NuGet.org API
Provides version suggestions and alternatives
Checks transitive dependencies
Suggests framework upgrades when beneficial
Uses intelligent caching for performance

Core Configuration

Enable Compatibility Checking

dotnetBuildBuddy.nugetCheckEnabled

boolean

default:true

Master switch for NuGet package compatibility checking.When disabled, no compatibility checks are performed. All other NuGet-related settings are ignored.

{
  "dotnetBuildBuddy.nugetCheckEnabled": true
}

Disabling this setting turns off all NuGet compatibility features, including inline diagnostics and suggestions.

Enable API Lookups

dotnetBuildBuddy.nugetApiEnabled

boolean

default:true

Enable real-time package information from NuGet.org API.When enabled, the extension queries the NuGet API for accurate package metadata. When disabled, only built-in compatibility rules are used.

{
  "dotnetBuildBuddy.nugetApiEnabled": true
}

API vs Local Rules

Feature	API Enabled	API Disabled
Package version info	Real-time from NuGet.org	Not available
Framework compatibility	Accurate, up-to-date	Built-in rules only
New packages	Full support	Limited support
Network required	Yes	No
Performance	Slower (cached)	Faster

See nugetCompatibilityChecker.ts:124-138 for the fallback logic.

Caching Configuration

Enable Caching

dotnetBuildBuddy.nugetCacheEnabled

boolean

default:true

Cache compatibility check results to improve performance.When enabled, results are stored in memory and reused until they expire.

{
  "dotnetBuildBuddy.nugetCacheEnabled": true
}

Cache Expiry

dotnetBuildBuddy.nugetCacheExpiry

number

default:3600

How long (in seconds) cached results remain valid.Default is 3600 seconds (1 hour). Increase for stable projects, decrease for active development.

{
  "dotnetBuildBuddy.nugetCacheExpiry": 3600
}

Cache Management

The cache:

Stores results in memory (not persisted)
Keys by package name, version, and target framework
Automatically expires based on nugetCacheExpiry
Clears when VS Code restarts

See nugetCompatibilityChecker.ts:338-361 for cache implementation.

Ignored Packages

Configuration

dotnetBuildBuddy.nugetIgnoredPackages

array

default:[]

List of package names or patterns to exclude from compatibility checks.Supports exact names and wildcard patterns using *.

{
  "dotnetBuildBuddy.nugetIgnoredPackages": [
    "MyInternalPackage",
    "Company.Internal.*",
    "Legacy.*"
  ]
}

Pattern Matching

Pattern matching rules:

Exact match: "MyPackage" matches only MyPackage
Wildcard: "Company.*" matches Company.Core, Company.Data, etc.
Case insensitive: "mypackage" matches MyPackage

See nugetCompatibilityChecker.ts:315-336 for pattern matching logic.

Common Use Cases

Internal/Private Packages

{
  "dotnetBuildBuddy.nugetIgnoredPackages": [
    "MyCompany.Internal.*",
    "PrivatePackage"
  ]
}

Legacy Packages

{
  "dotnetBuildBuddy.nugetIgnoredPackages": [
    "OldFramework.*",
    "DeprecatedLib"
  ]
}

Test Packages

{
  "dotnetBuildBuddy.nugetIgnoredPackages": [
    "TestUtilities.*",
    "MockingFramework"
  ]
}

Use ignored packages sparingly. Ignoring packages means you won’t receive compatibility warnings, which could hide real issues.

Network Configuration

API Timeout

dotnetBuildBuddy.nugetApiTimeout

number

default:5000

Maximum time (in milliseconds) to wait for NuGet API responses.Default is 5000ms (5 seconds). Increase for slow connections, decrease for faster failure detection.

{
  "dotnetBuildBuddy.nugetApiTimeout": 5000
}

Timeout Behavior

When a timeout occurs:

API request is cancelled
Falls back to local compatibility rules
Result is not cached
No error is shown to user

See nugetCompatibilityChecker.ts:308-311 for timeout handling.

Network Recommendations

Connection Speed	Recommended Timeout
Fast (>10 Mbps)	3000ms
Normal	5000ms (default)
Slow (<1 Mbps)	10000ms
Proxy/VPN	15000ms

Compatibility Rules

The extension includes built-in rules for common packages:

Framework Categories

ASP.NET Core: Microsoft.AspNetCore.*
Entity Framework: Microsoft.EntityFrameworkCore.*
Extensions: Microsoft.Extensions.*
Blazor: Microsoft.AspNetCore.Components.*
SignalR: Microsoft.AspNetCore.SignalR.*
gRPC: Grpc.*

Example Rules

// ASP.NET Core MVC
{
  packageName: 'Microsoft.AspNetCore.Mvc',
  supportedFrameworks: [
    'netcoreapp2.0', 'netcoreapp2.1', 'netcoreapp2.2',
    'netcoreapp3.1', 'net5.0', 'net6.0', 'net7.0', 'net8.0'
  ]
}

// Entity Framework Core
{
  packageName: 'Microsoft.EntityFrameworkCore',
  supportedFrameworks: [
    'netstandard2.0', 'netstandard2.1',
    'netcoreapp2.0', 'netcoreapp3.1',
    'net5.0', 'net6.0', 'net7.0', 'net8.0'
  ],
  minFramework: 'netstandard2.0'
}

See nugetCompatibilityChecker.ts:561-783 for complete rule definitions.

Configuration Profiles

Production Environment

Optimized for stability and performance:

{
  "dotnetBuildBuddy.nugetCheckEnabled": true,
  "dotnetBuildBuddy.nugetApiEnabled": true,
  "dotnetBuildBuddy.nugetCacheEnabled": true,
  "dotnetBuildBuddy.nugetCacheExpiry": 7200,
  "dotnetBuildBuddy.nugetApiTimeout": 5000
}

Development Environment

Balanced for accuracy and responsiveness:

{
  "dotnetBuildBuddy.nugetCheckEnabled": true,
  "dotnetBuildBuddy.nugetApiEnabled": true,
  "dotnetBuildBuddy.nugetCacheEnabled": true,
  "dotnetBuildBuddy.nugetCacheExpiry": 3600,
  "dotnetBuildBuddy.nugetApiTimeout": 5000
}

Offline Environment

For environments without internet access:

{
  "dotnetBuildBuddy.nugetCheckEnabled": true,
  "dotnetBuildBuddy.nugetApiEnabled": false,
  "dotnetBuildBuddy.nugetCacheEnabled": false
}

Performance-Focused

Minimize API calls and maximize caching:

{
  "dotnetBuildBuddy.nugetCheckEnabled": true,
  "dotnetBuildBuddy.nugetApiEnabled": true,
  "dotnetBuildBuddy.nugetCacheEnabled": true,
  "dotnetBuildBuddy.nugetCacheExpiry": 86400,
  "dotnetBuildBuddy.nugetApiTimeout": 3000
}

Minimal Checking

Quick checks with local rules only:

{
  "dotnetBuildBuddy.nugetCheckEnabled": true,
  "dotnetBuildBuddy.nugetApiEnabled": false,
  "dotnetBuildBuddy.nugetCacheEnabled": true,
  "dotnetBuildBuddy.nugetCacheExpiry": 3600
}

Understanding Compatibility Issues

Issue Types

The checker reports three types of issues:

1. Incompatible

❌ Package is not compatible with target framework

The package cannot run on your target framework. Typically requires:

Upgrading target framework
Using an alternative package
Finding a compatible version

2. Version Mismatch

⚠️ Package version is incorrect for target framework

The package version doesn’t align with your framework. Solutions:

Update to suggested version
Check version constraints
Review package documentation

3. Deprecated

⚠️ Package or version is deprecated

The package is no longer maintained. Consider:

Migrating to alternative package
Upgrading to newer version
Evaluating project requirements

See nugetCompatibilityChecker.ts:20-27 for issue type definitions.

Enhanced Issue Information

When API is enabled, issues include:

Suggested Version: Recommended compatible version
Alternative Package: Modern replacement packages
Transitive Issues: Problems with dependencies

Example:

❌ EntityFramework: Package is not compatible with net8.0
  🔄 Alternative: Microsoft.EntityFrameworkCore (8.0.0)
  📝 Recommendation: Modern Entity Framework Core for .NET Core/.NET 5+

Advanced Features

Framework Upgrade Suggestions

The extension can suggest framework upgrades when all packages support newer versions:

💡 Consider upgrading from netcoreapp3.1 to net8.0
   All 15 packages support net8.0

This feature:

Analyzes all project packages
Checks compatibility with newer frameworks
Suggests upgrade only when beneficial
Shows which packages support the upgrade

See nugetCompatibilityChecker.ts:1165-1246 for implementation.

Transitive Dependency Checking

When enabled, the checker verifies indirect dependencies:

{
  "dotnetBuildBuddy.nugetApiEnabled": true  // Required for transitive checks
}

Benefits:

Detects hidden compatibility issues
Identifies problematic sub-dependencies
Provides complete compatibility picture

See nugetCompatibilityChecker.ts:966-1009 for transitive checking.

Alternative Package Suggestions

For incompatible packages, the extension suggests modern alternatives:

Old Package	Alternative	Reason
EntityFramework	Microsoft.EntityFrameworkCore	Modern EF for .NET Core/.NET 5+
Microsoft.AspNet.Mvc	Microsoft.AspNetCore.Mvc	Modern ASP.NET Core MVC
Newtonsoft.Json	System.Text.Json	Built-in JSON in .NET Core/.NET 5+

See nugetCompatibilityChecker.ts:907-964 for alternative suggestions.

Troubleshooting

API Requests Timing Out

Check network connection

Verify you can access api.nuget.org from your network.

Increase timeout

{
  "dotnetBuildBuddy.nugetApiTimeout": 10000
}

Use offline mode

{
  "dotnetBuildBuddy.nugetApiEnabled": false
}

Missing Compatibility Warnings

Verify settings are enabled

Check that both nugetCheckEnabled and nugetApiEnabled are true.

Check ignored packages

Ensure the package isn’t in nugetIgnoredPackages.

Clear cache

Restart VS Code to clear the compatibility cache.

Check package rules

Some packages may not have built-in rules and require API lookups.

Performance Issues

High Memory Usage
Slow Checks
Too Many API Calls

Reduce cache expiry:

{
  "dotnetBuildBuddy.nugetCacheExpiry": 1800
}

Increase cache expiry:

{
  "dotnetBuildBuddy.nugetCacheExpiry": 7200
}

Enable aggressive caching:

{
  "dotnetBuildBuddy.nugetCacheEnabled": true,
  "dotnetBuildBuddy.nugetCacheExpiry": 86400
}

Internal Package Warnings

Ignore your internal packages:

{
  "dotnetBuildBuddy.nugetIgnoredPackages": [
    "YourCompany.*",
    "Internal.Package"
  ]
}

Best Practices

Enable API Lookups

Use nugetApiEnabled: true for accurate, up-to-date compatibility information.

Use Caching

Keep nugetCacheEnabled: true to reduce API calls and improve performance.

Configure Timeout

Adjust nugetApiTimeout based on your network speed.

Ignore Internal Packages

Add your company’s packages to nugetIgnoredPackages to reduce noise.

Next Steps

Settings Overview

View all configuration options

Watch Patterns

Configure file monitoring patterns

Get Started

Core Features

Configuration

Guides

​Overview

​Core Configuration

​Enable Compatibility Checking

​Enable API Lookups

​API vs Local Rules

​Caching Configuration

​Enable Caching

​Cache Expiry

​Cache Management

​Ignored Packages

​Configuration

​Pattern Matching

​Common Use Cases

​Internal/Private Packages

​Legacy Packages

​Test Packages

​Network Configuration

​API Timeout

​Timeout Behavior

​Network Recommendations

​Compatibility Rules

​Framework Categories

​Example Rules

​Configuration Profiles

​Production Environment

​Development Environment

​Offline Environment

​Performance-Focused

​Minimal Checking

​Understanding Compatibility Issues

​Issue Types

​1. Incompatible

​2. Version Mismatch

​3. Deprecated

​Enhanced Issue Information

​Advanced Features

​Framework Upgrade Suggestions

​Transitive Dependency Checking

​Alternative Package Suggestions

​Troubleshooting

​API Requests Timing Out

​Missing Compatibility Warnings

​Performance Issues

​Internal Package Warnings

​Best Practices

Enable API Lookups

Use Caching

Configure Timeout

Ignore Internal Packages

​Next Steps

Settings Overview

Watch Patterns

Build docs developers (and LLMs) love

Overview

Core Configuration

Enable Compatibility Checking

Enable API Lookups

API vs Local Rules

Caching Configuration

Enable Caching

Cache Expiry

Cache Management

Ignored Packages

Configuration

Pattern Matching

Common Use Cases

Internal/Private Packages

Legacy Packages

Test Packages

Network Configuration

API Timeout

Timeout Behavior

Network Recommendations

Compatibility Rules

Framework Categories

Example Rules

Configuration Profiles

Production Environment

Development Environment

Offline Environment

Performance-Focused

Minimal Checking

Understanding Compatibility Issues

Issue Types

1. Incompatible

2. Version Mismatch

3. Deprecated

Enhanced Issue Information

Advanced Features

Framework Upgrade Suggestions

Transitive Dependency Checking

Alternative Package Suggestions

Troubleshooting

API Requests Timing Out

Missing Compatibility Warnings

Performance Issues

Internal Package Warnings

Best Practices

Next Steps