MSBuild common routine for DragoAnt repositories

Prerequisites

• .NET SDK (the latest version recommended)
• MSBuild
• Git

Overview

This repository contains common MSBuild routines and configurations used across company repositories. It provides standardized build settings, version management, and project configurations.

You can copy this repository and adapt for your needs.

Key Features

Company-Specific Settings

• Standardized company information (ManufacturerName, FullManufacturerName)
• Default warning configurations
• GitLab CI integration
• Version management strategies:
  • DateBased (default): yyyy.M.d.$([MSBuild]::Modulo($(CIPipelineId), $(MaxBuildNumber)))
  • SemVer: Semantic versioning with build number
  • SemVer4: Modified semantic versioning(uses CI pipeline id as build number)
  • VersionTag: Git tag-based versioning

Build Configuration

• Nullable reference types enabled by default
• Implicit usings enabled
• Latest C# language version
• Code style enforcement in build
• Warning treatment as errors
• Documentation file generation for NuGet packages

Package Defaults

Applied to packable projects; each one is used only when the project leaves the property empty, so set it in Directory.Build.props (before or after the import) or in a .csproj to override it.

Property	Default
PackageIcon / PackageIconPath	package.icon.png from the repository root, packed as icon.png
Copyright	Copyright (c) <current year> $(FullManufacturerName)
RepositoryUrl	https://github.com/$(GITHUB_REPOSITORY) on GitHub Actions; unset on local builds
PackageProjectUrl	$(RepositoryUrl)
IncludeSymbols, SymbolPackageFormat	true, snupkg (off when the project has no separate pdb)

dotnet nuget push <dir>/*.nupkg also pushes the .snupkg that sits next to each package.

Project Structure

The repository is organized into several key directories:

• shared/: Contains common build configurations
  • common/: Common properties and settings
  • tests/: Test project configurations
  • utils/: Utility build scripts
  • checks/: Build validation checks

Key Files

• init.company.specific.props: Company-wide property definitions
• init.company.specific.targets: Company-wide target definitions
• shared/init.props: Base property initialization
• shared/init.targets: Base target initialization
• shared/version.props: Version management configuration
• Various local configuration files for secrets and project-specific settings

Usage

1. Add submodule to your git repository. File .gitmodules

   [submodule ".msbuild"]
    path = .msbuild
    url = ../MSBuild.Routine.git
    branch = master
   

2. Add Directory.Build.props in your solution's directory:

<Project>
  <PropertyGroup>
    <RepositoryUrl><!--your repo path --></RepositoryUrl>

    <TargetFramework>net9.0</TargetFramework>
    <IsPackable>false</IsPackable>

    <SlnSecretsId><!--your sln name --></SlnSecretsId>
  </PropertyGroup>

  <Import Project="$(MSBuildThisFileDirectory).msbuild\shared\init.props" />

</Project>

3. Add Directory.Build.targets in your solution's directory:

<Project>

  <Import Project="$(MSBuildThisFileDirectory).msbuild\shared\init.targets" />

</Project>

You can change properties to enable/disable MSBuild routine functionality in Directory.Build.props for all sln projects or in .csproj file for an individual project.

Version Management

The system supports multiple versioning strategies:

• DateBased (default): Uses date-based versioning with build number
• SemVer: Follows semantic versioning (https://semver.org/)
• SemVer4: Modified semantic versioning with build number(uses CI pipeline id as build number)
• VersionTag: Uses Git tags for versioning

On GitHub Actions the DragoAnt defaults pick the strategy from the ref:

Ref (GITHUB_REF_TYPE / GITHUB_REF_NAME)	Strategy	Version
tag v2.0.1 or 2.0.1	VersionTag	2.0.1 (a leading v/V is trimmed)
branch main, PR 15/merge, test_old	SemVer	$(VersionPrefix)-<ref>.<run id>, e.g. 1.0.0-15-merge.123456
local build (no GITHUB_RUN_ID)	DevEnv	9999.0.0

The prerelease part is the ref with every character outside [0-9A-Za-z-] replaced by -. A tag that is not valid SemVer 2.0 after trimming (e.g. v2.0) fails the build with an error naming the tag, instead of the silent MSB4181 restore failure. Set IncrementVersionType in Directory.Build.props, before the init.props import, to force a strategy on CI.

Security

The repository includes support for managing secrets and sensitive information:

• Local secrets management
• Directory-level secrets configuration
• Secret cleanup routines

Best Practices

1. Always use the company-specific settings for consistency
2. Enable code style enforcement in builds
3. Use the provided version management system
4. Follow the established project structure
5. Utilize the built-in security features for managing secrets

Questions

If you have questions or suggestions, feel free to write to Issues.

Useful links

• MSBuild Binary and Structured Log Viewer. Useful tool for MSBuild logs diagnostics. In Rider it will automatically open when build a project from ContextMenu > Advanced Build Actions > Rebuild Selected Project With Diagnostics An installation script below.

  winget install KirillOsenkov.MSBuildStructuredLogViewer