Skip to main content
The NuGetCompatibilityChecker class provides comprehensive NuGet package compatibility validation, including local rule-based checking and real-time API lookups.

​
Class Overview

Location: /workspace/source/src/nugetCompatibilityChecker.ts:87 
export class NuGetCompatibilityChecker {
    private compatibilityRules: PackageCompatibilityRule[];
    private cache: Map<string, CacheEntry>;
    private config: vscode.WorkspaceConfiguration;

    constructor();
}

​
Constructor

​
new NuGetCompatibilityChecker()

Creates a new instance of the compatibility checker. 
constructor()
Initialization:
  • Loads built-in compatibility rules for popular packages
  • Initializes result cache for performance
  • Loads workspace configuration settings
Example: 
import { NuGetCompatibilityChecker } from './nugetCompatibilityChecker';

const checker = new NuGetCompatibilityChecker();

​
Public Methods

​
checkCompatibility

Checks if a specific package is compatible with a target framework. 
public async checkCompatibility(
    packageName: string,
    packageVersion: string | undefined,
    targetFramework: string
): Promise<CompatibilityIssue | null>
​
packageName
string
required
The NuGet package name (e.g., "Newtonsoft.Json")
​
packageVersion
string | undefined
The package version, or undefined for latest
​
targetFramework
string
required
Target framework (e.g., "net8.0", "netstandard2.0")
​
return
CompatibilityIssue | null
Returns a CompatibilityIssue if incompatible, or null if compatible
interface CompatibilityIssue {
    packageName: string;
    packageVersion?: string;
    targetFramework: string;
    issueType: 'incompatible' | 'version_mismatch' | 'deprecated';
    message: string;
    recommendation?: string;
}
Example Usage: 
const checker = new NuGetCompatibilityChecker();

const issue = await checker.checkCompatibility(
    'System.Web.Mvc',
    '5.2.7',
    'net8.0'
);

if (issue) {
    console.log(`Issue: ${issue.message}`);
    console.log(`Type: ${issue.issueType}`);
    console.log(`Recommendation: ${issue.recommendation}`);
}
Configuration Settings:
  • dotnetBuildBuddy.nugetCheckEnabled - Enable/disable checks
  • dotnetBuildBuddy.nugetApiEnabled - Use real-time API lookups
  • dotnetBuildBuddy.nugetCacheEnabled - Cache results
  • dotnetBuildBuddy.nugetIgnoredPackages - Packages to skip

​
checkProjectCompatibility

Checks compatibility for all package references in a project. 
public async checkProjectCompatibility(
    packageReferences: Array<{ Include: string; Version?: string }>,
    targetFramework: string
): Promise<CompatibilityIssue[]>
​
packageReferences
Array<{Include: string; Version?: string}>
required
Array of package references from the project file
​
targetFramework
string
required
Target framework for the project
​
return
CompatibilityIssue[]
Array of compatibility issues found (empty if all compatible)
Example Usage: 
const packageRefs = [
    { Include: 'Newtonsoft.Json', Version: '13.0.3' },
    { Include: 'Microsoft.AspNetCore.Mvc', Version: '2.2.0' }
];

const issues = await checker.checkProjectCompatibility(
    packageRefs,
    'net8.0'
);

console.log(`Found ${issues.length} compatibility issues`);

​
checkProjectCompatibilityEnhanced

Performs enhanced compatibility checking with suggestions and transitive dependency analysis. 
public async checkProjectCompatibilityEnhanced(
    packageReferences: Array<{ Include: string; Version?: string }>,
    targetFramework: string
): Promise<EnhancedCompatibilityIssue[]>
​
packageReferences
Array<{Include: string; Version?: string}>
required
Array of package references from the project file
​
targetFramework
string
required
Target framework for the project
​
return
EnhancedCompatibilityIssue[]
interface EnhancedCompatibilityIssue extends CompatibilityIssue {
    suggestedVersion?: string;
    alternativePackage?: {
        name: string;
        version?: string;
        reason?: string;
    };
    transitiveIssues?: Array<{
        packageName: string;
        version?: string;
        message: string;
    }>;
}
Enhanced Features:
  • Suggests compatible package versions
  • Recommends alternative packages (e.g., Entity Framework Core instead of Entity Framework)
  • Checks transitive dependencies for compatibility
  • Provides actionable recommendations
Example Usage: 
const enhancedIssues = await checker.checkProjectCompatibilityEnhanced(
    packageRefs,
    'net8.0'
);

for (const issue of enhancedIssues) {
    console.log(`Package: ${issue.packageName}`);
    console.log(`Issue: ${issue.message}`);
    
    if (issue.suggestedVersion) {
        console.log(`Suggested version: ${issue.suggestedVersion}`);
    }
    
    if (issue.alternativePackage) {
        console.log(`Alternative: ${issue.alternativePackage.name}`);
        console.log(`Reason: ${issue.alternativePackage.reason}`);
    }
    
    if (issue.transitiveIssues) {
        console.log('Transitive issues:', issue.transitiveIssues);
    }
}

​
reportCompatibilityIssues

Reports compatibility issues to the user via VS Code notifications. 
public async reportCompatibilityIssues(
    issues: CompatibilityIssue[] | EnhancedCompatibilityIssue[]
): Promise<void>
​
issues
CompatibilityIssue[] | EnhancedCompatibilityIssue[]
required
Array of compatibility issues to report
Display Behavior:
  • Shows error notifications for incompatible issues
  • Shows warning notifications for version_mismatch and deprecated issues
  • Includes suggestions and recommendations in messages
  • Logs all issues to console for debugging
