文档首页/ 编译构建 CodeArts Build/ 用户指南/ 配置构建任务/ 配置构建步骤/ 使用Msbuild构建
更新时间：2024-08-22 GMT+08:00
查看PDF
分享

使用Msbuild构建

编译构建服务提供了常用的构建模板（构建环境），不同的构建模板中预装了对应构建所需工具集，MSBuild构建镜像一般预装了msbuild、nuget、.NET Framework等常用工具。

使用msbuild构建工具执行引擎、构造工程，支持.NET框架构建，包含.NET Core和.NET Frameworks。

  • Msbuild构建仅支持图形化构建。
  • Msbuild构建仅可单独使用，如果构建任务中已有其他构建步骤，将无法添加“Msbuild构建”。

Msbuild构建场景

表1 已支持的场景

场景类型

说明

无外部依赖

参考镜像版本及对应工具版本，对于仅使用了环境预装依赖库的项目，选择合适的镜像版本即可直接使用msbuild或.NET命令进行构建。

例如：项目使用了dotnetframework4.7.2的SDK和Office操作的相关官方依赖库（MSOffice）。可选用“msbuild15-dotnetframework4.7.2”版本镜像，使用msbuild命令构建。

使用Nuget进行依赖管理

对于使用了环境预装依赖库以外的项目，但使用了Nuget对所有依赖库进行管理的项目，选择合适的镜像版本后，可先使用nuget restore命令下载所有依赖，此后使用msbuild命令进行构建。.NET命令无需先执行nuget命令。

例如：项目使用了“dotnetframework4.7.2”的SDK，依赖了Myget上某Package并使用Nuget添加了该依赖。可选用“msbuild15-dotnetframework4.7.2”版本镜像，使用nuget restore && msbuild命令构建。

其他

对于有其他命令需求的项目，如Git、JDK、Nant、Nodejs等，使用对应的命令进行操作。
表2 未支持的场景

场景类型

说明

未使用Nuget管理依赖库

依赖了本地安装的依赖库，且没有使用nuget对依赖进行管理。详细解决方案请参见找不到程序集（**.dll）。

例如：某项目使用“dotnetframework4.7.2”的SDK，本地安装了Nunit依赖库，但没有使用Nuget对其进行管理。

此时使用msbuild命令对其进行构建时会出现找不到库的错误，导致构建失败。

解决方案版本低于VS2015（不包含）

对于使用VS2015（不含）以前版本创建的解决方案，会出现版本过低不兼容的情况，导致构建失败。请尝试升级解决方案。

约束与限制

为方便使用，CodeArts Build提供的Msbuild构建环境原则上尽可能保持与本地环境一致，但因Windows系统与CodeArts Build本身一些系统限制，少数场景下可能会导致构建失败。使用前建议仔细阅读以下规格说明。

  • 不支持带空格的文件路径

    C#项目中目录或文件名中包含空格会导致构建失败，目录/文件的命名请使用字母、数字、下划线的组合，勿使用其他特殊字符，避免不必要的构建失败。

  • 文件全路径长度不得超过260个字符
    • Windows系统中，文件全路径的最大长度限制为260个字符，超过此长度会导致Msbuild构建失败。
    • CodeArts Build需在指定目录下执行命令，即您的构建场景实际与以下步骤类似： 
      cd C:\编译构建的默认路径\您的项目路径
