After building the project it would be nice if we could inspect the resulting project file. To facilitate this let's add a -debugMode switch to Invoke-MSBuild that will use the MSBuild APIs to invoke the build and then return the build result as well as resulting ProjectInstance.

Since we will be calling the APIs instead of the command line we may not be able to understand all the properties but known ones should be passed in.

Tasks

• Add -debugMode switch
• Pass in properties during build
• Pass in targets during build
• Attach console logger
• Attach file loggers
• Pass in max node count
• Ability to set toolsversion
• Create a parameter set on Invoke-MSBuild
• Create helper functions (Eval-Property/Eval-Item/Expand-String) that act on the last build result
• Add evaluation functions to simplify
• Eval-Property
• Eval-Item
• Eval-String

We should create a nuget package which can be used by other nuget packages to manipulate msbuild files.

I currently have some PS functions like this:

Function Build { &'msbuild' /nologo /v:q }
Function Clean { &'msbuild' /t:Clean /nologo /v:q }

I was going to replace them with PSBuild; but it doesn't currently work without passing a project. With my functions, I can just type "build" in the root of my repo (which generally has a single .sln file), but PSBuild doesn't support this.

PSBuild should support the same; if I call Invoke-MSBuild with no project, call MSBuild anyway, and let it decide what to do.

We should add a function (and perhaps a param on Invoke-MSBuild) to import VS variables. You can see how to do that at https://github.com/cliffburger/posh-msbuild/blob/master/posh-msbuild.psm1#L62. The only issue with that is that it requires VS to be installed, a portable version of that would be better.

We should add a parameter to Invoke-MSBuild for /m.

Better Support for NuGet / Pkg Mgr Console

We can have a better story around NuGet and the package manager console using psbuild. The following are some user statements.

• As a nuget pkg author I can use psbuild to make it easier to manipulate MSBuild files. I can simply place a dependency on the psbuild nuget package then I can call the commands it makes available in my install.ps1/init.ps1.
• As a dev I can use psbuild to make it easier to call msbuild from the pkg mgr console. Perhaps after installing the package we can automatically (or with an explicit command) install the module to the users machine and NuGet profile. That way they don't have to keep installing the nuget package if they don't want to. If the user has already installed psbuild as a module in his PS env. ideally that automatically lights up in the pkg manager console.
• As a dev I can use psbuild from the pkg manager console to make it easier to interact with MSBuild files. I can create new msbuild files with a command, I can edit MSBuild files, etc.

When Invoke-MSBuild is called with -debugMode we should keep the last build result. When Invoke-MSBuild is called again (with or without -debugMode) we should re-set that value to either the new result or null.

After we save this value we can create the following cmdlets. These would be an alternative to assigning the result to a var and accessing via instance methods.

cmdlets / adv functions to create

• Eval-MSBuildProp
• Eval-MSBuildItem
• Expand-MSBuildString
• Get-MSBuildItems
• Set-MSBuildProperty
• Remove-MSBuildProperty
• Remove-MSBuildItem
• Save-MSBuildProject

Note: We should ensure that these are not confused with the existing "construction" related advanced functions.

We should be able to pipe the project to these cmdlets as well. Using the last build result should be the default.

We should add a parameter to Invoke-MSBuild for /preprocess. This could be helpful when working on MSBuild script inside of VS.

We should add a parameter to Get-MSBuild which can be used to control the bitness of the version that is returned. The default should be 32 bit.

We should add psbuild to psget so that users can easily acquire psbuild.

For the CLP parameter we should pass in the property ShowCommandLine

If I specify
Invoke-MSBuild $slnFile -msbuildPath $msbuildPath -properties $msbuildProperties -Verbose

I should not see the following warning in my console, especially not in a different color:

Using msbuild.exe from [C:\Program Files (x86)\MSBuild\12.0\bin\amd64\msbuild.exe]. Use Set-MSBuild to change this.

When Invoke-MSBuild is called with the -debugMode flag at the end of the build we should save the resulting ProjectInstance to a file. We can use the log folder as the location to persist that file. We should perhaps have an options/parameter for that.

After persisting this to disk we should also keep track of this path in the buildResult object which is saved for later use.

Then we can create the following cmdlets / advanced functions

• Get-PSBuildPostBuildResult (or something along those lines). The idea is that we would return the path to the .csproj file that contains the final "view" that MSBuild had for the project file. This would be really helpful for debugging.

This can be achieved with $projectInstance.ToProjectRootElement().Save('<path>')