Example Usage: 
const issues = await checker.checkProjectCompatibility(packageRefs, 'net8.0');
await checker.reportCompatibilityIssues(issues);

​
suggestFrameworkUpgrade

Analyzes packages and suggests a framework upgrade if beneficial. 
public async suggestFrameworkUpgrade(
    targetFramework: string,
    packageReferences: Array<{ Include: string; Version?: string }>
): Promise<{
    suggestedFramework: string;
    reason: string;
    packagesSupporting: string[];
} | null>
​
targetFramework
string
required
Current target framework
​
packageReferences
Array<{Include: string; Version?: string}>
required
Package references to analyze
​
return
object | null
Upgrade suggestion object or null if no upgrade recommended
{
    suggestedFramework: string;    // e.g., "net8.0"
    reason: string;                // Explanation
    packagesSupporting: string[];  // Packages that support the upgrade
}
Upgrade Paths Supported:
  • netcoreapp2.0 → netcoreapp2.1 → netcoreapp3.1 → net5.0 → … → net8.0
  • netstandard2.0 → netstandard2.1 → netcoreapp3.1 → … → net8.0
Example Usage: 
const upgrade = await checker.suggestFrameworkUpgrade(
    'netcoreapp3.1',
    packageRefs
);

if (upgrade) {
    console.log(`Suggested upgrade to: ${upgrade.suggestedFramework}`);
    console.log(`Reason: ${upgrade.reason}`);
    console.log(`Supporting packages: ${upgrade.packagesSupporting.join(', ')}`);
}
Threshold: Only suggests upgrades if 80% or more of packages support the new framework.

​
clearCache

Clears the compatibility check result cache. 
public clearCache(): void
Example Usage: 
checker.clearCache();
Clear the cache after changing configuration settings or when you want fresh API results.

​
Configuration Settings

The checker respects the following VS Code settings:
​
dotnetBuildBuddy.nugetCheckEnabled
boolean
default:"true"
Enable NuGet package compatibility checking
​
dotnetBuildBuddy.nugetApiEnabled
boolean
default:"true"
Enable real-time NuGet API lookups for package information
​
dotnetBuildBuddy.nugetCacheEnabled
boolean
default:"true"
Enable caching of compatibility check results
​
dotnetBuildBuddy.nugetCacheExpiry
number
default:"3600"
Cache expiry time in seconds (default: 1 hour)
​
dotnetBuildBuddy.nugetIgnoredPackages
string[]
default:"[]"
List of package names or patterns to ignore during checks
​
dotnetBuildBuddy.nugetApiTimeout
number
default:"5000"
NuGet API request timeout in milliseconds

​
Built-in Compatibility Rules

The checker includes comprehensive built-in rules for popular packages:

​
ASP.NET Core

  • Microsoft.AspNetCore.App
  • Microsoft.AspNetCore.Mvc
  • Microsoft.AspNetCore.* (pattern)

​
Entity Framework

  • Microsoft.EntityFrameworkCore
  • Microsoft.EntityFrameworkCore.* (pattern)
  • EntityFramework (legacy)

​
Modern .NET Extensions

  • Microsoft.Extensions.Hosting
  • Microsoft.Extensions.DependencyInjection
  • Microsoft.Extensions.Logging
  • Microsoft.Extensions.Configuration
  • Microsoft.Extensions.* (pattern)

​
Testing Frameworks

  • xunit
  • NUnit
  • Moq
  • Newtonsoft.Json
  • System.Text.Json
  • AutoMapper
  • Serilog
  • FluentValidation
  • MediatR

​
Web Technologies

  • Microsoft.AspNetCore.Components.* (Blazor)
  • Microsoft.AspNetCore.SignalR
  • Grpc.* (gRPC)
Rules are defined in /workspace/source/src/nugetCompatibilityChecker.ts:561 and cover framework requirements, version constraints, and deprecation warnings.

​
API Integration

When nugetApiEnabled is true, the checker uses the NuGet API: Endpoints Used:
  • Package index: https://api.nuget.org/v3-flatcontainer/{package}/index.json
  • Package spec: https://api.nuget.org/v3-flatcontainer/{package}/{version}/{package}.nuspec
Fallback Behavior:
  • If API call fails, falls back to local rules
  • Respects timeout configuration
  • Caches successful API responses

​
Usage Example

import { NuGetCompatibilityChecker } from './nugetCompatibilityChecker';
import * as vscode from 'vscode';

async function validateProjectPackages() {
    const checker = new NuGetCompatibilityChecker();
    
    const packageRefs = [
        { Include: 'Microsoft.EntityFrameworkCore', Version: '8.0.0' },
        { Include: 'Newtonsoft.Json', Version: '13.0.3' }
    ];
    
    // Enhanced checking with suggestions
    const issues = await checker.checkProjectCompatibilityEnhanced(
        packageRefs,
        'net8.0'
    );
    
    // Report issues to user
    await checker.reportCompatibilityIssues(issues);
    
    // Check for upgrade opportunities
    const upgrade = await checker.suggestFrameworkUpgrade(
        'net6.0',
        packageRefs
    );
    
    if (upgrade) {
        vscode.window.showInformationMessage(
            `Consider upgrading to ${upgrade.suggestedFramework}. ${upgrade.reason}`
        );
    }
}
The compatibility checker requires an active internet connection for API-based checks. Ensure your firewall allows access to api.nuget.org.

Build docs developers (and LLMs) love

Get started for freeTalk to us