.CSPROJ

Task 116: .CSPROJ File Format

Task 116: .CSPROJ File Format

thinkmelt@protonmail.com

• 6 min read

The .csproj file format is an XML-based format used by Microsoft Visual Studio and MSBuild for C# project files. It defines project settings, build configurations, file inclusions, references, and other metadata required to build .NET applications. The format follows the MSBuild XML schema, with a root  element and no strict binary structure or magic number (as it's text-based XML starting with ). The schema is documented in detail by Microsoft, including elements like PropertyGroup for settings and ItemGroup for files/references.

Based on the MSBuild schema and common usage in .csproj files, the intrinsic properties (referring to the key XML elements, attributes, and standard MSBuild properties that define the file's structure and content) include the following. These are not file system metadata (e.g., size or timestamps) but format-specific properties like configuration settings, build targets, and item definitions. I've compiled a comprehensive list from official documentation, categorizing where applicable. Note that .csproj files can include custom properties, but these are the standard ones.

Main Structural Elements (from Schema):

  • Project (root): Attributes - DefaultTargets, InitialTargets, Sdk, ToolsVersion, TreatAsLocalProperty, xmlns.
  • PropertyGroup: Attributes - Condition. Contains child property elements.
  • ItemGroup: Attributes - Condition. Contains child item elements.
  • Target: Attributes - AfterTargets, BeforeTargets, Condition, DependsOnTargets, Inputs, KeepDuplicateOutputs, Name, Outputs, Returns.
  • Import: Attributes - Condition, Project.
  • Item: Attributes - Condition, Exclude, Include, Remove.

Common Properties (typically in PropertyGroup):

  • Configuration
  • Platform
  • ProjectGuid
  • OutputType
  • TargetFramework
  • AssemblyName
  • RootNamespace

All Documented MSBuild Properties (categorized):

Assembly Validation Properties:

  • ApiCompatStrictMode
  • ApiCompatValidateAssemblies

Assembly Attribute Properties:

  • GenerateAssemblyInfo
  • GeneratedAssemblyInfoFile

Framework Properties:

  • TargetFramework
  • TargetFrameworks
  • NetStandardImplicitPackageVersion

Package Properties:

  • PackageId
  • PackageVersion
  • PackageIcon
  • Title
  • Description
  • PackRelease

Package Validation Properties:

  • ApiCompatEnableRuleAttributesMustMatch
  • ApiCompatEnableRuleCannotChangeParameterName
  • ApiCompatExcludeAttributesFile
  • ApiCompatGenerateSuppressionFile
  • ApiCompatPermitUnnecessarySuppressions
  • ApiCompatPreserveUnnecessarySuppressions
  • ApiCompatRespectInternals
  • ApiCompatSuppressionFile
  • ApiCompatSuppressionOutputFile
  • EnablePackageValidation
  • EnableStrictModeForBaselineValidation
  • EnableStrictModeForCompatibleFrameworksInPackage
  • EnableStrictModeForCompatibleTfms
  • NoWarn
  • PackageValidationBaselineFrameworkToIgnore
  • PackageValidationBaselineName
  • PackageValidationBaselineVersion
  • PackageValidationReferencePath
  • RoslynAssembliesPath

Build Output and Path Properties:

  • AppendTargetFrameworkToOutputPath
  • AppendRuntimeIdentifierToOutputPath
  • CopyLocalLockFileAssemblies
  • ErrorOnDuplicatePublishOutputFiles
  • GenerateRuntimeConfigDevFile
  • GenerateRuntimeConfigurationFiles
  • GenerateSatelliteAssembliesForCore
  • IsPublishable
  • PreserveCompilationContext
  • PreserveCompilationReferences
  • ProduceReferenceAssemblyInOutDir
  • PublishDocumentationFile
  • PublishDocumentationFiles
  • PublishReferencesDocumentationFiles
  • PublishRelease
  • PublishSelfContained
  • RollForward
  • RuntimeFrameworkVersion
  • RuntimeIdentifier
  • RuntimeIdentifiers
  • SatelliteResourceLanguages
  • SelfContained
  • UseAppHost

Trimming Properties:

  • PublishTrimmed
  • TrimMode
  • SuppressTrimAnalysisWarnings
  • EnableTrimAnalyzer
  • ILLinkTreatWarningsAsErrors
  • TrimmerSingleWarn
  • TrimmerRemoveSymbols

Build and Compilation Properties:

  • ContinuousIntegrationBuild
  • CopyDebugSymbolFilesFromPackages
  • CopyDocumentationFilesFromPackages
  • DisableImplicitFrameworkDefines
  • DocumentationFile
  • EmbeddedResourceUseDependentUponConvention
  • EnablePreviewFeatures
  • EnableWindowsTargeting
  • GenerateDocumentationFile
  • GenerateRequiresPreviewFeaturesAttribute
  • OptimizeImplicitlyTriggeredBuild
  • DisableRuntimeMarshalling
  • BuildWithNetFrameworkHostedCompiler
  • RoslynCompilerType

Default Item Inclusion Properties:

  • DefaultItemExcludes
  • DefaultItemExcludesInProjectFolder
  • EnableDefaultItems
  • EnableDefaultCompileItems
  • EnableDefaultEmbeddedResourceItems
  • EnableDefaultNoneItems

Code Analysis Properties:

  • AnalysisLevel
  • AnalysisLevelDesign
  • AnalysisLevelDocumentation
  • AnalysisLevelGlobalization
  • AnalysisLevelInteroperability
  • AnalysisLevelMaintainability
  • AnalysisLevelNaming
  • AnalysisLevelPerformance
  • AnalysisLevelSingleFile
  • AnalysisLevelReliability
  • AnalysisLevelSecurity
  • AnalysisLevelStyle
  • AnalysisLevelUsage
  • AnalysisMode
  • AnalysisModeDesign
  • AnalysisModeDocumentation
  • AnalysisModeGlobalization
  • AnalysisModeInteroperability
  • AnalysisModeMaintainability
  • AnalysisModeNaming
  • AnalysisModePerformance
  • AnalysisModeSingleFile
  • AnalysisModeReliability
  • AnalysisModeSecurity
  • AnalysisModeStyle
  • AnalysisModeUsage
  • CodeAnalysisTreatWarningsAsErrors
  • EnableNETAnalyzers
  • EnforceCodeStyleInBuild
  • _SkipUpgradeNetAnalyzersNuGetWarning

Runtime Configuration Properties:

  • AutoreleasePoolSupport
  • ConcurrentGarbageCollection
  • InvariantGlobalization
  • PredefinedCulturesOnly
  • RetainVMGarbageCollection
  • ServerGarbageCollection
  • ThreadPoolMaxThreads
  • ThreadPoolMinThreads
  • TieredCompilation
  • TieredCompilationQuickJit
  • TieredCompilationQuickJitForLoops
  • TieredPGO
  • UseWindowsThreadPool

Dependency and Package Management Properties:

  • AssetTargetFallback
  • DisableImplicitFrameworkReferences
  • DisableTransitiveFrameworkReferenceDownloads
  • DisableTransitiveProjectReferences
  • ManagePackageVersionsCentrally
  • RestoreIgnoreFailedSource
  • UseMauiEssentials
  • ValidateExecutableReferencesMatchSelfContained
  • WindowsSdkPackageVersion

Run and Launch Properties:

  • RunArguments
  • RunWorkingDirectory

SDK and Tooling Properties:

  • SdkAnalysisLevel

Testing Platform Properties:

  • IsTestingPlatformApplication
  • EnableMicrosoftTestingExtensionsCrashDump (and similar patterns like Enable[NugetPackageName])

Two direct download links for sample .csproj files (these are raw GitHub links that download the file directly when accessed):

Below is a self-contained HTML page with embedded JavaScript that can be embedded in a Ghost blog (or any HTML-based blog). It allows drag-and-drop of a .csproj file and dumps all extracted properties (i.e., name-value pairs from  elements in the XML) to the screen. It uses browser APIs for file reading and XML parsing.

CSProj Property Dumper
Drag and drop a .csproj file here
  1. Below is a Python class that can open, parse (decode/read), modify (write), and print all properties (name-value pairs from ) from a .csproj file to the console.
import xml.etree.ElementTree as ET
import os

class CSProjHandler:
    def __init__(self, file_path):
        self.file_path = file_path
        self.tree = None
        self.root = None
        self.load()

    def load(self):
        """Load and parse the .csproj file."""
        if not os.path.exists(self.file_path) or not self.file_path.endswith('.csproj'):
            raise ValueError("Invalid .csproj file path.")
        self.tree = ET.parse(self.file_path)
        self.root = self.tree.getroot()

    def get_properties(self):
        """Extract all properties from PropertyGroup elements."""
        properties = {}
        for prop_group in self.root.findall('.//PropertyGroup'):
            for prop in prop_group:
                properties[prop.tag] = prop.text.strip() if prop.text else ''
        return properties

    def print_properties(self):
        """Print all properties to console."""
        props = self.get_properties()
        print("Extracted Properties:")
        for name, value in props.items():
            print(f"{name}: {value}")

    def set_property(self, name, value):
        """Set or add a property in the first PropertyGroup."""
        prop_group = self.root.find('.//PropertyGroup')
        if prop_group is None:
            prop_group = ET.SubElement(self.root, 'PropertyGroup')
        prop = prop_group.find(name)
        if prop is None:
            prop = ET.SubElement(prop_group, name)
        prop.text = value

    def save(self, output_path=None):
        """Save the modified .csproj file."""
        if output_path is None:
            output_path = self.file_path
        self.tree.write(output_path, encoding='utf-8', xml_declaration=True)

# Example usage:
# handler = CSProjHandler('path/to/sample.csproj')
# handler.print_properties()
# handler.set_property('NewProperty', 'Value')
# handler.save()
  1. Below is a Java class that can open, parse (decode/read), modify (write), and print all properties (name-value pairs from ) from a .csproj file to the console.
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;
import java.io.File;

public class CSProjHandler {
    private String filePath;
    private Document doc;

    public CSProjHandler(String filePath) {
        this.filePath = filePath;
        load();
    }

    private void load() {
        if (!new File(filePath).exists() || !filePath.endsWith(".csproj")) {
            throw new IllegalArgumentException("Invalid .csproj file path.");
        }
        try {
            DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
            DocumentBuilder dBuilder = dbFactory.newDocumentBuilder();
            doc = dBuilder.parse(filePath);
            doc.getDocumentElement().normalize();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public void printProperties() {
        System.out.println("Extracted Properties:");
        NodeList propGroups = doc.getElementsByTagName("PropertyGroup");
        for (int i = 0; i < propGroups.getLength(); i++) {
            NodeList props = propGroups.item(i).getChildNodes();
            for (int j = 0; j < props.getLength(); j++) {
                if (props.item(j) instanceof Element) {
                    Element prop = (Element) props.item(j);
                    String value = prop.getTextContent().trim();
                    System.out.println(prop.getTagName() + ": " + value);
                }
            }
        }
    }

    public void setProperty(String name, String value) {
        NodeList propGroups = doc.getElementsByTagName("PropertyGroup");
        Element propGroup = (propGroups.getLength() > 0) ? (Element) propGroups.item(0) : doc.getDocumentElement().appendChild(doc.createElement("PropertyGroup"));
        NodeList existing = propGroup.getElementsByTagName(name);
        Element prop = (existing.getLength() > 0) ? (Element) existing.item(0) : propGroup.appendChild(doc.createElement(name));
        prop.setTextContent(value);
    }

    public void save(String outputPath) {
        if (outputPath == null) outputPath = filePath;
        try {
            TransformerFactory transformerFactory = TransformerFactory.newInstance();
            Transformer transformer = transformerFactory.newTransformer();
            DOMSource source = new DOMSource(doc);
            StreamResult result = new StreamResult(new File(outputPath));
            transformer.transform(source, result);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    // Example usage:
    // public static void main(String[] args) {
    //     CSProjHandler handler = new CSProjHandler("path/to/sample.csproj");
    //     handler.printProperties();
    //     handler.setProperty("NewProperty", "Value");
    //     handler.save(null);
    // }
}
  1. Below is a JavaScript class (Node.js compatible, using fs and xml2js for parsing) that can open, parse (decode/read), modify (write), and print all properties (name-value pairs from ) from a .csproj file to the console. Requires xml2js npm package.
const fs = require('fs');
const xml2js = require('xml2js');

class CSProjHandler {
    constructor(filePath) {
        this.filePath = filePath;
        this.xmlData = null;
        this.load();
    }

    load() {
        if (!fs.existsSync(this.filePath) || !this.filePath.endsWith('.csproj')) {
            throw new Error('Invalid .csproj file path.');
        }
        const xml = fs.readFileSync(this.filePath, 'utf-8');
        xml2js.parseString(xml, (err, result) => {
            if (err) throw err;
            this.xmlData = result;
        });
    }

    getProperties() {
        const properties = {};
        const propGroups = this.xmlData.Project.PropertyGroup || [];
        propGroups.forEach(group => {
            Object.keys(group).forEach(key => {
                properties[key] = group[key][0];
            });
        });
        return properties;
    }

    printProperties() {
        const props = this.getProperties();
        console.log('Extracted Properties:');
        Object.entries(props).forEach(([name, value]) => {
            console.log(`${name}: ${value}`);
        });
    }

    setProperty(name, value) {
        if (!this.xmlData.Project.PropertyGroup) {
            this.xmlData.Project.PropertyGroup = [{}];
        }
        this.xmlData.Project.PropertyGroup[0][name] = [value];
    }

    save(outputPath = this.filePath) {
        const builder = new xml2js.Builder({ renderOpts: { 'pretty': true, 'indent': '  ', 'newline': '\n' }, xmldec: { 'version': '1.0', 'encoding': 'utf-8' } });
        const xml = builder.buildObject(this.xmlData);
        fs.writeFileSync(outputPath, xml);
    }
}

// Example usage:
// const handler = new CSProjHandler('path/to/sample.csproj');
// handler.printProperties();
// handler.setProperty('NewProperty', 'Value');
// handler.save();
  1. Below is a C++ class (using pugixml library for XML parsing, as standard C++ lacks built-in XML support; assume pugixml is included) that can open, parse (decode/read), modify (write), and print all properties (name-value pairs from ) from a .csproj file to the console.
#include <iostream>
#include <string>
#include <pugixml.hpp>  // Assume pugixml.hpp is included/compiled with this

class CSProjHandler {
private:
    std::string filePath;
    pugi::xml_document doc;

public:
    CSProjHandler(const std::string& path) : filePath(path) {
        load();
    }

    void load() {
        if (filePath.substr(filePath.find_last_of(".") + 1) != "csproj") {
            throw std::invalid_argument("Invalid .csproj file path.");
        }
        pugi::xml_parse_result result = doc.load_file(filePath.c_str());
        if (!result) {
            throw std::runtime_error("Failed to parse XML.");
        }
    }

    void printProperties() {
        std::cout << "Extracted Properties:" << std::endl;
        for (pugi::xml_node propGroup : doc.child("Project").children("PropertyGroup")) {
            for (pugi::xml_node prop : propGroup.children()) {
                std::cout << prop.name() << ": " << prop.child_value() << std::endl;
            }
        }
    }

    void setProperty(const std::string& name, const std::string& value) {
        pugi::xml_node propGroup = doc.child("Project").child("PropertyGroup");
        if (!propGroup) {
            propGroup = doc.child("Project").append_child("PropertyGroup");
        }
        pugi::xml_node prop = propGroup.child(name.c_str());
        if (!prop) {
            prop = propGroup.append_child(name.c_str());
        }
        prop.text().set(value.c_str());
    }

    void save(const std::string& outputPath = "") {
        std::string path = outputPath.empty() ? filePath : outputPath;
        doc.save_file(path.c_str(), "  ", pugi::format_default | pugi::format_write_bom, pugi::encoding_utf8);
    }
};

// Example usage:
// int main() {
//     try {
//         CSProjHandler handler("path/to/sample.csproj");
//         handler.printProperties();
//         handler.setProperty("NewProperty", "Value");
//         handler.save();
//     } catch (const std::exception& e) {
//         std::cerr << e.what() << std::endl;
//     }
//     return 0;
// }