如何解决Azure Pipeline中生成OpenAPI定义的DotNet命令错误？

问题概述 #

Azure Pipeline中Generate OpenAPI definition for ${{ parameters.DocumentName }}步骤执行失败，DotNet命令返回非零退出码，提示未识别到任何项目，核心表现为命令解析异常，无法正确读取指定的Swagger文档。

错误详情 #

执行的命令及报错信息如下：

C:\hostedtoolcache\windows\dotnet\dotnet.exe swagger tofile --output D:\a\1\s\openapi_specs\swagger.json D:\a\1\s\unzipped_artifact\Returns.API.dll Returns API
Usage: dotnet swagger tofile [options] [startupassembly] [swaggerdoc]

startupassembly:
  relative path to the application's startup assembly

swaggerdoc:
  name of the swagger doc you want to retrieve, as configured in your startup class

options:
  --output:  relative path where the Swagger will be output, defaults to stdout
  --host:  a specific host to include in the Swagger output
  --basepath:  a specific basePath to include in the Swagger output
  --serializeasv2:  output Swagger in the V2 format rather than V3
  --yaml:  exports swagger in a yaml format

##[error]Error: The process 'C:\hostedtoolcache\windows\dotnet\dotnet.exe' failed with exit code 1
##[error]Dotnet command failed with non-zero exit code on the following projects : [ '' ]

错误原因分析 #

1. 带空格的文档名称未转义：执行命令中swaggerdoc参数为Returns API，空格导致命令解析错误——系统将空格后的API识别为额外参数，而非swaggerdoc的一部分，无法匹配到指定的Swagger文档。
2. API启动DLL可能获取错误：PowerShell脚本仅通过*.exe过滤获取DLL名称，若解压目录存在多个exe文件，可能误选非目标API的文件。
3. Swagger CLI版本不匹配：安装的Swagger CLI版本与项目中Swashbuckle.AspNetCore的版本存在差异，导致无法正确识别项目中的Swagger配置。

修复步骤 #

1. 转义带空格的DocumentName参数 #

修改Generate OpenAPI definition步骤的arguments，用双引号包裹${{ parameters.DocumentName }}，确保带空格的名称被正确解析：

- task: DotNetCoreCLI@2
  displayName: 'Generate OpenAPI definition for ${{ parameters.DocumentName }}'
  inputs:
    command: 'custom'
    custom: 'swagger'
    arguments: 'tofile --output $(System.DefaultWorkingDirectory)\openapi_specs\${{ parameters.ApiFileName }} $(System.DefaultWorkingDirectory)\unzipped_artifact\$(ApiStartupName) "${{ parameters.DocumentName }}"'

2. 确保获取正确的API启动DLL #

更新PowerShell脚本，添加过滤逻辑确保只获取目标Web API的exe对应的DLL：

- task: PowerShell@2
  displayName: 'Setup CLI tool and variables'
  inputs:
    targetType: 'inline'
    script: |
        mkdir $(System.DefaultWorkingDirectory)\openapi_specs\
        $swaggerDllPath = "$(System.DefaultWorkingDirectory)\unzipped_artifact\Swashbuckle.AspNetCore.Swagger.dll"
        if (-not (Test-Path $swaggerDllPath)) {
            throw "Swashbuckle.AspNetCore.Swagger.dll not found in unzipped artifact!"
        }
        $version = (Get-Item $swaggerDllPath).VersionInfo.FileVersionRaw
        $versionstring = "{0}.{1}.{2}" -f $version.Major,$version.Minor,$version.Build
        
        # 过滤获取目标API的exe文件
        $exeFile = Get-ChildItem -Path $(System.DefaultWorkingDirectory)\unzipped_artifact\ -Filter *.exe | Where-Object { $_.BaseName -match "API" } | Select-Object -First 1
        if (-not $exeFile) {
            throw "No API executable found in unzipped artifact directory"
        }
        $exeName = $exeFile.BaseName + ".dll"
        
        Write-Host "##vso[task.setvariable variable=SwaggerToolVersion;]$versionstring"
        Write-Host "##vso[task.setvariable variable=ApiStartupName;]$exeName"
        Write-Host "Setting tool version to found Swashbuckle.AspNetCore.Swagger version '$versionstring' and API startup DLL to '$exeName'"

3. 验证文件路径与权限 #

添加验证步骤，确认解压后的文件存在且路径正确：

- task: PowerShell@2
  displayName: 'Verify Artifact Files'
  inputs:
    targetType: 'inline'
    script: |
        Write-Host "Unzipped artifact contents:"
        Get-ChildItem -Path $(System.DefaultWorkingDirectory)\unzipped_artifact\
        
        $apiDllPath = "$(System.DefaultWorkingDirectory)\unzipped_artifact\$(ApiStartupName)"
        Write-Host "Checking API DLL path: $apiDllPath"
        if (-not (Test-Path $apiDllPath)) {
            throw "API startup DLL not found at specified path!"
        }

4. 确保Swagger CLI版本完全匹配 #

若项目中使用带补丁号的Swashbuckle.AspNetCore版本（如6.4.0.1），需修改PowerShell脚本完整获取版本号：

$versionstring = "{0}.{1}.{2}.{3}" -f $version.Major,$version.Minor,$version.Build,$version.Revision

验证方法 #

修改Pipeline后重新运行，检查Generate OpenAPI definition步骤是否成功生成swagger.json文件，并确认后续的Copy和发布步骤正常执行。

内容的提问来源于stack exchange，提问作者Bhav