NSwag项目升级后生成异常类配置问题的解决方案

问题背景

在使用NSwag.ApiDescription.Client进行API客户端代码生成时，部分用户在从13.20.0版本升级到14.0.3版本后遇到了一个MSBuild错误。该错误提示系统期望获取一个布尔值，但实际得到了空字符串，导致代码生成过程失败。

错误现象

具体错误信息表现为：

MSB4100: Expected "%(NSwagGenerateExceptionClasses)" to evaluate to a boolean instead of ""

这个错误发生在条件判断"!%(FirstForGenerator) OR !%(NSwagGenerateExceptionClasses)"时，表明系统无法正确解析NSwagGenerateExceptionClasses参数的值。

问题根源

经过分析，这个问题源于14.x版本中对异常类生成机制的改进。新版本要求明确指定是否生成异常类，而不再采用隐式默认值。这种改变提高了配置的明确性，但导致了旧项目升级时的兼容性问题。

解决方案

方案一：显式指定异常类生成选项

在OpenApiReference项中直接添加NSwagGenerateExceptionClasses属性：

<ItemGroup>
    <OpenApiReference 
        Include="api.yaml" 
        CodeGenerator="NSwagCSharp" 
        Namespace="Your.Namespace" 
        ClassName="YourApi"
        NSwagGenerateExceptionClasses="true" />
</ItemGroup>

方案二：通过PropertyGroup全局设置

对于不需要生成异常类的情况，可以在项目文件中添加全局属性：

<PropertyGroup>
    <NSwagGenerateExceptionClasses>false</NSwagGenerateExceptionClasses>
</PropertyGroup>

方案三：升级到修复版本

该问题在NSwag 14.0.4版本中已得到修复。建议用户直接升级到最新稳定版本：

<PackageReference Include="NSwag.ApiDescription.Client" Version="14.0.4" />

注意事项

1. 命名规范变化：新版本对生成的类名处理有所调整，可能会将某些类名首字母改为小写。这是为了更好符合OpenAPI规范，但可能与C#命名惯例不符。用户可以通过后续处理或自定义模板来调整。

2. 配置迁移：从旧版本迁移时，建议检查所有OpenApiReference项的配置，确保所有开关参数都显式声明。

3. 构建环境：确保构建环境中的MSBuild版本支持新的条件判断语法，避免因环境差异导致的问题。

最佳实践

1. 对于新项目，建议始终显式声明NSwagGenerateExceptionClasses参数
2. 定期更新NSwag包到最新稳定版本
3. 在团队开发环境中统一NSwag配置标准
4. 考虑将API客户端生成配置放入独立的.props文件便于管理

通过以上措施，可以有效避免类似问题的发生，并确保API客户端代码生成的稳定性和一致性。