msbuild
      • 项目文件全路径长度实际为项目下文件相对路径长度与编译构建服务默认路径长度之和。
      • 编译构建服务默认路径长度为45字符。因此，在使用Msbuild构建的过程中，您的项目文件路径需满足：项目下文件相对路径（以代码仓库为根目录）长度不可大于215字符。
      • 一些特殊场景（如构建时指定输出目录为“Output/release”)下，可能会额外占用路径长度。

        建议您的项目下文件相对路径（以代码仓库为根目录）长度保持在200个字符以下，原则上尽可能短。

  • 不可直接引用系统不具备的组件

    部分场景下，解决方案中可能不使用NuGet等管理工具，直接引用默认路径下的程序集。但构建时环境中不具备此程序集，导致编译告警，如果项目代码中使用了此引用，甚至会直接导致失败。

    由于Windows系统特殊性，通常情况下，此类程序集默认安装于本地系统，无需指定程序集位置，VS构建时会从默认配置的几个程序集路径查找，可以构建成功。而云端构建环境对应目录无此程序集，进而导致云端构建环境与本地不一致带来的失败。

    为解决此类场景，Msbuild集成了NuGet，可以在构建时从远程仓库下载对应程序集，此时只需于项目中指定“packages.config”，并于其中声明依赖的程序集即可。

    特殊情况下，项目引用的程序集可能无法在远程仓库找到，此时需要手工保存程序集至代码仓库中，并显式指定程序集路径。

    详细解决方案请参见找不到程序集（**.dll）。

  • 命令行中路径分隔符使用'/'而非'\'

    部分场景下，可能需要在命令行中使用路径参数，此处需注意，Msbuild构建环境要求路径分隔符统一使用“／”格式。

    错误示例：

    cd test\test1或cd test\\test1

    正确示例：

    cd test/test1
  • 避免直接指定低版本SDK路径
    • CodeArts Build提供了“.NET Framework”的4.7.2版本和3.5版本。

      CodeArts Build支持的工具版本，可查看构建工具版本。若当前的工具版本不满足您的使用要求，您可以自定义构建环境。

      一般来讲，4.7.2版本可以兼容4.0以上版本SDK，3.5版本可以兼容3.5版本以下SDK，项目中可以引用兼容版本的SDK内容。

    • 在某些场景下，用户可能将引用直接指向了某个低版本的SDK路径，此时会因找不到SDK导致构建失败。

      如果您的项目出现此类场景，建议：

      • 尝试更改您的引用路径，尽可能使用兼容版本SDK。
      • 如果您的项目因为不可回避的原因，必须指向低版本SDK路径，请联系客服。

图形化构建

在配置构建步骤中，添加“Msbuild构建”构建步骤，参考表3配置参数。

表3 Msbuild构建参数说明

参数

说明

步骤显示名称

构建步骤的名称，可自定义修改。

  • 支持中文、英文、数字、“-”、“_”、英文逗号、英文分号、英文冒号、“.”、“/”、圆括号（中英文）。
  • 字符长度范围为1~128。

工具版本

根据用户实际开发环境的需要，选择对应的工具版本。

CodeArts Build支持的工具版本，可查看构建工具版本。若当前的工具版本不满足您的使用要求，您可以自定义构建环境。

powershell命令

配置Msbuild命令，一般使用系统默认给出的命令即可。常见命令可参考常用Powershell命令。

  • nuget restore命令会还原csharp项目依赖。
  • msbuild命令构建项目：
    • OutputPath会指定生成路径，此路径设置会以csproject文件为相对路径。
    • 项目存在多个csproject时可能会因此导致构建失败，删除路径指定参数后可构建成功。
  • .NET Core项目请尝试使用.NET相关命令构建。

常用Powershell命令

如果在构建任务中使用powershell命令，在命令行窗口按如下格式输入命令即可。

powershell –Command Powershell命令 Powershell命令参数列表
表4 常用Powershell命令

Powershell命令

命令使用说明

Compress-Archive（压缩命令）

 
powershell –Command Compress-Archive -Path [SourcePath] -DestinationPath [Target.zip]
  • SourcePath：指定需要压缩的文件或文件夹，支持通配符和相对路径。
  • Target.zip：输出的压缩文件名，可用于上传到软件发布库时填写文件名。

Expand-Archive（解压缩命令）

 
powershell –Command Expand-Archive -Path [SourcePath] -DestinationPath [TargetPath]
  • SourcePath：指定需要解压的文件，如“demo.zip”。
  • TargetPath：要解压到的目标路径，支持通配符和相对路径。

Copy-Item（复制命令）

 
powershell –Command Copy-Item -Recurse -Path [SourcePath] -DestinationPath [TargetPath]
  • SourcePath：指定需要复制的文件或文件夹，支持通配符和相对路径。
  • TargetPath：要复制到的目标路径，支持通配符和相对路径。
说明：

-Recurse选项为循环复制子文件夹，但若在SourcePath中使用了通配符，此开关会失效，不会复制指定目录下的子文件夹。

文档只介绍了构建常用的Powershell命令，更多Powershell命令请参见官方文档。

父主题： 配置构建步骤

相关文档