@isopodlabs/msbuild

A TypeScript library for parsing and manipulating MSBuild project files and Visual Studio solutions.

☕ Support My Work

If you use this package, consider buying me a cup of tea to support future updates!

Installation

npm install @isopodlabs/msbuild

Features

Solution Management

• Parse Visual Studio solution files (.sln)
• Project discovery - automatically detect and load referenced projects
• Configuration management - handle Debug/Release, platform configurations
• Project dependencies - track and manage inter-project references
• Solution folders - organize projects in virtual folders

Project Support

• MSBuild projects - C#, VB.NET, F#, C++ projects
• Modern SDK-style projects - .NET Core/5+ projects
• Legacy projects - Framework 4.x and earlier
• Specialized projects - Android, web, deployment projects
• Project filters - Visual Studio filter files (.vcxproj.filters)

Property System

• Property evaluation - MSBuild property expansion and substitution
• Conditional properties - condition-based property evaluation
• Import resolution - handle .props and .targets imports
• Environment integration - access environment variables and registry

Usage

Loading Solutions

import { Solution } from '@isopodlabs/msbuild';

// Load a Visual Studio solution
const solution = await Solution.load('path/to/solution.sln');

if (solution) {
    console.log(`Loaded ${Object.keys(solution.projects).length} projects`);
    
    // Access projects
    const project = solution.projectByName('MyProject');
    
    // Get active configuration
    const config = solution.activeConfiguration;
    console.log(`Active: ${config.Configuration}|${config.Platform}`);
}

Working with Projects

// Get project configurations
const configs = project.configurationList();  // ['Debug', 'Release']
const platforms = project.platformList();     // ['x86', 'x64', 'Any CPU']

// Evaluate project properties
const [props, origins] = await project.evaluateProps({
    Configuration: 'Debug',
    Platform: 'x64'
});

console.log('Output path:', props.properties.OutputPath);

API Reference

Core Classes

• Solution - Visual Studio solution parser and manager
• Project - Base project class with common functionality
• MsBuildProject - MSBuild-based projects (.csproj, .vbproj, etc.)
• PropertyContext - MSBuild property evaluation engine
• Items - Project item collections (files, references, etc.)

Supported Project Types

The library recognizes and handles these Visual Studio project types:

• C# Projects - .csproj files (Framework and SDK-style)
• VB.NET Projects - .vbproj files
• F# Projects - .fsproj files
• C++ Projects - .vcxproj files with filter support
• Web Projects - ASP.NET, MVC, Web API projects
• Mobile Projects - Xamarin Android/iOS projects
• Deployment Projects - Setup and deployment projects

Advanced Features

Expression Evaluation

Built-in support for MSBuild expressions and functions:

• Property substitution: $(PropertyName)
• Registry access: $(registry:HKEY_LOCAL_MACHINE\SOFTWARE\...)
• Static function calls: $([System.Environment]::GetFolderPath(...))
• Metadata access: %(MetadataName)
• List expressions: @(Items) and @(Items->%(field))

License

This project is licensed under the MIT License.