Working with Projects - DotNET Build Buddy

Understanding Project Management

DotNET Build Buddy automatically manages your .NET project files and solution structures. This guide explains how the extension organizes projects and how to work effectively with them.

Project File Generation

How Projects Are Created

The extension automatically generates project files based on your source file structure:

MyWorkspace/
├── Program.cs              → Creates MyWorkspace.csproj
├── Utils.cs
├── Services/
│   ├── UserService.cs     → Creates Services.csproj
│   └── DataService.cs
└── Models/
    ├── User.fs            → Creates Models.fsproj
    └── Product.fs

Each directory with source files gets its own project file, named after the directory. Files in the root get a project named after the workspace folder.

Supported Project Types

The extension supports three .NET project types:

C# Projects

File Extension: .csprojSource Files: *.csSDK: Microsoft.NET.SdkDefault Framework: net8.0

F# Projects

File Extension: .fsprojSource Files: *.fsSDK: Microsoft.NET.SdkDefault Framework: net8.0

VB.NET Projects

File Extension: .vbprojSource Files: *.vbSDK: Microsoft.NET.SdkDefault Framework: net8.0

Project File Structure

Generated C# project files follow the modern SDK-style format:

MyProject.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  
  <!-- Compile items added if subdirectories exist -->
  <ItemGroup>
    <Compile Include="Program.cs" />
    <Compile Include="Utils/Helper.cs" />
  </ItemGroup>
  
  <!-- PackageReferences preserved from existing file -->
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

Updating Project Files

Automatic Updates

By default, project files are automatically updated when you:

Add New Files

Create a new .cs, .fs, or .vb file in your workspace. The extension detects the change, waits 1 second (debounce), and updates the appropriate project file.

# Extension automatically adds Program.cs to MyProject.csproj
touch Program.cs

Delete Files

Delete a source file, and it’s automatically removed from the project file.

# Extension automatically removes OldFile.cs from MyProject.csproj
rm OldFile.cs

Move Files

Move files between directories, and the extension updates project memberships accordingly.

Moving a file to a different directory may change which project it belongs to, based on directory-based grouping.

Manual Updates

You can manually trigger updates using these commands:

Update Project Files
Generate Solution File
Refresh All Files

Command: DotNET Build Buddy: Update Project FilesKeyboard: Ctrl+Shift+P → Type “Update Project Files”What it does:

Scans workspace for source files
Groups files by directory and type
Updates all project files
Preserves existing configurations
Checks NuGet compatibility

Use when:

Auto-update is disabled
You want to force an immediate update
Files weren’t detected automatically

Command: DotNET Build Buddy: Generate Solution FileKeyboard: Ctrl+Shift+P → Type “Generate Solution”What it does:

Finds all project files in workspace
Creates/updates Solution.sln
Includes all projects with proper GUIDs
Sets up Debug/Release configurations

Use when:

Solution file is missing
You added new projects manually
You want to refresh solution structure

Command: DotNET Build Buddy: Refresh All .NET FilesKeyboard: Ctrl+Shift+P → Type “Refresh All”What it does:

Updates all project files
Regenerates solution file
Complete refresh of .NET structure

Use when:

You want a full rebuild of all files
After major workspace reorganization
As a troubleshooting step

Configuration Preservation

The extension intelligently preserves your existing project configurations.

What Gets Preserved

Target Framework

<PropertyGroup>
  <TargetFramework>net6.0</TargetFramework>
  <!-- Preserved when updating project -->
</PropertyGroup>

The extension reads existing target framework and maintains it. If no existing project exists, it detects the framework from other projects in the workspace or defaults to net8.0.

Project Properties

<PropertyGroup>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <UserSecretsId>12345</UserSecretsId>
  <RootNamespace>MyApp.Core</RootNamespace>
  <!-- All custom properties preserved -->
</PropertyGroup>

Custom properties like Nullable, ImplicitUsings, UserSecretsId, and any other custom settings are preserved when updating.

NuGet Packages

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  <PackageReference Include="Serilog" Version="3.1.1" />
  <!-- All package references preserved -->
