functions/Install-DotNetTool.ps1
|
# <copyright file="Install-DotNetTool.ps1" company="Endjin Limited"> # Copyright (c) Endjin Limited. All rights reserved. # </copyright> function Install-DotNetTool { <# .SYNOPSIS Simple wrapper to install a .NET global tool if it is not already installed. .DESCRIPTION Simple wrapper to install a .NET Global Tool if it is not already installed. Any existing installed version will be uninstalled before installing the required version. .PARAMETER Name The name of the .NET global tool to install. .PARAMETER Version The version of the global tool to install. When unspecified the latest version will attempted to used, however, this does not work for all scenarios (e.g. pre-release, when not using a fully-featured NuGet feed as a source). .PARAMETER AdditionalArgs An array of arbitrary command-line arguments supported by 'dotnet tool install' command. .PARAMETER Global When specified, the tool is installed in the global scope (i.e. for the current user). .PARAMETER Local When specified, the tool is installed in the local scope (i.e. for the current project's .NET tool manifest). .PARAMETER ToolPath When specified, the tool is installed in the specified directory. .OUTPUTS System.String .EXAMPLE ```powershell Install-DotNetTool -Global -Name dotnet-gitversion ``` .EXAMPLE ```powershell Install-DotNetTool -ToolPath ./tools -Name dotnet-gitversion -Version 5.6.6 ``` #> [CmdletBinding(DefaultParameterSetName="global")] [OutputType([String])] param ( [Parameter(Mandatory=$true, Position=0)] [string] $Name, [Parameter()] [string] $Version, [Parameter()] [string[]] $AdditionalArgs = @(), [Parameter(ParameterSetName="global")] [switch] $Global, [Parameter(ParameterSetName="local")] [switch] $Local, [Parameter(ParameterSetName="toolpath")] [string] $ToolPath ) # Remove AdditionArgs from the bound parameters so we can splat the Test-DotNetTool call $PSBoundParameters.Remove("AdditionalArgs") | Out-Null $alreadyInstalled = Get-DotNetTool @PSBoundParameters # Translate the current parameter set to the relevant 'dotnet tool' cli argument switch ($PSCmdlet.ParameterSetName) { "global" { $scopeArg = @("--global") } "local" { $scopeArg = @("--local") } "toolpath" { $scopeArg = @("--tool-path", $ToolPath) } } # Uninstall an existing version of the tool if it's the wrong version if ($alreadyInstalled -and $Version -and $alreadyInstalled.version -ne $Version) { Write-Host "Uninstalling existing version: $($alreadyInstalled.version)" _runDotNetToolUninstall @scopeArg $Name if ($LASTEXITCODE -ne 0) { throw "'dotnet tool uninstall' returned a non-zero exit code ($LASTEXITCODE) - check previous output" } # Ensure the required version is installed below $alreadyInstalled = $false } # Install the tool, if necessary if (!$alreadyInstalled) { if ($Version) { $AdditionalArgs += @( "--version" $Version ) } # Remove any 'scope' references that may have been unnecessarily supplied via AdditionalArgs $AdditionalArgs = $AdditionalArgs | Where-Object { $_ -notin @("-g","--global","-l","--local","-t","--tool-path") } Write-Verbose "cmdline: & dotnet tool install $($scopeArg -join " ") $Name $AdditionalArgs" _runDotNetToolInstall @scopeArg $Name @AdditionalArgs if ($LASTEXITCODE -ne 0) { throw "'dotnet tool install' returned a non-zero exit code ($LASTEXITCODE) - check previous output" } } # Ensure .NET global tools are available via the PATH environment variable, if only for the current process if ($PSCmdlet.ParameterSetName -eq "global") { $toolsPath = Join-Path $HOME ".dotnet/tools" if ($toolsPath -notin ($env:PATH -split [IO.Path]::PathSeparator)) { $env:PATH = "{0}{1}{2}" -f $env:PATH, [IO.Path]::PathSeparator, $toolsPath } } } # Internal wrapper functions to enable mocking in tests function _runDotNetToolInstall { [CmdletBinding()] param ( [Parameter(ValueFromRemainingArguments)] $cmdArgs ) & dotnet tool install @cmdArgs } function _runDotNetToolUninstall { [CmdletBinding()] param ( [Parameter(ValueFromRemainingArguments)] $cmdArgs ) & dotnet tool uninstall @cmdArgs } |