Configuration can be set with a direct command-line parameter rather than through properties, presumably because it is in all sln/csproj files and usually needs to be specified for msbuild.

By the same logic, there should be such a Platform variable as well.

We should add the following properties as parameters

• OutputPath
• DeployOnBuild
• PublishProfile
• Password

We should add a new function Update-Psbuild which will just executes the install instructions from https://github.com/ligershark/psbuild/.

Default to /m

When authoring msbuild files you often need to escape special characters. It'd be helpful to have a function,Get-MSBuildEscapeCharacters, that can be called to show the common escape characters.

When Invoke-MSBuild is called with the -debugMode flag we return the resulting ProjectInstance object. Users can use that object to then execute specific build targets. We could do the following to help here.

• Add a function on the build result object to call build
• Add a parameter to Invoke-MSBuild to accept a ProjectInstance (available only under -debugMode parameter set)

We should add a parameter to Invoke-MSBuild for /nologo.

I don't like having to use a browser to search for the exact name of reserved properties. We should create a function to display the reserved properties and their values for a dummy project.

When invoking Open-PSbuildLog you get an error related to indexing an empty array.

On the Inovke-MSBuild function we should enable the -whatif switch.

We should add the ability to turn off logging, both globally and for a single invocation of Invoke-MSBuild.

• Add a switch -noLogFiles parameter to Invoke-MSBuild to avoid logging
• Add a setting which turns logging off globally

Invoking a sample console application .sln file using Invoke-MSBuild throws an error but compiles the project successfully and produces valid .exe.

Invoke-MSBuild .\ConsoleApplication.sln

