Command Invoke DscRunner

Invoke-DscRunner

Synopsis

Provider-agnostic entry point for the DSC pipeline runner.

Description

Invoke-DscRunner drives the runner without any hard dependency on Azure DevOps. It composes three loader-driven lifecycle actions (see Invoke-Action):

1. Source — resolve the configuration to a local directory (Local, Git, or a custom drop-in / inline scriptblock).
2. Connect — establish any auth/session before evaluation (None by default, AzureDevOps, or a custom drop-in / inline scriptblock).
3. Compile Datum and run Start-DscRunner over each compiled configuration file.

Every seam is selectable by name (a file under Actions//) or overridden with an inline [scriptblock], so third parties can plug in bespoke sources and auth providers without forking the module.

Parameters

Name	Type	Required	Description
Source	String	No	Name of the Source action (a file under Actions/Source/). Default: 'Local'.
SourceAction	ScriptBlock	No	Inline Source action scriptblock. Takes precedence over -Source.
SourceContext	Hashtable	No	Hashtable passed to the Source action (for example @{ Url = ... } for Git or @{ Path = ... } for Local). If -ConfigurationSourcePath is supplied it is merged in as the 'Path' (and, for Git, 'Url') key.
ConfigurationSourcePath	String	No	Convenience: a local directory or git URL. Populates the Source context.
ConfigurationRevision	String	No	Convenience: the branch, tag, or commit to pin a remote configuration to. Populates the Source context's 'Revision' key, which the Git source action passes to Clone-Repository. Supplying a full 40-character commit SHA makes the pin exact - the clone's HEAD is verified against it. Ignored by source actions that do not clone.
Connect	String	No	Name of the Connect action (a file under Actions/Connect/). Default: 'None'.
ConnectAction	ScriptBlock	No	Inline Connect action scriptblock. Takes precedence over -Connect.
ConnectContext	Hashtable	No	Hashtable passed to the Connect action.
CacheDirectory	String	No	Directory Datum compiles into. When omitted, the generic PIPELINERUNNER_CACHE_DIRECTORY environment variable is used (with AZDODSC_CACHE_DIRECTORY honoured as a back-compat alias); failing that, a new temporary directory is created. Replaces the old AZDODSC_CACHE_DIRECTORY hard requirement.
Mode	String	No	'Test' (default) or 'Set'.
ReportPath	String	No	Optional directory to write the per-configuration CSV report into.
Engine	String	No	Name of the execution engine action (a file under Actions/Engine/). 'DscV2' (default) wraps Invoke-DscResource; 'DscV3' drives dsc.exe. 'Auto' opts in to detection, choosing DscV3 when the dsc executable is present (or the version hint asks for it) and DscV2 otherwise. When -Engine is not passed explicitly, the configuration's PipelineRunnerSettings drive selection: an 'Engine' key names the engine, otherwise the back-compat 'DSCResourceVersion' major version maps (2.x -> DscV2, 3.x -> DscV3).
EngineVersion	String	No	Optional resource version hint used to bias 'Auto' engine selection by major version (major >= 3 selects DscV3, major 2 selects DscV2). Ignored unless -Engine is 'Auto'.
EngineAction	ScriptBlock	No	Inline engine scriptblock. Takes precedence over -Engine.
FailOnError	SwitchParameter	No	Undocumented.
KeepTemporaryDirectory	SwitchParameter	No	Leave any temporary directory the runner created (a clone, or a fallback cache directory) on disk after the run instead of deleting it. Useful when debugging a compile failure. Directories supplied by the caller are never deleted, with or without this switch.

Examples

Example 1

Invoke-DscRunner -ConfigurationSourcePath 'C:\config' -Mode Test
Runs against a local directory with no authentication (Source: Local, Connect: None).

Example 2

Invoke-DscRunner -Source Git -SourceContext @{ Url = $repo; Token = $pat } `
                 -Connect AzureDevOps -ConnectContext @{ OrganizationName = 'MyOrg'; AuthenticationType = 'PAT'; PATToken = $pat }

Example 3

Invoke-DscRunner -ConfigurationSourcePath 'C:\config' -ConnectAction {
    param($Context) Connect-MyPlatform -Token $Context.Token
}