如何通过MSBuild自动生成OpenAPI C#客户端库替代Post Build事件？

安全阿岳

2026-8-14

使用NSwag ServiceProjectReference实现API客户端自动生成与NuGet推送

可行性结论

NSwag的ServiceProjectReference是当前最简洁现代化的实现方案，完全满足你的需求：无需启动API服务、无需独立依赖第三方CLI，直接通过MSBuild集成实现从API项目元数据生成客户端代码、关联GitVersion版本号、打包推送私有NuGet源的全自动化流程。

具体实现步骤

1. 基础环境准备

确保API项目已配置Swashbuckle.AspNetCore，能正常生成OpenAPI文档（常规配置即可，无需额外修改）。
安装GitVersion：通过dotnet tool install --global GitVersion.Tool全局安装，或在解决方案中通过Directory.Build.props集成（推荐后者保证团队一致性）。
配置私有NuGet源：在本地NuGet.config或CI/CD环境中添加私有源的地址与访问凭据。

2. 创建客户端类库项目

新建一个.NET 6（或.NET Standard 2.0+）类库项目，用于承载生成的客户端代码。安装NSwag.MSBuild包：

dotnet add package NSwag.MSBuild

3. 配置ServiceProjectReference关联API项目

编辑客户端项目的.csproj文件，添加对API项目的服务引用，同时配置客户端生成规则：

<PropertyGroup>
  <!-- 启用GitVersion版本同步 -->
  <Version>$(GitVersion_SemVer)</Version>
  <PackageVersion>$(GitVersion_SemVer)</PackageVersion>
  <Authors>YourTeam</Authors>
  <Description>自动生成的API客户端库</Description>
</PropertyGroup>

<ItemGroup>
  <!-- 关联API项目，自动生成客户端代码 -->
  <ServiceProjectReference Include="..\YourApiProjectName\YourApiProjectName.csproj">
    <Name>YourApiClient</Name> <!-- 生成的客户端类名称 -->
    <Namespace>YourCompany.YourProduct.ApiClient</Namespace> <!-- 客户端代码命名空间 -->
    <OutputPath>Generated</OutputPath> <!-- 生成代码的存放目录 -->
    <GenerateClientInterfaces>true</GenerateClientInterfaces> <!-- 是否生成接口便于依赖注入 -->
    <GenerateDtoTypes>true</GenerateDtoTypes> <!-- 是否自动生成DTO类 -->
    <ClientBaseClass>System.Net.Http.HttpClient</ClientBaseClass> <!-- 客户端基类 -->
  </ServiceProjectReference>
</ItemGroup>

<Target Name="PackAndPushToNuGet" AfterTargets="Pack">
  <!-- 打包完成后自动推送到私有NuGet源 -->
  <Exec Command="dotnet nuget push &quot;$(OutputPath)$(AssemblyName).$(PackageVersion).nupkg&quot; --source YourPrivateNuGetSource --api-key %(NuGetApiKey)" />
</Target>

4. 配置GitVersion自动计算版本

在解决方案根目录添加GitVersion.yml文件，配置符合你项目分支策略的版本规则示例：

mode: Mainline
branches:
  main:
    regex: ^main$
    mode: Mainline
    tag: ''
    increment: Patch
    prevent-increment-of-merged-branch-version: true
    track-merge-target: false
  develop:
    regex: ^dev(elop)?(ment)?$
    mode: ContinuousDeployment
    tag: alpha
    increment: Minor
    prevent-increment-of-merged-branch-version: false
    track-merge-target: true

5. 验证自动化流程

本地构建解决方案：客户端项目会自动分析API项目的元数据生成客户端代码，无需启动API服务；GitVersion会根据当前分支、提交记录计算SemVer版本号；完成代码生成后自动打包并推送到私有NuGet源。
CI/CD环境集成：只需确保CI环境已安装GitVersion、配置NuGet源凭据，执行dotnet build或dotnet pack即可触发全流程。

方案优势对比

无需启动API服务：直接通过MSBuild分析API项目代码生成OpenAPI规范，避免了原方案中启动服务的依赖与耗时。
无独立CLI依赖：NSwag逻辑完全集成在MSBuild流程中，无需单独安装NSwag CLI或维护复杂的Post Build脚本。
版本自动同步：GitVersion的版本号直接注入客户端项目的版本属性，保证客户端与API版本严格一致。

内容的提问来源于stack exchange，提问作者void.pointer