1. 理解MAUI项目中的版本控制
在.NET MAUI开发中，版本控制是一个看似简单实则暗藏玄机的重要环节。我刚接触MAUI时，就曾因为版本设置不当导致应用商店审核被拒，后来花了整整两天时间才排查出问题所在。今天我就来详细拆解这些版本属性的区别和使用场景。
先来看一个典型的MAUI项目.csproj文件中的版本配置片段：
xml复制<Project>
<PropertyGroup>
<Version>1.0.0</Version>
<AssemblyVersion>1.0.0.0</AssemblyVersion>
<PackageVersion>1.0.0</PackageVersion>
<ApplicationDisplayVersion>1.0</ApplicationVersion>
<ApplicationVersion>1</ApplicationVersion>
</PropertyGroup>
</Project>
这五个属性各司其职，理解它们的区别是避免后续麻烦的关键。让我用一个实际案例来说明：我们团队曾发布一个MAUI应用到App Store，明明功能测试通过，却被苹果拒绝，原因就是ApplicationVersion设置不当。这个教训让我深刻认识到版本控制的重要性。
2. 版本属性深度解析
2.1 Version属性：NuGet包的基石
Version属性是SDK风格项目的核心版本标识，它遵循语义化版本控制(SemVer)规范。在我的实际项目中，这个属性主要影响三个方面：
- NuGet包默认版本：当你不显式设置PackageVersion时，打包工具会使用Version值作为包版本
- 项目引用解析：其他项目通过PackageReference引用时，会依据此版本进行依赖解析
- 构建输出：影响编译生成的程序集信息
提示：SemVer规范要求版本格式为
主版本.次版本.补丁版本，例如2.5.3。主版本变化表示不兼容的API修改，次版本表示向后兼容的功能新增，补丁版本表示向后兼容的问题修正。
2.2 AssemblyVersion：运行时的身份证明
AssemblyVersion是.NET生态中最重要的版本标识之一，它会被编译进程序集的元数据。这个属性的特殊之处在于：
- 强名称程序集必须：如果你使用强名称签名，这个版本就是程序集的唯一身份标识
- 影响绑定策略：.NET运行时根据这个版本决定加载哪个程序集
- 格式严格：必须是四段式数字，如1.0.0.0
我在一个企业级项目中就遇到过AssemblyVersion变更导致的运行时错误：更新了一个类库但忘记递增版本号，导致应用程序仍然加载旧版本，引发难以排查的异常。
2.3 PackageVersion：NuGet发布的控制阀
PackageVersion属性给了开发者更精细的NuGet包版本控制能力。与Version属性相比：
- 优先级更高：设置后会覆盖Version值
- 支持预发布标记：可以添加
-alpha、-beta等后缀 - 影响依赖解析：NuGet客户端会根据这个版本解决依赖关系
实际开发中，我常用这样的版本策略：
xml复制<PackageVersion>2.1.0-rc.1</PackageVersion>
表示这是2.1.0的候选发布版1号，方便进行预发布测试。
2.4 ApplicationDisplayVersion：用户可见的友好版本
这个属性在MAUI、WPF等客户端应用中特别重要，它决定了用户看到的版本信息。几个关键点：
- 显示位置：应用的"关于"对话框、设置页面、安装程序界面等
- 格式灵活：可以使用更友好的格式，如"2024春季版"
- 多平台一致：MAUI会确保各平台显示相同的版本信息
我在一个跨平台应用中就利用这个特性，设置了<ApplicationDisplayVersion>2024.1</ApplicationDisplayVersion>，让用户更容易理解版本含义。
2.5 ApplicationVersion：应用商店的通行证
这是最容易被忽视但至关重要的属性，特别是在提交到应用商店时：
- 必须为整数：苹果App Store和Google Play都要求递增的整数值
- 每次提交必须增加：否则会被商店拒绝
- 独立于其他版本：可以与语义版本完全不同
我曾经踩过的坑：连续两次提交都使用ApplicationVersion="1"，结果被苹果拒绝。现在我的团队严格执行每次发布递增1的策略。
3. 版本属性的对比与选择
3.1 属性功能对比表
通过下表可以清晰看到各属性的区别：
| 属性 | 格式要求 | 主要用途 | 是否必须 | 示例 |
|---|---|---|---|---|
| Version | SemVer字符串 | NuGet包默认版本 | 否 | 1.5.2 |
| AssemblyVersion | 四段数字 | 运行时程序集绑定 | 是(强名称) | 1.5.2.0 |
| PackageVersion | SemVer字符串 | 显式NuGet包版本 | 否 | 2.0.0-alpha |
| ApplicationDisplayVersion | 任意字符串 | 用户界面显示 | MAUI建议 | 2024.1 |
| ApplicationVersion | 整数 | 应用商店提交 | MAUI必须 | 42 |
3.2 不同项目类型的配置建议
类库项目最佳实践
对于纯类库项目，通常只需要设置两个版本属性：
xml复制<Version>1.0.0</Version>
<AssemblyVersion>1.0.0.0</AssemblyVersion>
如果类库需要发布预发布包，可以添加：
xml复制<PackageVersion>1.0.0-beta.1</PackageVersion>
MAUI应用完整配置
MAUI应用由于涉及多平台发布，建议设置全部版本属性：
xml复制<Version>1.0.0</Version>
<AssemblyVersion>1.0.0.0</AssemblyVersion>
<PackageVersion>1.0.0</PackageVersion>
<ApplicationDisplayVersion>1.0</ApplicationDisplayVersion>
<ApplicationVersion>1</ApplicationVersion>
注意：ApplicationVersion每次发布到应用商店时必须递增，这是硬性要求。
4. 实战中的版本管理策略
4.1 自动化版本递增方案
手动维护版本号容易出错，我推荐以下几种自动化方案：
- 使用MSBuild任务自动递增：
xml复制<Target Name="IncrementVersion" BeforeTargets="Build">
<PropertyGroup>
<ApplicationVersion>$([MSBuild]::Add($(ApplicationVersion), 1))</ApplicationVersion>
</PropertyGroup>
</Target>
-
GitVersion工具：
根据Git提交历史自动生成语义版本，特别适合持续集成环境。 -
自定义脚本：
编写简单的PowerShell或Bash脚本在构建前修改版本号。
4.2 多环境版本标记策略
在实际开发中，我们通常需要区分开发、测试和生产环境。我的做法是：
xml复制<!-- 开发环境 -->
<PackageVersion>1.0.0-dev</PackageVersion>
<!-- 测试环境 -->
<PackageVersion>1.0.0-qa</PackageVersion>
<!-- 生产环境 -->
<PackageVersion>1.0.0</PackageVersion>
这样在NuGet仓库中就能清晰区分不同环境的包。
4.3 常见问题排查指南
-
应用商店拒绝提交：
- 检查ApplicationVersion是否已递增
- 确认ApplicationVersion是纯整数
- 确保新版本的ApplicationVersion大于上次提交
-
运行时程序集加载失败：
- 检查AssemblyVersion是否一致
- 强名称程序集必须完全匹配版本
- 考虑使用bindingRedirect（传统.NET Framework）
-
NuGet包依赖冲突：
- 确认PackageVersion符合SemVer规范
- 检查依赖项目是否指定了正确的版本范围
- 使用
dotnet list package --outdated检查过时包
5. 高级版本控制技巧
5.1 条件化版本设置
在复杂的项目中，可能需要根据不同配置设置不同版本。MSBuild的条件语法可以帮上忙：
xml复制<PropertyGroup Condition="'$(Configuration)' == 'Release'">
<PackageVersion>1.0.0</PackageVersion>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
<PackageVersion>1.0.0-dev</PackageVersion>
</PropertyGroup>
5.2 多目标框架的版本控制
当项目支持多个目标框架时，可能需要不同的版本策略：
xml复制<PropertyGroup>
<Version>1.0.0</Version>
<AssemblyVersion Condition="'$(TargetFramework)' == 'net6.0'">1.0.0.1</AssemblyVersion>
<AssemblyVersion Condition="'$(TargetFramework)' == 'netstandard2.0'">1.0.0.2</AssemblyVersion>
</PropertyGroup>
5.3 版本信息与构建元数据
对于追求精细控制的团队，可以在版本中包含构建信息：
xml复制<PropertyGroup>
<Version>1.0.0+$([System.DateTime]::Now.ToString("yyyyMMdd"))</Version>
</PropertyGroup>
+后面的部分是构建元数据，不会影响版本解析，但可以用于追踪。
经过多个MAUI项目的实战，我发现合理的版本控制策略能为团队节省大量调试和排查时间。特别是在持续交付环境中，自动化的版本管理更是必不可少。希望这些经验能帮助你避开我踩过的那些坑。