Release构建自动递增版本号的Directory.Build.targets问题排查

问题背景 #

编写Directory.Build.targets文件，期望在Release配置构建时自动递增项目版本号（如从1.0.0.0变为1.0.0.1），先解决了MSB4067 The element <WriteLinesToFile> beneath element <Target> is unrecognized错误，但当前版本号递增逻辑（旧版本号+1）无法生效，System.Int32.Parse等转换方法不工作，需要排查实现问题并寻找跨Windows本地和CI环境的简便方案。

原实现代码 #

<Project Sdk="Microsoft.NET.Sdk">
    <Target Name="IncrementBuildNumber" BeforeTargets="GenerateAssemblyInfo" Condition="'$(Configuration)' == 'Release'">
        <PropertyGroup>
            <VersionFile>$(MSBuildThisFileDirectory)version.txt</VersionFile>
        </PropertyGroup>

        <ReadLinesFromFile File="$(VersionFile)">
            <Output TaskParameter="Lines" ItemName="VersionLines"/>
        </ReadLinesFromFile>

        <PropertyGroup>
            <VersionString>%(VersionLines[0])</VersionString>
            <MajorVersion>$([System.String]::Split($(VersionString), '.')[0])</MajorVersion>
            <MinorVersion>$([System.String]::Split($(VersionString), '.')[1])</MinorVersion>
            <PatchNumber>$([System.String]::Split($(VersionString), '.')[2])</PatchNumber>
            <BuildNumber>$([System.String]::Split($(VersionString), '.')[3])</BuildNumber>
        </PropertyGroup>

        <PropertyGroup>
            <NewBuildNumber>$([System.Int32]::Parse($(BuildNumber)) + 1)</NewBuildNumber>
            <NewVersion>$(MajorVersion).$(MinorVersion).$(PatchNumber).$(NewBuildNumber)</NewVersion>
        </PropertyGroup>

        <WriteLinesToFile File="$(VersionFile)" Overwrite="true">
            $(NewVersion)
        </WriteLinesToFile>

        <PropertyGroup>
            <Version>$(NewVersion)</Version>
        </PropertyGroup>
    </Target>
</Project>

当前实现的问题分析 #

1. Item取值错误：VersionLines是通过ReadLinesFromFile输出的Item集合，取第一个元素内容应该用@(VersionLines)或%(VersionLines.Identity)，而非%(VersionLines[0])，后者不符合MSBuild语法，导致VersionString为空，后续版本号拆分、转换全部失效。
2. WriteLinesToFile用法错误：原代码直接将$(NewVersion)放在标签内部，正确写法需要用<Lines>属性或<Text>子元素包裹内容，这也是最初出现MSB4067错误的核心原因。
3. 属性计算顺序问题：同一个PropertyGroup内的属性相互引用时，MSBuild的计算顺序可能导致依赖属性未正确赋值，建议拆分到独立的PropertyGroup块中。

修正后的可行代码 #

<Project Sdk="Microsoft.NET.Sdk">
    <Target Name="IncrementBuildNumber" BeforeTargets="GenerateAssemblyInfo" Condition="'$(Configuration)' == 'Release'">
        <!-- 定义版本文件路径及默认初始版本 -->
        <PropertyGroup>
            <VersionFile>$(MSBuildThisFileDirectory)version.txt</VersionFile>
            <DefaultVersion>1.0.0.0</DefaultVersion>
        </PropertyGroup>

        <!-- 版本文件不存在时自动初始化 -->
        <Touch Files="$(VersionFile)" Condition="!Exists('$(VersionFile)')" />
        <WriteLinesToFile File="$(VersionFile)" Lines="$(DefaultVersion)" Overwrite="false" Condition="!Exists('$(VersionFile)')" />

        <!-- 读取版本文件内容 -->
        <ReadLinesFromFile File="$(VersionFile)">
            <Output TaskParameter="Lines" ItemName="VersionLines"/>
        </ReadLinesFromFile>

        <!-- 解析版本号各段 -->
        <PropertyGroup>
            <VersionString>@(VersionLines)</VersionString>
            <MajorVersion>$([System.String]::Split('$(VersionString)', '.')[0])</MajorVersion>
            <MinorVersion>$([System.String]::Split('$(VersionString)', '.')[1])</MinorVersion>
            <PatchNumber>$([System.String]::Split('$(VersionString)', '.')[2])</PatchNumber>
            <BuildNumber>$([System.String]::Split('$(VersionString)', '.')[3])</BuildNumber>
        </PropertyGroup>

        <!-- 递增构建号并生成新版本号 -->
        <PropertyGroup>
            <NewBuildNumber>$([System.Int32]::Parse('$(BuildNumber)') + 1)</NewBuildNumber>
            <NewVersion>$(MajorVersion).$(MinorVersion).$(PatchNumber).$(NewBuildNumber)</NewVersion>
        </PropertyGroup>

        <!-- 写入新版本号到文件 -->
        <WriteLinesToFile File="$(VersionFile)" Lines="$(NewVersion)" Overwrite="true" />

        <!-- 同步设置项目版本相关属性 -->
        <PropertyGroup>
            <Version>$(NewVersion)</Version>
            <AssemblyVersion>$(NewVersion)</AssemblyVersion>
            <FileVersion>$(NewVersion)</FileVersion>
        </PropertyGroup>
    </Target>
</Project>

跨环境简便方案推荐 #

方案1：使用GitVersion（推荐） #

GitVersion是跨平台工具，可根据Git提交记录自动生成版本号，支持Windows、Linux、Mac及各类CI环境，无需手动维护version.txt：

• 安装：dotnet tool install --global GitVersion.Tool
• 在项目根目录执行gitversion init生成配置文件，按需调整版本规则
• 在Directory.Build.targets中添加版本注入逻辑：

<Target Name="SetVersionFromGitVersion" BeforeTargets="GenerateAssemblyInfo">
    <Exec Command="dotnet gitversion /output buildserver /nofetch" ConsoleToMSBuild="true">
        <Output TaskParameter="ConsoleOutput" PropertyName="GitVersionOutput" />
    </Exec>
    <PropertyGroup>
        <Version>$([System.Text.RegularExpressions.Regex]::Match('$(GitVersionOutput)', 'SemVer: (.*)').Groups[1].Value)</Version>
    </PropertyGroup>
</Target>

方案2：基于CI环境变量的轻量实现 #

如果不需要关联Git提交记录，可直接复用CI环境自带的BuildNumber变量（如Azure DevOps、GitHub Actions均默认提供），结合基础版本号：

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup Condition="'$(Configuration)' == 'Release'">
        <BaseVersion>1.0.0</BaseVersion>
        <!-- 本地构建默认用0，CI环境自动使用BuildNumber -->
        <Version>$(BaseVersion).$([System.String]::IsNullOrEmpty('$(BuildNumber)') ? '0' : '$(BuildNumber)')</Version>
    </PropertyGroup>
</Project>

内容的提问来源于stack exchange，提问作者André Polykanine