更新时间:2023-12-15 GMT+08:00
分享

Msbuild构建

背景信息

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

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

配置说明

配置构建步骤中,添加“Msbuild构建”构建步骤。

参数说明如下:

参数项

说明

步骤显示名称

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

工具版本

请根据需要选择Msbuild构建工具版本。

  • 请选择相应的.NET版本。
  • msbuild15-all版本的工具提供更多的构建支持,如nant、nodejs的构建命令支持等。

powershell命令

配置Msbuild命令,一般使用系统默认给出的命令即可。

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

Msbuild系统规格说明

为方便使用,编译构建服务提供的Msbuild构建环境原则上尽可能保持与本地环境一致,但因Windows系统与编译构建服务本身一些系统限制,少数场景下可能会导致构建失败。

使用前建议仔细阅读以下规格说明。

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

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

  • 文件全路径长度不得超过260个字符
    • Windows系统中,文件全路径的最大长度限制为260个字符,超过此长度会导致Msbuild构建失败。
    • 编译构建服务约定在指定目录下执行命令,即您的构建场景实际与以下步骤类似:
      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路径
    • 编译构建服务提供了“.NET Framework”的4.7.2版本和3.5版本(详细说明请参见已支持的镜像版本及工具集)。

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

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

      如果您的项目出现此类场景,建议:

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

Msbuild构建场景

  • 已支持场景

    场景类型

    说明

    无外部依赖

    参考镜像版本及对应工具版本,对于仅使用了环境预装依赖库的项目,选择合适的镜像版本即可直接使用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等,请参见msbuild15-all版本镜像构建工具集的说明,使用支持的命令进行操作。

  • 未支持场景

    场景类型

    说明

    未使用Nuget管理依赖库

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

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

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

    解决方案版本低于VS2015(不包含)

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

Powershell命令使用

  • Powershell使用操作

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

    powershell –Command 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命令请参见微软官方文档

分享:

    相关文档

    相关产品