en-US/about_Whiskey_MSBuild_Task.help.txt
|
TOPIC
about_Whiskey_MSBuild_Task SUMMARY Runs msbuild.exe, the Microsoft Build tool. DESCRIPTION The MSBuild task runs the "build" target against one or more files, specified with the `Path` property. (In clean mode, it runs the "clean" target instead.) These files must be in formats that MSBuild recognizes (e.g. *.sln, *.csproj, etc.). You can change what build targets to run using the `Target` property. When run by a developers, this task builds using Debug configuration. When run by a build server, it builds using Release configuration. For each solution file in the `Path` property (i.e. a file whose extension is .sln), the MSBuild task will restore that solutions's NuGet packages before the build begins, i.e. it runs `nuget.exe restore PATH_TO.sln`. When run on the build server, the MSBuild task adds the current version being built to all AsssemblyInfo.cs files in or under the same directory as the file being built. Specifically, these assembly attributes are addded: [assembly: System.Reflection.AssemblyVersion("VERSION_NUMBER")] [assembly: System.Reflection.AssemblyFileVersion("VERSION_NUMBER")] [assembly: System.Reflection.AssemblyInformationalVersion("VERSION_NUMBER+BUILD_METADATA")] If an AssemblyInfo.cs file already has one of these attributes, the existing attribute is replaced. Build metadata is added to the end of the version in the AssemblyInformationalVersion attribute's value. The build fails if msbuild.exe returns a non-zero exit code. The MSBuild task looks up installed versions of MSBuild in the "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions' registry key. For each key it finds, it uses the "MSBuildToolsPath" property to locate that version's MSBuild.exe executable. Versions of MSBuild that ship with Visual Studio 2017 and later don't appear in the registry, so the MSBuild task also uses the `Get-VSSetupInstance` function in the VSSetup PowerShell module to find installed instances of Visual Studio 2017 (and later). The task looks for versions of MSBuild in the "MSBuild" directory under each Visual Studio instance's installation path. Under each version, it looks for 64-bit MSBuild.exe at "Bin\amd64\MSBuild.exe" and 32-bit MSBuild.exe at "Bin\MSBuild.exe". A detailed log of the build is saved to the build output directory named "msbuild.FILE_NAME.log" file, where `FILE_NAME` is replaced by the name of the file being built. This task downloads and uses the [VSSetup PowerShell module from the PowerShell Gallery](https://www.powershellgallery.com/packages/VSSetup) to detect find versions of MSBuild that ship with Visual Studio 2017 (and later). PROPERTY * `Path` (*mandatory*): A list of one or more paths to files that MSBuild can build. Files are built in the order they appear in this list. Wildcards are permitted. * `Verbosity`: Controls the verbosity level of MSBuild's output. The default is minimal. On build servers, the default is debug. Should be one of quiet, minimal, normal, debug, or diagnostic. * `Property`: A list of additional MSBuild properties to pass to MSBuild, e.g. Disable_CopyWebApplication=True. Must be of the form NAME=VALUE. * `OutputDirectory`: The directory where assemblies should be compiled to. The default is the location specified in each .csproj file. * `CpuCount`: The number of MSBuild processes to use when building. The default is the number of cores/CPUs on the current computer. Setting this to 1 disables parallel builds. * `NoMaxCpuCountArgument`: This disables multi-CPU builds by not passing the /maxcpucount argument to MSBuild. Useful if you're building with versions of MSBuild that don't support /maxcpucount. * `NoFileLogger`: Disables logging debug output to a log file in the output directory. * `Argument`: A list of arguments to pass to msbuild.exe. * `Target`: A list of build targets to run. The default is build. * `Version`: The version of MSBuild to use. By default, uses the most recent/latest version of MSBuild installed. You usually will want to pin this to a specific version. Valid values are 15.0 (Visual Studio 2017), 14.0 (Visual Studio 2015) 12.0 (Visual Studio 2013), 4.0, 3.5, or 2.0. * `NuGetVersion`: The version of NuGet to use to restore packages. The default is to use the latest version. * `Use32Bit`: Set to `true` to use a 32-bit version of MSBuild.exe. The default is to use a version that matches the processor architecture of the current computer. * `VSSetupVersion`: the version of the `VSSetup` PowerShell module to download and use. The default is the latest 2.* version. This module is used to find versions of MSBuild that ship with Visual Studio 2017 (and later). Be careful about changing the version. The task may not support newer/olders versions. EXAMPLES ## Example 1 Build: - MSBuild: Path: MySolution.sln Demonstrates how to use the MSBuild task to build a Visual Studio solution file. |