Add init script and more contributing guidance

Fixes #85

Author: AArnott

CONTRIBUTING.md

@@ -14,19 +14,36 @@ All other dependencies are acquired via NuGet.
 
 ## Building
 
-To build this repository from the command line, you must first execute a complete NuGet package restore.
+To build this repository from the command line, you must first execute our init.ps1 script,
+which downloads NuGet 3.3.0 and uses it to restore packages.
 Assuming your working directory is the root directory of this git repo, the command is:
 
-    nuget restore src
-
-You may need to [download NuGet.exe][NuGetClient] first. **Be sure to use nuget.exe 3.3.0** rather than
-3.4.4 or any version in between because these newer versions have regressions that break the build.
+    .\init
 
 Everything in the repo may be built via building the solution file
 either from Visual Studio 2015 or the command line:
 
     msbuild src\ImmutableObjectGraph.sln
 
+### Important notice when developing with Visual Studio
+
+The NuGet package restore functionality in Visual Studio does not work for this project, which relies
+on newer functionality than comes with Visual Studio 2015 Update 3. You should disable automatic
+package restore on build in Visual Studio in order to build successfully and have a useful Error List
+while developing.
+
+Follow these steps to disable automatic package restore in Visual Studio:
+
+1. Tools -> Options -> NuGet Package Manager -> General
+2. *Clear* the checkbox for "Automatically check for missing packages during build in Visual Studio
+
+With this setting, you can still execute a package restore within Visual Studio by right-clicking
+on the _solution_ node in Solution Explorer and clicking "Restore NuGet Packages". But do not ever
+execute that on this project as that will corrupt the result of `init.ps1`.
+
+Before developing this project in Visual Studio, or after making project or project.json changes,
+or to recover after Visual Studio executes a package restore, run the `init` script again.
+
 ## Testing
 
 The Visual Studio 2015 Test Explorer will list and execute all tests.

init.cmd

@@ -0,0 +1 @@
+powershell.exe -ExecutionPolicy bypass -Command "& '%~dpn0.ps1'" %*

init.ps1

@@ -0,0 +1,27 @@
+<#
+.SYNOPSIS
+    Prepares a machine to build and test this project.
+#>
+Param(
+)
+
+Push-Location $PSScriptRoot
+try {
+    $toolsPath = "$PSScriptRoot\tools"
+
+    # First restore NuProj packages since the solution restore depends on NuProj evaluation succeeding.
+    gci "$PSScriptRoot\src\project.json" -rec |? { $_.FullName -imatch 'nuget' } |% {
+        & "$toolsPath\Restore-NuGetPackages.ps1" -Path $_ -Verbosity quiet
+    }
+
+    & "$toolsPath\Restore-NuGetPackages.ps1" -Path "$PSScriptRoot\src" -Verbosity quiet
+
+    Write-Host "Successfully restored all dependencies" -ForegroundColor Green
+}
+catch {
+    Write-Error "Aborting script due to error"
+    exit $lastexitcode
+}
+finally {
+    Pop-Location
+}

tools/Get-NuGetTool.ps1

@@ -0,0 +1,24 @@
+<#
+.SYNOPSIS
+    Downloads the NuGet.exe tool and returns the path to it.
+#>
+
+function Expand-ZIPFile($file, $destination) {
+    if (!(Test-Path $destination)) { $null = mkdir $destination }
+    $shell = new-object -com shell.application
+    $zip = $shell.NameSpace((Resolve-Path $file).Path)
+    foreach ($item in $zip.items()) {
+        $shell.Namespace((Resolve-Path $destination).Path).copyhere($item)
+    }
+}
+
+$binaryToolsPath = "$PSScriptRoot\..\obj\tools"
+if (!(Test-Path $binaryToolsPath)) { $null = mkdir $binaryToolsPath }
+$nugetPath = "$binaryToolsPath\nuget.exe"
+if (!(Test-Path $nugetPath)) {
+    $NuGetVersion = "3.3.0"
+    Write-Host "Downloading nuget.exe $NuGetVersion..." -ForegroundColor Yellow
+    Invoke-WebRequest -Uri "https://dist.nuget.org/win-x86-commandline/v$NuGetVersion/nuget.exe" -OutFile $nugetPath
+}
+
+$nugetPath

tools/Restore-NuGetPackages.ps1

@@ -0,0 +1,21 @@
+<#
+.SYNOPSIS
+    Restores NuGet packages.
+.PARAMETER Path
+    The path of the solution, directory, packages.config or project.json file to restore packages from.
+    If not specified, the current directory is used.
+.PARAMETER Verbosity
+#>
+Param(
+    [Parameter(Position=1)]
+    [string]$Path=(Get-Location),
+    [Parameter()]
+    [ValidateSet('Quiet','Normal','Detailed')]
+    [string]$Verbosity='normal'
+)
+
+$nugetPath = & "$PSScriptRoot\Get-NuGetTool.ps1"
+
+Write-Host "Restoring NuGet packages for $Path" -ForegroundColor Yellow
+& $nugetPath restore $Path -MSBuildVersion 14.0 -Verbosity $Verbosity
+if ($lastexitcode -ne 0) { throw }