MSBuildProjectManager

Manages MSBuild project files (.csproj, Directory.Build.props, etc.) with formatting preservation capabilities.

Definition

Assembly: CloudNimble.EasyAF.MSBuild.dll

Namespace: CloudNimble.EasyAF.MSBuild

Inheritance: System.Object

Syntax

CloudNimble.EasyAF.MSBuild.MSBuildProjectManager

Summary

Manages MSBuild project files (.csproj, Directory.Build.props, etc.) with formatting preservation capabilities.

Remarks

This class provides comprehensive support for loading, validating, and modifying MSBuild project files while preserving the original formatting (indentation, line breaks). It follows the same pattern as DocsJsonManager for consistency.

Constructors

.ctor

Initializes a new instance of the MSBuildProjectManager class.

Syntax

public MSBuildProjectManager()

.ctor

Initializes a new instance of the MSBuildProjectManager class with the specified file path.

Syntax

public MSBuildProjectManager(string filePath)

Parameters

Name	Type	Description
filePath	string	The file path to the MSBuild project file.

Exceptions

Exception	Description
ArgumentException	Thrown when filePath is null or whitespace.

.ctor Inherited

Inherited from object

Syntax

public Object()

Properties

FilePath

Gets the file path of the loaded project.

Syntax

public string FilePath { get; private set; }

Property Value

Type: string The absolute path to the project file that was loaded or will be saved to. Returns null if no file path has been specified.

IsLoaded

Gets a value indicating whether a project is successfully loaded.

Syntax

public bool IsLoaded { get; }

Property Value

Type: bool True if a project is loaded and there are no errors; otherwise, false.

PreserveFormatting

Gets a value indicating whether formatting preservation is enabled.

Syntax

public bool PreserveFormatting { get; private set; }

Property Value

Type: bool True if the project was loaded with formatting preservation; otherwise, false.

Project

Gets the loaded MSBuild project root element.

Syntax

public Microsoft.Build.Construction.ProjectRootElement Project { get; private set; }

Property Value

Type: Microsoft.Build.Construction.ProjectRootElement The ProjectRootElement instance loaded from the file system. Returns null if no project has been loaded or if loading failed.

ProjectErrors

Gets the collection of project loading and processing errors.

Syntax

public System.Collections.Generic.List<System.CodeDom.Compiler.CompilerError> ProjectErrors { get; private set; }

Property Value

Type: System.Collections.Generic.List<System.CodeDom.Compiler.CompilerError> A list of CompilerError instances representing any errors encountered during project loading, validation, or processing operations.

Methods

AddItemGroup

Adds an ItemGroup with the specified condition and configures it using the provided action.

Syntax

public CloudNimble.EasyAF.MSBuild.MSBuildProjectManager AddItemGroup(string condition, System.Action<CloudNimble.EasyAF.MSBuild.ItemGroupBuilder> configure)

Parameters

Name	Type	Description
condition	string	The condition for the ItemGroup.
configure	System.Action<CloudNimble.EasyAF.MSBuild.ItemGroupBuilder>	An action to configure the ItemGroup.

Returns

Type: CloudNimble.EasyAF.MSBuild.MSBuildProjectManager The current instance for method chaining.

Exceptions

Exception	Description
ArgumentNullException	Thrown when configure is null.
InvalidOperationException	Thrown when no project is loaded.

AddPackageReference

Adds a PackageReference to the project.

Syntax

public CloudNimble.EasyAF.MSBuild.MSBuildProjectManager AddPackageReference(string packageId, string version, string condition = null)

Parameters

Name	Type	Description
packageId	string	The package ID.
version	string	The package version.
condition	string	Optional condition for the PackageReference.

Returns

Type: CloudNimble.EasyAF.MSBuild.MSBuildProjectManager The current instance for method chaining.

Exceptions

Exception	Description
ArgumentException	Thrown when packageId or version is null or whitespace.
InvalidOperationException	Thrown when no project is loaded.

CreateNew

Creates a new MSBuild project file with default structure.

Syntax

public void CreateNew(string filePath, string targetFramework = "net8.0")

Parameters

Name	Type	Description
filePath	string	The file path where the new project should be created.
targetFramework	string	The target framework for the project (default: net8.0).

Exceptions

Exception	Description
ArgumentException	Thrown when filePath is null or whitespace.

EnsureMSBuildRegistered

Ensures MSBuild is registered with the latest available version.