</ItemGroup>

All PackageReference entries are preserved with their versions. The extension also checks compatibility and provides warnings if needed.

SDK Type

<Project Sdk="Microsoft.NET.Sdk.Web">
  <!-- SDK type preserved -->
</Project>

If you’re using a specific SDK (like Microsoft.NET.Sdk.Web for web projects), it’s preserved. Default is Microsoft.NET.Sdk.

What Gets Updated

Source File Compilation Items

The <Compile Include="..." /> entries are updated to match current source files.

Manual <Compile> entries will be replaced with auto-detected files. Use .csproj file globbing patterns if you need custom inclusion logic.

File Organization

Files are reorganized based on current directory structure. The extension adds explicit <Compile> entries when files are in subdirectories.

Solution File Management

Solution Structure

The extension generates Visual Studio-compatible solution files:

Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17
VisualStudioVersion = 17.0.31903.59
MinimumVisualStudioVersion = 10.0.40219.1

Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MyProject", "MyProject/MyProject.csproj", "{GUID}"
EndProject

Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharpLib", "FSharpLib/FSharpLib.fsproj", "{GUID}"
EndProject

Global
  GlobalSection(SolutionConfigurationPlatforms) = preSolution
    Debug|Any CPU = Debug|Any CPU
    Release|Any CPU = Release|Any CPU
  EndGlobalSection
  ...
EndGlobal

Project Type GUIDs

The extension uses correct Visual Studio project type GUIDs:

Language	GUID
C#	`9A19103F-16F7-4668-BE54-9A1E7A4F7556`
F#	`6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705`
VB.NET	`F184B08F-C81C-45F6-A57F-5ABD9991F28F`

Solution Location

Solution files are always created at the workspace root with the name Solution.sln.

MyWorkspace/
├── Solution.sln           ← Always at root
├── ProjectA/
│   └── ProjectA.csproj
└── ProjectB/
    └── ProjectB.csproj

Multi-Project Workspaces

Organizing Multiple Projects

Best practice for multi-project solutions:

Create Project Directories

Create separate directories for each logical project:

MySolution/
├── MyApp.Core/           ← Core business logic
├── MyApp.Web/            ← Web application
├── MyApp.Tests/          ← Unit tests
└── MyApp.Shared/         ← Shared utilities

Add Source Files

Add source files to each project directory:

MySolution/
├── MyApp.Core/
│   ├── Services/
│   │   └── UserService.cs
│   └── Models/
│       └── User.cs
├── MyApp.Web/
│   ├── Program.cs
│   └── Controllers/
│       └── UserController.cs

Extension Generates Projects

The extension creates one project per directory:

MySolution/
├── Solution.sln                ← Generated
├── MyApp.Core/
│   ├── MyApp.Core.csproj      ← Generated
│   └── ...
├── MyApp.Web/
│   ├── MyApp.Web.csproj       ← Generated
│   └── ...

Add Project References Manually

The extension does NOT automatically create project references between projects. You must add these manually.

Edit project files to add references:

MyApp.Web.csproj

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <!-- Add manually -->
  <ItemGroup>
    <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />
  </ItemGroup>
</Project>

Project references are preserved once added. The extension won’t remove them.

Mixed Language Projects

You can have different languages in the same solution:

MySolution/
├── Solution.sln
├── CSharpApp/
│   ├── CSharpApp.csproj      ← C# project
│   └── Program.cs
├── FSharpLib/
│   ├── FSharpLib.fsproj      ← F# project
│   └── Library.fs
└── VBNetTools/
    ├── VBNetTools.vbproj     ← VB.NET project
    └── Utilities.vb

Target Framework Management

Framework Detection

The extension determines target framework in this order:

Existing project file: Uses <TargetFramework> from existing .csproj/.fsproj/.vbproj
Other projects: Looks at other projects in workspace for consistency
Default: Falls back to net8.0

Changing Target Framework

To change your target framework:

Edit Project File

Open your .csproj file and change the <TargetFramework>:

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <!-- Change to desired framework -->
</PropertyGroup>

Save File

