Skip to content

DEV Public Functions

Jump to bottom
Roman Kuzmin edited this page Nov 24, 2017 · 36 revisions

The engine state and build results ${*}

Build result data

All = [System.Collections.Specialized.OrderedDictionary]([System.StringComparer]::OrdinalIgnoreCase)

All tasks added by the build script except redefined.

Tasks = [System.Collections.Generic.List[object]]@()

Tasks invoked in the build.

Errors = [System.Collections.Generic.List[object]]@()

Errors collected in the build.

Warnings = [System.Collections.Generic.List[object]]@()

Warnings collected in the build.

Redefined = @()

Redefined task objects removed from All.

Doubles = @()

Collected potentially always skipped double referenced tasks #82. They are checked when the build starts.

Started = [DateTime]::Now

Build start time.

Elapsed = $null

Build duration, [timespan].

Error = $null

Null or the build failure error.

Private engine state

Task = $null

Null or the current task.

File

Either a build script path or a script block to be invoked. Added in 3.6.0, #78.

Safe = $PSBoundParameters['Safe']
Summary = $PSBoundParameters['Summary']

Build parameters stored for later. We remove variables, including parameters, to reduce noise.

CD = *Path

The original current location restored in finally.

DP = New-Object System.Management.Automation.RuntimeDefinedParameterDictionary

Dynamic parameters, i.e. all build script parameters.

SP = ${}

Script parameters, [hashtable]. These parameters are sent to the dot-sourced build script. They are specified on invoking the build and used for storing checkpoints by Build-Checkpoint.

P = ...

Null or the parent engine state object. Tasks, errors, and warnings from the current state are appended to the parent in finally.

A = 1

Abort state. 1: build is aborted. 0: build is started.

If A is 1 in finally then the build is aborted before tasks. It is used just in order to print a distinctive ABORTED message. Why not just use B? Because B = 2 in catch and this is not enough to tell ABORTED or FAILED.

B = 0

Build state. 0: build not started. 1: build completed. 2: build failed.

If B is 0 we do not print the header and footer.

Q = 0

Query mode. 0: normal build mode. True: IB is called with ? or ??.

H = @{}

Help synopsis cache used by Get-BuildSynopsis.

EnterBuild = $null
ExitBuild = $null
EnterTask = $null
ExitTask = $null
EnterJob = $null
ExitJob = $null
Header = {Write-Build 11 "Task $($args[0])"}

Build blocks.

Data = @{}

External data set by Set-BuildData. Used by Build-Checkpoint ("Checkpoint.Export", "Checkpoint.Import").

XBuild = $null
XTask = $null

External hooks injected via the parameter Result. XBuild is called after Enter-Build before invoking tasks. XTask is called on invoking each task before evaluating their If.

$BuildRoot, the special variable

Unlike other build variables, this one is supposed to be set in special cases. A user may assign a custom path and it will be maintained current by the engine.

Q: Why do not we have a special function Set-BuildRoot? It might resolve the path to full, check for existence, set it current at once.

A: Because the current way is simple, flexible, and good enough even in older versions. And v3.7.2 normalizes, tests, and makes $BuildRoot constant after loading tasks (#95).

Also, the function may look confusing like something designed for several calls. This is not the case. The build root is either not changed or changed just once.

Add-BuildTask (alias task)

v3.3.8 Before adding the task to the list, check for the existing and move such a task to Redefined in build results. When the build starts, write gray messages about each task in Redefined.

Errors

  • Invalid job - if it not string, scriptblock, or hashtable @{name=1} (only 1 if OK, see tests).

Get-BuildFile

  • $Path: full directory path
  • Output: full file path or null

It is used internally and designed for wrappers.

Plot

# $f = get files like *.build.ps1, array of full paths
# if there is exactly one then return it
if (($f = [System.IO.Directory]::GetFiles($Path, '*.build.ps1')).Length -eq 1) {return $f}

# $_ = find .build.ps1 in $f, array of 1 or 0 items
# if it is found then return it (remember, array is unrolled)
if ($_ = $f -match '[\\/]\.build\.ps1$') {return $_}

# if $f has 2+ items then die
# do this check after normal cases
if ($f.Length -ge 2) {throw "Ambiguous default script in '$Path'."}

# at this point $f is empty, i.e. we did not find a build script
# try to get it by the hook, if any, then move to the parent folder

# $_ = get $env:InvokeBuildGetFile ($null or some)
# if the file $_ exists then it is the hook script, invoke it, return not empty result
if ([System.IO.File]::Exists(($_ = $env:InvokeBuildGetFile)) -and ($_ = & $_ $Path)) {return $_}

# $Path = get the parent directory
# if it is not empty then repeat all, otherwise the function returns nothing
$Path = Split-Path $Path

Get-BuildProperty (alias property)

2017-04-10 v3.3.4

See #60

Interestingly, [Environment]::GetEnvironmentVariable gets null for an existing but empty env var. Anyway, it is fine to check as we do: !($_ = [Environment]::GetEnvironmentVariable($Name)). Null and empty are both treated as undefined.

NB

Replaced $ExecutionContext.SessionState.PSVariable.GetValue($Name) with faster $PSCmdlet.GetVariableValue($Name).

Get-BuildSynopsis gets task synopsis

  • It is used on ib ?
  • It is suitable for making more informative task output.
  • Show-BuildTree.ps1 uses it as well via dot-sourcing IB.

Resolve-MSBuild (Resolve-MSBuild.ps1)

Script functions are used in order to mock on testing.

Use-BuildAlias (alias use)

Get-Item <path>\* is useful but very slow. Get-ChildItem <path> is faster.

Replaced Convert-Path (Resolve-Path -LiteralPath $Path -ErrorAction Stop) with *Path + [System.IO.Directory]::Exists. The old does not work in paths with [ ].

Write-Build

There are two functions with the same name. The first uses $Host.UI to set colors. If it has problems on the trial call then the second is defined to override the first. The second does not use $Host.UI.

NB: The dummy function does not define [ConsoleColor] for $Color because it is not used. It is possible to pass some garbage but without colors it does not matter anyway.

Why try..finally

It is used in order to restore the color on Ctrl-C.

v2.14.3 #21

One function with a helper class [InvokeBuild]. A C# code is used in order quietly catch an exception on setting ForegroundColor and ignore colors on next calls.

Known bad hosts

The Default Host (created by [PowerShell]::Create()) or ServerRemoteHost (background jobs) have UI and RawUI defined. At the same time RawUI throws on setting colors ("not supported"). Weird design. Anyway, the work around is to check for known bad names and use the primitive function for such hosts.

NB: ServerRemoteHost was removed later, not sure about it.

Write-Host (1.2.2) and Write-Warning (1.4.1)

v1.2.2 With 'Default Host' Write-Host is defined as empty, disabled. Do not turn it to a text writer, i.e. do not redefine, this breaks code that returns data and writes some extra info using Write-Host.

NOTE Write-Host dropped.

1.4.1 Ditto about Write-Warning

Write-Warning wraps and extends warnings

function Write-Warning([Parameter()]$Message)

It replaces the native cmdlet and provides the same parameters as the main native parameters. Common native parameters are ignored.

This function extends warning information and makes build analysis easier, either with the build result object or just with the log. When the build is over, collected warnings are printed together with task names and script paths.

When Write-Warning is called the native warning is still written as

$PSCmdlet.WriteWarning($Message)

In addition to this, we collect warning information in the result list. The stored warning object properties

Message = $Message # warning message
File = $BuildFile  # current build file
Task = ${*}.Task   # current build task or null

Helpers

Appendix

Clone this wiki locally