Syntax

public static void EnsureMSBuildRegistered()

Remarks

This method should be called before any MSBuild operations to ensure the correct version of MSBuild is loaded. On .NET Core, QueryVisualStudioInstances() returns SDK instances (versions like 8.0.x, 9.0.x, 10.0.x), not Visual Studio instances. We explicitly select and register the latest available instance.

Equals Inherited Virtual

Inherited from object

Syntax

public virtual bool Equals(object obj)

Parameters

Name	Type	Description
obj	object?	-

Returns

Type: bool

Equals Inherited

Inherited from object

Syntax

public static bool Equals(object objA, object objB)

Parameters

Name	Type	Description
objA	object?	-
objB	object?	-

Returns

Type: bool

GetHashCode Inherited Virtual

Inherited from object

Syntax

public virtual int GetHashCode()

Returns

Type: int

GetPropertyValue

Gets the value of a property from the project.

Syntax

public string GetPropertyValue(string name)

Parameters

Name	Type	Description
name	string	The property name.

Returns

Type: string The property value, or null if the property does not exist.

Exceptions

Exception	Description
ArgumentException	Thrown when name is null or whitespace.
InvalidOperationException	Thrown when no project is loaded.

GetType Inherited

Inherited from object

Syntax

public System.Type GetType()

Returns

Type: System.Type

Load

Loads an existing MSBuild project file from the file path specified in the constructor.

Syntax

public CloudNimble.EasyAF.MSBuild.MSBuildProjectManager Load(bool preserveFormatting = true)

Parameters

Name	Type	Description
preserveFormatting	bool	Whether to preserve the original formatting of the project file.

Returns

Type: CloudNimble.EasyAF.MSBuild.MSBuildProjectManager The current instance for method chaining.

Exceptions

Exception	Description
InvalidOperationException	Thrown when no file path has been specified.

Load

Loads an existing MSBuild project file from the specified file path.

Syntax

public CloudNimble.EasyAF.MSBuild.MSBuildProjectManager Load(string filePath, bool preserveFormatting = true)

Parameters

Name	Type	Description
filePath	string	The file path to the MSBuild project file.
preserveFormatting	bool	Whether to preserve the original formatting of the project file.

Returns

Type: CloudNimble.EasyAF.MSBuild.MSBuildProjectManager The current instance for method chaining.

Exceptions

Exception	Description
ArgumentException	Thrown when filePath is null or whitespace.

MemberwiseClone Inherited

Inherited from object

Syntax

protected internal object MemberwiseClone()

Returns

Type: object

ReferenceEquals Inherited

Inherited from object

Syntax

public static bool ReferenceEquals(object objA, object objB)

Parameters

Name	Type	Description
objA	object?	-
objB	object?	-

Returns

Type: bool

RemoveProperty

Removes a property from the project.

Syntax

public CloudNimble.EasyAF.MSBuild.MSBuildProjectManager RemoveProperty(string name)

Parameters

Name	Type	Description
name	string	The property name to remove.

Returns

Type: CloudNimble.EasyAF.MSBuild.MSBuildProjectManager The current instance for method chaining.

Exceptions

Exception	Description
ArgumentException	Thrown when name is null or whitespace.
InvalidOperationException	Thrown when no project is loaded.

Save

Saves the current project to the file system using the original file path.

Syntax

public void Save()

Exceptions

Exception	Description
InvalidOperationException	Thrown when no project is loaded or no file path is specified.

Save

Saves the current project to the specified file path.

Syntax

public void Save(string filePath)

Parameters

Name	Type	Description
filePath	string	The file path where the project should be saved.

Exceptions

Exception	Description
ArgumentException	Thrown when filePath is null or whitespace.
InvalidOperationException	Thrown when no project is loaded.

SetProperty

Sets a property value in the project.

Syntax

public CloudNimble.EasyAF.MSBuild.MSBuildProjectManager SetProperty(string name, string value)

Parameters

Name	Type	Description
name	string	The property name.
value	string	The property value.

Returns

Type: CloudNimble.EasyAF.MSBuild.MSBuildProjectManager The current instance for method chaining.

Exceptions

Exception	Description
ArgumentException	Thrown when name or value is null or whitespace.
InvalidOperationException	Thrown when no project is loaded.

ToString Inherited Virtual

Inherited from object

Syntax

public virtual string ToString()

Returns

Type: string?