Save the project file. The extension preserves your change on future updates.

Check Compatibility

The extension automatically checks NuGet package compatibility with the new framework and shows warnings if issues are found.

You may see suggestions to upgrade packages or use alternatives that support your new framework.

Multi-Targeting

For multi-targeting, manually edit the project file:

<PropertyGroup>
  <!-- Replace TargetFramework with TargetFrameworks -->
  <TargetFrameworks>net6.0;net7.0;net8.0</TargetFrameworks>
</PropertyGroup>

The extension preserves TargetFrameworks (plural) and doesn’t overwrite it with TargetFramework (singular).

Watch Patterns and Exclusions

Default Watch Patterns

By default, the extension monitors:

{
  "dotnetBuildBuddy.watchPatterns": [
    "**/*.cs",
    "**/*.fs",
    "**/*.vb"
  ]
}

Default Exclusions

These directories are excluded:

{
  "dotnetBuildBuddy.excludePatterns": [
    "**/bin/**",      // Build output
    "**/obj/**",      // Intermediate files
    "**/node_modules/**"  // Node.js dependencies
  ]
}

Custom Patterns

Customize watch and exclude patterns in your settings:

settings.json

{
  "dotnetBuildBuddy.watchPatterns": [
    "**/*.cs",
    "**/*.fs",
    "**/*.vb",
    "src/**/*.cs"  // Additional pattern
  ],
  "dotnetBuildBuddy.excludePatterns": [
    "**/bin/**",
    "**/obj/**",
    "**/node_modules/**",
    "**/temp/**",      // Custom exclusion
    "**/backup/**"     // Custom exclusion
  ]
}

Disabling Auto-Updates

If you prefer manual control:

settings.json

{
  "dotnetBuildBuddy.autoUpdate": false
}

With auto-update disabled, you must manually trigger updates using the Command Palette commands.

Best Practices

Use Version Control

Always commit project files to Git before letting the extension modify them. Review changes with git diff to ensure they’re correct.

One Project Per Directory

Organize source files into directories by project. The extension creates one project per directory for clean separation.

Preserve Custom Settings

The extension preserves most settings, but review generated files if you have complex custom configurations.

Monitor Output Panel

Watch the Output panel (Ctrl+Shift+U → “DotNET Build Buddy”) to understand what the extension is doing.

Next Steps

NuGet Management

Learn how to leverage NuGet compatibility checking and smart package suggestions.

Configuration Reference

Explore all available configuration options for fine-tuning the extension.

Get Started

Core Features

Configuration

Guides

​Understanding Project Management

​Project File Generation

​How Projects Are Created

​Supported Project Types

C# Projects

F# Projects

VB.NET Projects

​Project File Structure

​Updating Project Files

​Automatic Updates

​Manual Updates

​Configuration Preservation

​What Gets Preserved

​What Gets Updated

​Solution File Management

​Solution Structure

​Project Type GUIDs

​Solution Location

​Multi-Project Workspaces

​Organizing Multiple Projects

​Mixed Language Projects

​Target Framework Management

​Framework Detection

​Changing Target Framework

​Multi-Targeting

​Watch Patterns and Exclusions

​Default Watch Patterns

​Default Exclusions

​Custom Patterns

​Disabling Auto-Updates

​Best Practices

Use Version Control

One Project Per Directory

Preserve Custom Settings

Monitor Output Panel

​Next Steps

NuGet Management

Configuration Reference

Build docs developers (and LLMs) love

Understanding Project Management

Project File Generation

How Projects Are Created

Supported Project Types

Project File Structure

Updating Project Files

Automatic Updates

Manual Updates

Configuration Preservation

What Gets Preserved

What Gets Updated

Solution File Management

Solution Structure

Project Type GUIDs

Solution Location

Multi-Project Workspaces

Organizing Multiple Projects

Mixed Language Projects

Target Framework Management

Framework Detection

Changing Target Framework

Multi-Targeting

Watch Patterns and Exclusions

Default Watch Patterns

Default Exclusions

Custom Patterns

Disabling Auto-Updates

Best Practices

Next Steps