Exception calling "Open" with "2" argument(s): "The project file could not be loaded. Data at the root level is
invalid. Line 2, position 1.  C:\.\ConsoleApplication.sln"
At C:\..\Modules\psbuild\psbuild.psm1:870 char:13
+             $project = ([Microsoft.Build.Construction.ProjectRootElement]::Open( ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : InvalidProjectFileException

We should add a parameter for Configuration on Invoke-MSBuild

We should update the non-beta release on nuget, and unlist 0.0.1

When psbuild is installed we should add it to the nuget profile as well that way a VS user can easily use this from the package manager console.

Since I was just learning appveyor I configured the build in the website directly. Now that I have everything configured I will move the config into appveyor.yml so that it's versioned with the code.

The user may have a few different intentions when calling Invoke-MSBuild.

1. Build a file
2. Build a file with -debugMode
3. -preprocess

Each of these are mutually exclusive. We should add some parameter sets to Invoke-MSBuild to reflect this. The default parameter set should be Build a file.

We should update build.ps1 so that it can publish to nuget.org. We should also update the CI build to publish to nuget.org whenever the release branched has a new set of changes.

Suppose the following:

 Invoke-MSBuild $slnFile -properties $msbuildProperties -Verbose -nologfiles

After the build, I see

  >>>> Build completed you can use Open-PSBuildLog to open the log file

It should just say

  >>>> Build completed 

We should add a parameter to Invoke-MSBuild for /version.

We should add support for generating a log that is written in markdown. Along with this change we should do a few more things, they are listed below.

• Create a new markdown logger and update psbuild to use that
• Improve how logs are written out. Today we create a detailed and a diagnostic log and its index based which one it is. Instead we should have named logs, and update Open-PSBiuldLog to have switches for which log should be opened.
• Update acquisition experience to pull from nuget.org. Right now the GetPsBuild.ps1 script pulls from github. It would be better if this pulled from nuget.org instead. This will allow give us a lot of benefits like; versioning, easier testing, and some other stuff.
• Update Open-PSBuildLog to support a switch for which type of log should be opened

Get-PSBuildLog returns one or more .log file and Open-PSBuildLog file opens the last .log file. One has to type two commands to open the log file. Can we have Open-PSBuildLog cmdlet accept pipeline object from Get-PSBuildLog.

Get-PSBuildLog | Open-PSBuildLog

With parameter defaults we can directly open the first log file just like it works right now.

The test cases are no longer current and are failing. We should make the following changes.

• Update test cases so that they all pass
• Update build.ps1 to execute the test cases
• Update the CI build to execute test cases and fail if there is an error

When invoking msbuild.exe you can pass in parameters on the command line. These parameters are _overriding_ standard property declarations in the project file. In some cases it would be nice to be able to set the _default value_ for a property, i.e. the value that should be used if no other value has been specified. Since msbuild.exe doesn't support this we will have to build it ourselves.

User Experience

We should add a new parameter to the Invoke-MSBuild function that allows the user to pass in these properties. This property should be named defaultProperties.

Design

MSBuild doesn't have the concept of default properties but when MSBuild encounters a declaration like $(PropName) if the property has not been declared MSBuild will fall back to returning the value of an env var with the same name if it exists. We can exploit this behavior to implement default properties. Inside of Invoke-MSBuild before we call msbuild.exe we can set the default properties as env variables. If there is any clean up needed we can do that after msbuild.exe returns.

Open Items

• If we set the properties as PS env vars will msbuild.exe be smart enough to pick those up?

please how to write :
msbuild MyProject.csproj /p:Configuration=Release /p:DeployOnBuild=true /p:PublishProfile=WMyProject

We should make sure that the CI server executes the PowerShell test cases under the tests\ folder. We should wait for #38 to be completed. In addition to this we should update build.ps1 to execute the PS test cases. Perhaps we can add a parameter(s) to build.ps1 that just executes the test cases. That way we can use that both locally as well as in CI.

Having all three loggers always write to disk can slow a build considerably.

I've used the functions below on several projects where psbuild is used. It would be easier to add this to the psbuild.psm1 directly.

Note: we should investigate if the names of the functions below are what we want to use

function Filter-String{
[cmdletbinding()]
    param(
        [Parameter(Position=0,Mandatory=$true,ValueFromPipeline=$true)]
        [string[]]$message
    )
    process{
        foreach($msg in $message){
            if($nugetApiKey){
                $msg = $msg.Replace($nugetApiKey,'REMOVED-FROM-LOG')
            }

            $msg
        }
    }
}

function Write-Message{
    [cmdletbinding()]
    param(
        [Parameter(Position=0,Mandatory=$true,ValueFromPipeline=$true)]
        [string[]]$message
    )
    process{
        Filter-String -message $message | Write-Verbose
    }
}

<#
.SYNOPSIS
    If nuget is in the tools
    folder then it will be downloaded there.
#>
function Get-Nuget{
    [cmdletbinding()]
    param(
        $toolsDir = ("$env:LOCALAPPDATA\LigerShark\tools\"),
        $nugetDownloadUrl = 'http://nuget.org/nuget.exe'
    )
    process{
        $nugetDestPath = Join-Path -Path $toolsDir -ChildPath nuget.exe

        if(!(Test-Path $nugetDestPath)){
            $nugetDir = ([System.IO.Path]::GetDirectoryName($nugetDestPath))
            if(!(Test-Path $nugetDir)){
                New-Item -Path $nugetDir -ItemType Directory | Out-Null
            }

            'Downloading nuget.exe' | Write-Message
            (New-Object System.Net.WebClient).DownloadFile($nugetDownloadUrl, $nugetDestPath)

            # double check that is was written to disk
            if(!(Test-Path $nugetDestPath)){
                throw 'unable to download nuget'
            }
        }

        # return the path of the file
        $nugetDestPath
    }
}

We should add a parameter to Invoke-MSBuild for /detailedsummary.

Add VisualStudioVersion parameter

Add Open-PSBuildLog which can be used to open the last log file in the default system editor.

Add Configuration parameter to Invoke-MSBuild. When passed in we should just convert it to an MSBuild property to msbuild.exe.

Add support for /clp to Invoke-MSBuild. It should default to values which are best practices.

If the build fails we should throw an exception so that the rest of the process after the build can stop.

$svnToolFolder = "C:\Program Files\TortoiseSVN\bin\"
$msbuildProperties = @{'SVNToolFolder'=$svnToolFolder;}
Invoke-MSBuild $slnFile -properties $msbuildProperties

As the point of the hashtable is to abstract away the command line, $svnToolFolder should automatically handle arguments with spaces. But this is what I see:

VERBOSE: Performing the operation "Invoke-MSBuild" on target "
msbuild.exe ..\Solutions\MySoliton.sln /p:SVNToolFolder=C:\Program Files\TortoiseSVN\bin\ [...]

We should add a function Import-Pester which will download pester from nuget and load the module. This will make it easier to avoid placing pester in repositories.

See the changes aspnet/vsweb-publish@566f311#diff-f0e02e42e53ec40f5d3b8bed031ad09e

When building with psbuild you should get a better experience when using appveyor. For example.

• Add appveyor msbuild logger
• Build logs should be uploaded as build artifacts (off by default because it may contain sensitive data)
• Write an appveyor message for each call to Invoke-MSBuild