en-US/Datum.InvokeCommand-help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-InvokeCommandAction</command:name> <command:verb>Invoke</command:verb> <command:noun>InvokeCommandAction</command:noun> <maml:description> <maml:para>Invokes a Datum handler action that evaluates embedded commands within Datum configuration data.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This function is the primary action handler for the Datum.InvokeCommand module. It is called by the Datum framework when `Test-InvokeCommandFilter` returns `$true` for a given value. The function processes input objects that contain embedded commands wrapped in the configurable header/footer delimiters (default: `[x=` and `=]`).</maml:para> <maml:para>The function supports three types of embedded content: - ScriptBlocks : Code wrapped in curly braces, e.g., `[x={ Get-Date }=]` - Expandable strings : Double-quoted strings with variable expansion, e.g., `[x="$($Node.Name)"=]` - Literal strings : Single-quoted strings (returned as-is with a warning), e.g., `[x='literal'=]`</maml:para> <maml:para>When a Datum value contains an embedded command, the handler extracts the content using the configured regular expression, determines whether it is a script block or expandable string via `Get-ValueKind`, and then invokes or expands it accordingly via `Invoke-InvokeCommandActionInternal`.</maml:para> <maml:para>The function provides access to `$Node`, `$Datum`, and `$File` variables within the embedded commands, enabling dynamic lookups across the Datum hierarchy.</maml:para> <maml:para>Error handling behavior is controlled by the `DatumHandlersThrowOnError` property in the Datum definition. When set to `$true`, errors terminate execution; otherwise, warnings are emitted and the original input value is returned.</maml:para> <maml:para>For more information about Datum and Datum handlers, see https://github.com/gaelcolas/datum/.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-InvokeCommandAction</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The input object containing the embedded command string(s) to evaluate. This parameter accepts pipeline input. The value should contain a string wrapped with the configured header and footer delimiters (default: `[x=` ... `=]`).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Datum</maml:name> <maml:description> <maml:para>The Datum structure (hashtable) providing access to the full configuration data hierarchy. This is made available as `$Datum` within embedded script blocks and expandable strings, enabling lookups like `$Datum.Global.Adds.DomainName`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>Node</maml:name> <maml:description> <maml:para>The current node context (hashtable or object) being processed. If not provided, the function attempts to resolve the node from the file path using `Get-DatumCurrentNode`. This is made available as `$Node` within embedded commands.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>{{ Fill ProgressAction Description }}</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ProjectPath</maml:name> <maml:description> <maml:para>The root path of the DSC configuration project. Used to resolve relative paths within embedded commands.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Datum</maml:name> <maml:description> <maml:para>The Datum structure (hashtable) providing access to the full configuration data hierarchy. This is made available as `$Datum` within embedded script blocks and expandable strings, enabling lookups like `$Datum.Global.Adds.DomainName`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The input object containing the embedded command string(s) to evaluate. This parameter accepts pipeline input. The value should contain a string wrapped with the configured header and footer delimiters (default: `[x=` ... `=]`).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>Node</maml:name> <maml:description> <maml:para>The current node context (hashtable or object) being processed. If not provided, the function attempts to resolve the node from the file path using `Get-DatumCurrentNode`. This is made available as `$Node` within embedded commands.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>{{ Fill ProgressAction Description }}</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ProjectPath</maml:name> <maml:description> <maml:para>The root path of the DSC configuration project. Used to resolve relative paths within embedded commands.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para>This function is registered as a Datum handler in the `Datum.yml` configuration file under the `DatumHandlers` section:</maml:para> <maml:para> DatumHandlers: Datum.InvokeCommand::InvokeCommand: SkipDuringLoad: true</maml:para> <maml:para>The `SkipDuringLoad: true` flag prevents the handler from being invoked during the initial Datum structure loading. Commands are evaluated only during value resolution (e.g., RSOP computation).</maml:para> <maml:para>The header and footer delimiters can be customized in the module configuration file `Config\Datum.InvokeCommand.Config.psd1`.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$value = '[x={ Get-Date }=]' Invoke-InvokeCommandAction -InputObject $value</dev:code> <dev:remarks> <maml:para>Evaluates the embedded script block `{ Get-Date }` and returns the current date/time.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$value = '[x="$($Node.Name) in $($Node.Environment)"=]' Invoke-InvokeCommandAction -InputObject $value -Datum $datum -Node $node</dev:code> <dev:remarks> <maml:para>Expands the embedded string using the `$Node` variable, returning something like 'DSCFile01 in Dev'.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>$value = '[x={ $Datum.Global.Adds.DomainFqdn }=]' Invoke-InvokeCommandAction -InputObject $value -Datum $datum</dev:code> <dev:remarks> <maml:para>Evaluates the script block to return the domain FQDN from Datum's global configuration, e.g., 'contoso.com'.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>$value = '[x={ @{ Name = "Server1"; Value = "Config1" } }=]' Invoke-InvokeCommandAction -InputObject $value</dev:code> <dev:remarks> <maml:para>Returns a hashtable from the evaluated script block. Script blocks can return any PowerShell object type including hashtables, arrays, and custom objects.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>'[x={ Get-Date }=]' | Invoke-InvokeCommandAction</dev:code> <dev:remarks> <maml:para>Demonstrates pipeline input support.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>https://github.com/raandree/Datum.InvokeCommand</maml:linkText> <maml:uri>https://github.com/raandree/Datum.InvokeCommand</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>https://github.com/gaelcolas/datum/</maml:linkText> <maml:uri>https://github.com/gaelcolas/datum/</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Test-InvokeCommandFilter</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Test-InvokeCommandFilter</command:name> <command:verb>Test</command:verb> <command:noun>InvokeCommandFilter</command:noun> <maml:description> <maml:para>Tests whether a Datum value contains an embedded command that should be processed by the Datum.InvokeCommand handler.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This filter function is invoked by the Datum framework's `ConvertTo-Datum` function on every value during data resolution. When this function returns `$true`, the Datum framework calls the corresponding action function `Invoke-InvokeCommandAction` to evaluate the embedded command.</maml:para> <maml:para>The function checks whether the input object is a string that matches the configured regular expression pattern for embedded commands (default pattern: `[x=` ... `=]`). The header and footer delimiters are defined in `Config\Datum.InvokeCommand.Config.psd1` and compiled into a regex at module load time.</maml:para> <maml:para>When the `-ReturnValue` switch is specified, the function returns the full matched string instead of a boolean. This is used internally by `Invoke-InvokeCommandActionInternal` to detect and resolve nested embedded commands.</maml:para> <maml:para>For more information about Datum handlers and their filter/action pattern, see https://github.com/gaelcolas/datum/.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-InvokeCommandFilter</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object to test. Only string values are evaluated against the embedded command pattern. Non-string objects always return `$false`. Accepts pipeline input.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>{{ Fill ProgressAction Description }}</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ReturnValue</maml:name> <maml:description> <maml:para>When specified, returns the full matched string (including header and footer) instead of a boolean. Used internally for nested command resolution.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object to test. Only string values are evaluated against the embedded command pattern. Non-string objects always return `$false`. Accepts pipeline input.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>{{ Fill ProgressAction Description }}</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ReturnValue</maml:name> <maml:description> <maml:para>When specified, returns the full matched string (including header and footer) instead of a boolean. Used internally for nested command resolution.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para>Datum handler modules follow a convention of exposing a filter function (`Test-*`) and an action function (`Invoke-*`). The filter function is called first to determine if the action should be invoked for a given value. This pattern is described in the Datum documentation.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Test-InvokeCommandFilter -InputObject '[x={ Get-Date }=]'</dev:code> <dev:remarks> <maml:para>Returns `$true` because the input string matches the embedded command pattern.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Test-InvokeCommandFilter -InputObject 'Just a regular string'</dev:code> <dev:remarks> <maml:para>Returns `$false` because the input string does not contain an embedded command.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>'[x={ Get-Date }=]' | Test-InvokeCommandFilter</dev:code> <dev:remarks> <maml:para>Demonstrates pipeline input. Returns `$true`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Test-InvokeCommandFilter -InputObject '[x={ Get-Date }=]' -ReturnValue</dev:code> <dev:remarks> <maml:para>Returns the full matched string `[x={ Get-Date }=]` instead of `$true`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>42 | Test-InvokeCommandFilter</dev:code> <dev:remarks> <maml:para>Returns `$false` because the input is not a string.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>https://github.com/raandree/Datum.InvokeCommand</maml:linkText> <maml:uri>https://github.com/raandree/Datum.InvokeCommand</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>https://github.com/gaelcolas/datum/</maml:linkText> <maml:uri>https://github.com/gaelcolas/datum/</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-InvokeCommandAction</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |