diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
new file mode 100644
index 00000000..2287a484
--- /dev/null
+++ b/.github/workflows/build.yml
@@ -0,0 +1,34 @@
+on:
+ push:
+ branches:
+ - master
+ - main
+
+jobs:
+ build:
+
+ runs-on: windows-latest
+ permissions:
+ contents: write
+
+ steps:
+ - uses: actions/checkout@v1
+ - name: Install Prerequisites
+ run: .\build\psf-prerequisites.ps1
+ shell: powershell
+ - name: Install Prerequisites
+ run: .\build\vsts-help.ps1
+ shell: powershell
+ - name: Validate
+ run: .\build\vsts-validate.ps1
+ shell: powershell
+ - name: Build
+ run: .\build\vsts-build.ps1 -ApiKey $env:APIKEY
+ shell: powershell
+ env:
+ APIKEY: ${{ secrets.ApiKey }}
+ - name: Release
+ run: .\build\vsts-release.ps1
+ shell: powershell
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
\ No newline at end of file
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 00000000..3a51c80f
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,18 @@
+on: [pull_request]
+
+jobs:
+ validate:
+
+ runs-on: windows-latest
+
+ steps:
+ - uses: actions/checkout@v1
+ - name: Install Prerequisites
+ run: .\build\psf-prerequisites.ps1
+ shell: powershell
+ - name: Install Prerequisites
+ run: .\build\vsts-help.ps1
+ shell: powershell
+ - name: Validate
+ run: .\build\vsts-validate.ps1
+ shell: powershell
\ No newline at end of file
diff --git a/PSFramework/PSFramework.psd1 b/PSFramework/PSFramework.psd1
index ccf09e7d..4c82df50 100644
--- a/PSFramework/PSFramework.psd1
+++ b/PSFramework/PSFramework.psd1
@@ -4,7 +4,7 @@
RootModule = 'PSFramework.psm1'
# Version number of this module.
- ModuleVersion = '1.12.346'
+ ModuleVersion = '1.13.406'
# ID used to uniquely identify this module
GUID = '8028b914-132b-431f-baa9-94a6952f21ff'
@@ -38,12 +38,14 @@
'Add-PSFFilterCondition'
'Add-PSFLoggingProviderRunspace'
'Add-PSFRunspaceWorker'
+ 'Add-PSFTeppCompletion'
'Clear-PSFMessage'
'Clear-PSFresultCache'
'Compare-PSFArray'
'ConvertFrom-PSFArray'
'ConvertFrom-PSFClixml'
'ConvertTo-PSFClixml'
+ 'ConvertTo-PSFPsd1'
'Disable-PSFConsoleInterrupt'
'Disable-PSFLoggingProvider'
'Disable-PSFTaskEngineTask'
@@ -51,12 +53,15 @@
'Enable-PSFTaskEngineTask'
'Export-PSFClixml'
'Export-PSFConfig'
+ 'Export-PSFJson'
'Export-PSFModuleClass'
+ 'Export-PSFPowerShellDataFile'
'Get-PSFCallback'
'Get-PSFConfig'
'Get-PSFConfigValue'
'Get-PSFDynamicContentObject'
'Get-PSFFeature'
+ 'Get-PSFFileContent'
'Get-PSFFilterCondition'
'Get-PSFFilterConditionSet'
'Get-PSFLicense'
@@ -77,11 +82,13 @@
'Get-PSFTaskEngineCache'
'Get-PSFTaskEngineTask'
'Get-PSFTempItem'
+ 'Get-PSFTeppCompletion'
'Get-PSFTypeSerializationData'
'Get-PSFUserChoice'
'Import-PSFClixml'
'Import-PSFCmdlet'
'Import-PSFConfig'
+ 'Import-PSFJson'
'Import-PSFLocalizedString'
'Import-PSFLoggingProvider'
'Import-PSFPowerShellDataFile'
@@ -115,6 +122,7 @@
'Register-PSFMessageEvent'
'Register-PSFMessageTransform'
'Register-PSFParameterClassMapping'
+ 'Register-PSFPsd1Converter'
'Register-PSFRunspace'
'Register-PSFSessionObjectType'
'Register-PSFSupportDataProvider'
@@ -131,6 +139,7 @@
'Remove-PSFMessageLevelModifier'
'Remove-PSFRunspaceWorkflow'
'Remove-PSFTempItem'
+ 'Remove-PSFTeppCompletion'
'Reset-PSFConfig'
'Resolve-PSFDefaultParameterValue'
'Resolve-PSFItem'
@@ -139,6 +148,7 @@
'Select-PSFPropertyValue'
'Set-PSFDynamicContentObject'
'Set-PSFFeature'
+ 'Set-PSFFileContent'
'Set-PSFLoggingProvider'
'Set-PSFPath'
'Set-PSFResultCache'
@@ -173,6 +183,7 @@
# Cmdlets to export from this module
CmdletsToExport = @(
+ 'Assert-PSFInternalCommand'
'ConvertTo-PSFHashtable'
'Invoke-PSFCallback'
'Invoke-PSFProtectedCommand'
@@ -181,6 +192,7 @@
'Set-PSFConfig'
'Set-PSFObjectOrder'
'Test-PSFShouldProcess'
+ 'Update-PSFTeppCompletion'
'Write-PSFMessage'
)
diff --git a/PSFramework/bin/PSFramework.dll b/PSFramework/bin/PSFramework.dll
index 0ec05368..b7090b20 100644
Binary files a/PSFramework/bin/PSFramework.dll and b/PSFramework/bin/PSFramework.dll differ
diff --git a/PSFramework/bin/PSFramework.pdb b/PSFramework/bin/PSFramework.pdb
index a7b805e5..274101c9 100644
Binary files a/PSFramework/bin/PSFramework.pdb and b/PSFramework/bin/PSFramework.pdb differ
diff --git a/PSFramework/bin/PSFramework.xml b/PSFramework/bin/PSFramework.xml
index 82f48642..f5048d37 100644
--- a/PSFramework/bin/PSFramework.xml
+++ b/PSFramework/bin/PSFramework.xml
@@ -4,6 +4,21 @@
PSFramework
+
+
+ Amazingly useful command, that verifies that the command being executed was called from another command in the same module.
+
+
+
+
+ The $PSCmdlet variable of the calling function. This allows us to throw the error from the calling command and hide our cmdlet to the end user.
+
+
+
+
+ The main implementation, doing the various checks needed to ensure it is only called internally.
+
+
Command executing callbacks in functions
@@ -143,6 +158,17 @@
Execute end step
+
+
+ Imports provided values to parameters configured for an auto-training completer.
+
+
+
+
+ Execute the main (and only) step: Copying over values provided to the calling command as parameter into the completion cache.
+ Only applies to parameters configured for auto-training tab completers.
+
+
Implements the ConvertTo-PSFHashtable command
@@ -174,6 +200,11 @@
Enabling this switch has the command inherit values from variables in the caller scope if their name has been specified in the Include parameter.
+
+
+ Inherit from all parameters of the calling command, including all non-bound parameters.
+
+
Remap individual keys in the hashtable provided.
@@ -303,6 +334,11 @@
The message level at which to generate non-error messages written by this cmdlet
+
+
+ Make the final error generated a nonterminating error
+
+
Information on the calling command, including name, module, file and line.
@@ -390,7 +426,7 @@
The name of the feature to check.
Whether the flag is enabled
-
+
Write a message using the PSFramework. Executed as scriptblock, so the current runspace must not be occupied elseways
@@ -403,8 +439,9 @@
Tags to attach to this message
A target object to specify
Add additional metadata to the message written
+ Exception to include in the message
-
+
Write a message using the PSFramework. Executed as scriptblock, so the current runspace must not be occupied elseways
@@ -418,6 +455,7 @@
Tags to attach to this message
A target object to specify
Add additional metadata to the message written
+ Exception to include in the message
@@ -453,6 +491,12 @@
Whether the command has been set to terminate by StopCommand. Use when supporting EnableException
+
+
+ Throw a continue exception, equivalent to calling continue in script
+
+
+
Invokes all applicable callback scripts.
@@ -620,6 +664,13 @@
Implements the end action of the command
+
+
+ Converts a select-object result based on extra elements to add
+
+ The item to convert / extend
+ A fully converted object
+
Implements the Set-PSFConfig command
@@ -952,6 +1003,12 @@
This is less user friendly, but allows catching exceptions in calling scripts.
+
+
+ Create a new error record, using the current message, then write it.
+ This parameter is only respected if EnableException is set to true.
+
+
Enables breakpoints on the current message. By default, setting '-Debug' will NOT cause an interrupt on the current position.
@@ -1521,6 +1578,457 @@
The value is something indeterminate, but possibly complex
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ The type the custom converter is assigned to
+
+
+
+
+ The code calculating the new PSD1-String
+
+
+
+
+ Any additional properties to assign to this.
+ These properties are made available to the code via the $this variable
+
+
+
+
+ The result to return as a default.
+ This is mostly used in combination with "OnErrorDefault"
+
+
+
+
+ Whether in case of an error it should just return a default string, rather than failing the entire conversion.
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Creates a new custom converter
+
+ The type that should be converted
+ The code doing the conversion
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Converts data structures into PSD1 Strings
+
+
+
+
+ Converts to psd1 string
+
+ The object to convert
+ The indentation level
+ The conversion runtime object, including its settings.
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The converted PSD1 representation of the value provided
+
+
+
+ Global Helper Tools for dealing with Data
+
+
+
+
+ The registered list of PSD1 converters
+
+
+
+
+ The fallback converter to use when all else fails
+
+
+
+
+ The converter to use for dictionaries, such as Hashtables
+
+
+
+
+ Convert an object to the string to insert into a psd1 document.
+
+ The value to convert
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The current indentation depth. Can be ignored for plain value returns, if you do not need to return multiple lines.
+ The conversion runtime object, including its settings.
+ The converted PSD1 representation of the value provided
+
+
+
+ Resets the PSD1 Converters to their default state
+
+
+
+
+ Ruleset for types implementing PSD1 Conversion
+
+
+
+
+ Convert an object to the string to insert into a psd1 document.
+
+ The value to convert
+ The parent objects. Used in complex data types to prevent infinite recursion.
+ The current indentation depth. Can be ignored for plain value returns, if you do not need to return multiple lines.
+ The conversion runtime object, including its settings.
+ The converted PSD1 representation of the value provided
+
+
+
+ The PSD1 conversion runtime object.
+ Use this to transport any settings conversion plugins require.
+
+
+
+
+ The reference to the PowerShell command running this conversion.
+ Can be used to directly interact with the current runtime, send messages or throw errors.
+ May be null.
+
+
+
+
+ How deeply nested are we willing to delve into sub-properties?
+ By default, this is only respected for PSObjects or Dictionaries.
+
+
+
+
+ Extra configuration settings.
+ This will be ignored by the default, builtin converters, but external ones may use this to transport and implement settings.
+
+
+
+
+ Enable verbose messages.
+
+
+
+
+ Convert some object to PSD1
+
+ The object to convert to PSD1
+ A PSD1-string
+
+
+
+ Convert some object to PSD1
+
+ The object to convert to PSD1
+ How deeply indented do we start?
+ What parent objects came before us? Helps prevent infinite recursion.
+ A PSD1-string
+
+
+
+ Send a message (maybe)
+
+
+
+
+
+ Escapes a string's single quotes of all flavors.
+
+ The text to escape
+ A properly escaped string
+
+
+
+ Escapes a string's single quotes of all flavors.
+ Ensures content is converted to text using PowerShell rules first.
+
+ The text to escape
+ A properly escaped string
+
An individual filter condition.
@@ -3269,6 +3777,45 @@
Generation 2 logging provider, where each provider is handled as a dynamically created module, properly isolating resource from each other.
+
+
+ Helper class to properly format logging messages for the TXT-Variant of the logfile provider
+
+
+
+
+ The text pattern provided by the user, describing the way the logfile is supposed to look.
+
+
+
+
+ The properties that exist within the text pattern. Used to optimize the content replacement process.
+
+
+
+
+ Create an empty text-builder
+
+
+
+
+ Create a text-builder preconfigured with a text to build
+
+ The text to build. Use "%PropertyName%" to offer placeholders that later values get inserted into.
+
+
+
+ Load a new text to build.
+
+ The text to build. Use "%PropertyName%" to offer placeholders that later values get inserted into.
+
+
+
+ Take a message object and build it into a string, ready for logging
+
+ The message object to build.
+ The finished message, ready for the logfile.
+
Container for a callstack, to create a non-volatile copy of the relevant information
@@ -4013,6 +4560,11 @@
Include message timestamps in verbose message output
+
+
+ Include the message target (if present) in verbose message output
+
+
Include the level of a message in verbose message output
@@ -4038,6 +4590,11 @@
Whether the console messages should be written with only one color, rather than respecting color tags
+
+
+ The format used in messages written on screen
+
+
Define the message prefix value for the critical level
@@ -4860,18 +5417,179 @@
The category of the error, determining the exception type
An exception
-
+
- Provides centralized utilities for interacting with PowerShell objects.
+ Wrapper exposing a PowerShell scope and all its content.
-
+
- Add a set of noteproperties to the specified PowerShell object
+ What kind of scope it is.
- The object to extend
- The set of properties to add
- Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
+
+
+ Creates an empty scope object
+
+
+
+
+ Creates a scope object, wrapping around a previously reflected PS scope object.
+
+ The raw scope object, as obtained from the PowerShell engine via reflection.
+
+
+
+ Get a representation of the global scope.
+
+ a representation of the global scope
+
+
+
+ Get a representation of the module scope.
+
+ a representation of the module scope
+
+
+
+ Get a representation of the script scope.
+
+ a representation of the script scope
+
+
+
+ Get a representation of the current scope.
+
+ a representation of the current scope
+
+
+
+ Enable access to variable content of the scope.
+
+
+
+
+ Disable access to variable content of the scope.
+
+
+
+
+ The variables contained in the scope
+
+
+
+
+ Checks whether a specific variable exists in the scope
+
+ Name of the variable to scan for
+ Whether the variable exists
+
+
+
+ Retrieve the value of a variable in the scope.
+ Returns null if scope or variable do not exist.
+
+ Name of the variable to retrieve.
+ The value of the variable.
+
+
+
+ Change the value of a variable, in effect overwriting it.
+
+ The name of the variable to apply
+ The value to assign to the variable
+
+
+
+ Enable access to alias content of the scope.
+
+
+
+
+ Disable access to alias content of the scope.
+
+
+
+
+ The aliases of the scope
+
+
+
+
+ Enable access to function content of the scope.
+
+
+
+
+ Disable access to function content of the scope.
+
+
+
+
+ The functions defined within the scope.
+
+
+
+
+ Enable access to cmdlet content of the scope.
+
+
+
+
+ Disable access to cmdlet content of the scope.
+
+
+
+
+ The Cmdlets contained within the scope
+
+
+
+
+ Enable access to PSDrivecontent of the scope.
+
+
+
+
+ Disable access to PSDrivecontent of the scope.
+
+
+
+
+ The PSDrives contained within the scope
+
+
+
+
+ The Parent Scope of the current scope
+
+
+
+
+ Update the assigned Type.
+ Intended when generating a scope based on another scope.
+
+
+
+
+ Provides centralized utilities for interacting with PowerShell objects.
+
+
+
+
+ Add a set of noteproperties to the specified PowerShell object
+
+ The object to extend
+ The set of properties to add
+ Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
+
+
+ Add a set of noteproperties to all specified PowerShell objects
+
+ The objects to extend
+ The set of properties to add
+ Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
@@ -4882,6 +5600,15 @@
The value to assign to the new property
Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
+
+ Adds a single noteproperty to a lot of specified PowerShell objects
+
+ The objects to extend
+ The name of the property to add
+ The value to assign to the new property
+ Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
Adds a script-calculated property to the specified PowerShell object
@@ -4892,6 +5619,16 @@
(optional) The code used when assigning input to the property.
Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
+
+ Adds a script-calculated property to the specified PowerShell objects
+
+ The objects to extend
+ The name of the script-property to add
+ The code used to read the value
+ (optional) The code used when assigning input to the property.
+ Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
Removes a member from the specified PowerShell object
@@ -4899,6 +5636,13 @@
The object to remove a member from
The name of the member to remove.
+
+
+ Removes a member from the specified PowerShell objects
+
+ The objects to remove a member from
+ The name of the member to remove.
+
Adds a script-based method to the specified PowerShell object
@@ -4908,6 +5652,15 @@
The code implementing the logic when the method is called.
Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
+
+ Adds a script-based method to the specified PowerShell objects
+
+ The objects to extend
+ The name of the method to add.
+ The code implementing the logic when the method is called.
+ Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
Adds several script methods to the specified PowerShell object
@@ -4916,6 +5669,14 @@
The methods to add. Provide a hashtable mapping method name to scriptblock with the logic implementing the method.
Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
+
+ Adds several script methods to the specified PowerShell objects
+
+ The objects to extend
+ The methods to add. Provide a hashtable mapping method name to scriptblock with the logic implementing the method.
+ Whether validation has already been performed and need not be done. Setting this to false will add performance overhead.
+
Extend default hashtables to include a default value
@@ -4926,6 +5687,16 @@
The default value when retrieving values for keys that do not exist
+
+
+ Whether in case of unexpected key, the key should be returned, rather than a default value.
+
+
+
+
+ Scriptblock used to calculate result when providing a key that is not applied to the hashtable.
+
+
Creates a new, empty psfhashtable
@@ -4943,6 +5714,22 @@
The default value when accessing this PsfHashtable's values
+
+
+ Enables the PassThru behavior, where an unexpected key gets returned as the default action
+
+
+
+
+ Disables the PassThru behavior, where an unexpected key would get returned as the default action
+
+
+
+
+ Sets the scriptblock used to calculate the results for keys, that are not registered with the hashtable
+
+ The logic doing the calculating. Provide null to disable.
+
Create a copy of the current PsfHashtable, including its default value. The default value will be the same instance of an object.
@@ -5305,6 +6092,112 @@
+
+
+ Parameterclass that accepts a single directory
+
+
+
+
+ Processes a single string as a single directory.
+
+ The path to process
+
+
+
+ Processes a single DirectoryInfo item as a single directory.
+
+ The path to process
+
+
+
+ Processes a single Uri as a single directory.
+
+ The path to process
+
+
+
+ Processes a single object as a single directory.
+
+ The path to process
+
+
+
+ Implicitly convert to string.
+
+ The path to convert
+
+
+
+ Implicitly convert to DirectoryInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert DirectoryInfo to PathDirectorySingleParameter.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileSystemInfo.
+
+ The path to convert
+
+
+
+ Parameterclass accepting/resolving to a single, fully-resolved path to a file.
+
+
+
+
+ Processes a single string as a single file.
+
+ The path to process
+
+
+
+ Processes a single FileInfo item as a single file.
+
+ The path to process
+
+
+
+ Processes a single Uri as a single file.
+
+ The path to process
+
+
+
+ Processes a single object as a single file.
+
+ The path to process
+
+
+
+ Implicitly convert to string.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert FileInfo to PathFileSingle.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileSystemInfo.
+
+ The path to convert
+
Resolves any file or folder evaluating wildcards, will not throw on bad input
@@ -5782,6 +6675,228 @@
+
+
+ Parameter Class that maps to a single file or folder
+
+
+
+
+ Processes a single string as a single directory or file.
+
+ The path to process
+
+
+
+ Processes a single DirectoryInfo item as a single directory.
+
+ The path to process
+
+
+
+ Processes a single FileInfo item as a single file.
+
+ The path to process
+
+
+
+ Processes a single Uri as a single directory or file.
+
+ The path to process
+
+
+
+ Processes a single object as a single directory or file.
+
+ The path to process
+
+
+
+ Implicitly convert to string.
+
+ The path to convert
+
+
+
+ Implicitly convert to DirectoryInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert DirectoryInfo to PathFileSystemSingleParameter.
+
+ The path to convert
+
+
+
+ Implicitly convert FileInfo to PathFileSystemSingleParameter.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileSystemInfo.
+
+ The path to convert
+
+
+
+ Base class for parameter classes mapping to a single filesystem item
+
+
+
+
+ The path resolved
+
+
+
+
+ Default text representation of the PathFileSingle type.
+
+ Its path.
+
+
+
+ Resolve the path provided and ensure it exists and is of the proper type!
+
+ The path to resolve
+ Whether it may be a file
+ Whether it may be a directory
+ When the path provided cannot be resolved at all.
+ When the path provided resolves to multiple items.
+ When the path should resolve to a file, but is not a file.
+ When the path should resolve to a directory, but is not a directory.
+
+
+
+ Verify the specified path exists, process relative paths, but do not apply wildcards.
+
+ The path to process
+ Whether the path may point to a file
+ Whether the path may point to a directory
+ Thrown if the item does not exist at all
+ When the path should resolve to a file, but is not a file.
+ When the path should resolve to a directory, but is not a directory.
+
+
+
+ Implicitly convert to string.
+
+ The path to convert
+
+
+
+ Parameter class that maps to a single directory.
+
+
+
+
+ Processes a single string as a single directory.
+
+ The path to process
+
+
+
+ Processes a single DirectoryInfo item as a single directory.
+
+ The path to process
+
+
+
+ Processes a single Uri as a single directory.
+
+ The path to process
+
+
+
+ Processes a single object as a single directory.
+
+ The path to process
+
+
+
+ Implicitly convert to string.
+
+ The path to convert
+
+
+
+ Implicitly convert to DirectoryInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert DirectoryInfo to PathLiteralDirectorySingleParameter.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileSystemInfo.
+
+ The path to convert
+
+
+
+ Parameter Class that maps to a single file without processing wildcards
+
+
+
+
+ Processes a single string as a single file.
+
+ The path to process
+
+
+
+ Processes a single FileInfo item as a single file.
+
+ The path to process
+
+
+
+ Processes a single Uri as a single file.
+
+ The path to process
+
+
+
+ Processes a single object as a single file.
+
+ The path to process
+
+
+
+ Implicitly convert to string.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert FileInfo to PathLiteralFileSingleParameter.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileSystemInfo.
+
+ The path to convert
+
Input converter performing path evaluation without wildcard interpretation, not throwing errors on bad input
@@ -5908,6 +7023,77 @@
+
+
+ Parameter Class that maps to a single file or directory, without resolving wildcards.
+
+
+
+
+ Processes a single string as a single directory or file.
+
+ The path to process
+
+
+
+ Processes a single DirectoryInfo item as a single directory.
+
+ The path to process
+
+
+
+ Processes a single FileInfo item as a single file.
+
+ The path to process
+
+
+
+ Processes a single Uri as a single directory or file.
+
+ The path to process
+
+
+
+ Processes a single object as a single directory or file.
+
+ The path to process
+
+
+
+ Implicitly convert to string.
+
+ The path to convert
+
+
+
+ Implicitly convert to DirectoryInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert to DirectoryInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert DirectoryInfo to PathDirectorySingleParameter.
+
+ The path to convert
+
+
+
+ Implicitly convert FileInfo to PathDirectorySingleParameter.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileSystemInfo.
+
+ The path to convert
+
Parameter class, converting input into the path to a file, where either the file or at least its parent folder already exist.
@@ -5957,6 +7143,59 @@
+
+
+ ParameterClass to map to a single file that needs not exist, but whose parent directory must.
+
+
+
+
+ Processes a single string as a single file.
+
+ The path to process
+
+
+
+ Processes a single FileInfo item as a single file.
+
+ The path to process
+
+
+
+ Processes a single Uri as a single file.
+
+ The path to process
+
+
+
+ Processes a single object as a single file.
+
+ The path to process
+
+
+
+ Implicitly convert to string.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileInfo.
+
+ The path to convert
+
+
+
+ Implicitly convert FileInfo to PathDirectorySingleParameter.
+
+ The path to convert
+
+
+
+ Implicitly convert to FileSystemInfo.
+
+ The path to convert
+
Parameter Class to help automate certificate store lookup but also accept a pure certificate object
@@ -7594,6 +8833,11 @@
Allows integrating PSFramework tab expansion by attribute, rather than command.
+
+
+ The name of the completion
+
+
Create an argument completer offering but the name of the registered completion
@@ -7683,6 +8927,26 @@
Whether to execute the scriptblock in the global scope
+
+
+ If true: Match input against any part of the options, not just the beginning
+
+
+
+
+ If true: Wrap all results into quotes, not just those with whitespace
+
+
+
+
+ If true: Apply FuzzyMatching to the legal completions, not just direct word matching.
+
+
+
+
+ If true: Completion results will not be sorted by name.
+
+
Returns whether a new refresh of tab completion should be executed.
@@ -7694,6 +8958,48 @@
+
+
+ Returns the matching pattern applied against the list of completion values.
+
+ What the user typed so far
+ The resolved pattern to match with
+
+
+
+ The trained values for the current completion scriptblock.
+
+
+
+
+ Whether this completion should automatically be trained with values provided to parameters
+
+
+
+
+ Add a completion option to the list of trained completions.
+
+ The value to offer for completion
+
+
+
+ Add a completion option to the list of trained completions.
+
+ A hashtable with the completion data to add. Must at least contain a "Text" node.
+ An invalid hashtable, not containing a key named "Text" will cause an argument exception
+
+
+
+ Remove a previously provided completion value.
+
+ The text value to no longer complete.
+
+
+
+ Remove a previously provided completion value.
+
+ Hashtable containing the completion to no longer offer.
+
Class that handles the static fields supporting the ÜSFramework TabExpansion implementation
@@ -7709,6 +9015,21 @@
The cache used by scripts utilizing TabExpansionPlusPlus for PSFramework
+
+
+ Whether PSFramework completion should by default match type text to anywhere in the included/valid options' text, not just from the beginning.
+
+
+
+
+ Whether PSFramework completion should always wrap quotes around the completion text, even if there is no whitespace.
+
+
+
+
+ Whether PSFramework completion should use fuzzy-matching when matching completion values with the already typed text.
+
+
Registers a new completion scriptblock
@@ -9917,6 +11238,22 @@
The compressed string to expand
Returns an expanded string.
+
+
+ Joins two path segments together. Will correct path separators, will trace back ".." path segments. Will ignore the Base, if the Child is an absolute Uri.
+
+ The base path to which to add the child
+ The child path segement to add to the base
+ The fully joined path
+
+
+
+ Tool to remove items from an array at a specific location
+
+ The array to remove items from
+ The indexes of the items to remove
+ A new array with all items of the source array, minus the ones at the specified indexes.
+
Returns the execution context for the current runspace based on the current thread.
@@ -10026,6 +11363,15 @@
The arguments to pass to the method
The result of the method invoked
+
+
+ Creates a new PSCustomObject based on the base object wrapped by the input.
+
+ The item to refelct upon.
+ Whether to include public properties / fields
+ Whether to include private properties / fields
+ A new object containing only properties and fields of the base input. Anything else (including noteproperties of the input) will be ignored.
+
Execute a constructor for the specified type, creating a new instance of it.
diff --git a/PSFramework/bin/type-aliases.ps1 b/PSFramework/bin/type-aliases.ps1
index 877a0f6a..7e610543 100644
--- a/PSFramework/bin/type-aliases.ps1
+++ b/PSFramework/bin/type-aliases.ps1
@@ -1,36 +1,44 @@
# Define our type aliases
$TypeAliasTable = @{
- PsfArgumentCompleter = "PSFramework.TabExpansion.PsfArgumentCompleterAttribute"
- PSFComputer = "PSFramework.Parameter.ComputerParameter"
- PSFComputerParameter = "PSFramework.Parameter.ComputerParameter"
- PSFDateTime = "PSFramework.Parameter.DateTimeParameter"
- PSFDateTimeParameter = "PSFramework.Parameter.DateTimeParameter"
- PsfDirectory = 'PSFramework.Parameter.PathDirectoryParameter'
- PsfDirectoryLax = 'PSFramework.Parameter.PathDirectoryLaxParameter'
- PsfDynamicTransform = 'PSFramework.Utility.DynamicTransformationAttribute'
- PSFEncoding = "PSFramework.Parameter.EncodingParameter"
- PSFEncodingParameter = "PSFramework.Parameter.EncodingParameter"
- PsfErrorRecord = 'PSFramework.Meta.PsfErrorRecord'
- PsfFile = 'PSFramework.Parameter.PathFileParameter'
- PsfFileLax = 'PSFramework.Parameter.PathFileLaxParameter'
- PsfHashtable = 'PSFramework.Object.PsfHashtable'
- PsfLiteralPath = 'PSFramework.Parameter.PathLiteralParameter'
- PsfLiteralPathLax = 'PSFramework.Parameter.PathLiteralLaxParameter'
- PsfNewFile = 'PSFramework.Parameter.PathNewFileParameter'
- PSFNumber = 'PSFramework.Utility.Number'
- PsfPath = 'PSFramework.Parameter.PathFileSystemParameter'
- PsfPathLax = 'PSFramework.Parameter.PathFileSystemLaxParameter'
- psfrgx = "PSFramework.Utility.RegexHelper"
- PsfScriptBlock = 'PSFramework.Utility.PsfScriptBlock'
- PsfScriptTransform = 'PSFramework.Utility.ScriptTransformationAttribute'
- PSFSize = "PSFramework.Utility.Size"
- PSFTimeSpan = "PSFramework.Parameter.TimeSpanParameter"
- PSFTimeSpanParameter = "PSFramework.Parameter.TimeSpanParameter"
- PsfValidateLanguageMode = "PSFramework.Validation.PsfValidateLanguageMode"
- PSFValidatePattern = "PSFramework.Validation.PsfValidatePatternAttribute"
- PSFValidatePSVersion = "PSFramework.Validation.PsfValidatePSVersion"
- PSFValidateScript = "PSFramework.Validation.PsfValidateScriptAttribute"
- PSFValidateSet = "PSFramework.Validation.PsfValidateSetAttribute"
+ PsfArgumentCompleter = "PSFramework.TabExpansion.PsfArgumentCompleterAttribute"
+ PSFComputer = "PSFramework.Parameter.ComputerParameter"
+ PSFComputerParameter = "PSFramework.Parameter.ComputerParameter"
+ PSFDateTime = "PSFramework.Parameter.DateTimeParameter"
+ PSFDateTimeParameter = "PSFramework.Parameter.DateTimeParameter"
+ PsfDirectory = 'PSFramework.Parameter.PathDirectoryParameter'
+ PsfDirectoryLax = 'PSFramework.Parameter.PathDirectoryLaxParameter'
+ PsfDirectorySingle = 'PSFramework.Parameter.PathDirectorySingleParameter'
+ PsfDynamicTransform = 'PSFramework.Utility.DynamicTransformationAttribute'
+ PSFEncoding = "PSFramework.Parameter.EncodingParameter"
+ PSFEncodingParameter = "PSFramework.Parameter.EncodingParameter"
+ PsfErrorRecord = 'PSFramework.Meta.PsfErrorRecord'
+ PsfFile = 'PSFramework.Parameter.PathFileParameter'
+ PsfFileLax = 'PSFramework.Parameter.PathFileLaxParameter'
+ PsfFileSingle = 'PSFramework.Parameter.PathFileSingleParameter'
+ PsfHashtable = 'PSFramework.Object.PsfHashtable'
+ PsfLiteralDirectorySingle = 'PSFramework.Parameter.PathLiteralDirectorySingleParameter'
+ PsfLiteralFileSingle = 'PSFramework.Parameter.PathLiteralFileSingleParameter'
+ PsfLiteralPath = 'PSFramework.Parameter.PathLiteralParameter'
+ PsfLiteralPathLax = 'PSFramework.Parameter.PathLiteralLaxParameter'
+ PsfLiteralPathSingle = 'PSFramework.Parameter.PathLiteralSingleParameter'
+ PsfNewFile = 'PSFramework.Parameter.PathNewFileParameter'
+ PsfNewFileSingle = 'PSFramework.Parameter.PathNewFileSingleParameter'
+ PSFNumber = 'PSFramework.Utility.Number'
+ PsfPath = 'PSFramework.Parameter.PathFileSystemParameter'
+ PsfPathLax = 'PSFramework.Parameter.PathFileSystemLaxParameter'
+ PsfPathSingle = 'PSFramework.Parameter.PathFileSystemSingleParameter'
+ psfrgx = "PSFramework.Utility.RegexHelper"
+ PsfScope = 'PSFramework.Meta.Scope'
+ PsfScriptBlock = 'PSFramework.Utility.PsfScriptBlock'
+ PsfScriptTransform = 'PSFramework.Utility.ScriptTransformationAttribute'
+ PSFSize = "PSFramework.Utility.Size"
+ PSFTimeSpan = "PSFramework.Parameter.TimeSpanParameter"
+ PSFTimeSpanParameter = "PSFramework.Parameter.TimeSpanParameter"
+ PsfValidateLanguageMode = "PSFramework.Validation.PsfValidateLanguageMode"
+ PSFValidatePattern = "PSFramework.Validation.PsfValidatePatternAttribute"
+ PSFValidatePSVersion = "PSFramework.Validation.PsfValidatePSVersion"
+ PSFValidateScript = "PSFramework.Validation.PsfValidateScriptAttribute"
+ PSFValidateSet = "PSFramework.Validation.PsfValidateSetAttribute"
}
Set-PSFTypeAlias -Mapping $TypeAliasTable
\ No newline at end of file
diff --git a/PSFramework/changelog.md b/PSFramework/changelog.md
index 0d6e23d5..2728856e 100644
--- a/PSFramework/changelog.md
+++ b/PSFramework/changelog.md
@@ -1,5 +1,68 @@
# CHANGELOG
+## 1.13.406 (2025-08-29)
+
+- New: Assert-PSFInternalCommand - Verifies, that the command calling it in turn was only called from another command within the same module. (#685)
+- New: Add-PSFTeppCompletion - Adds a completion result to a tab completion script.
+- New: Remove-PSFTeppCompletion - Removes a previously added completion result from a tab completion script.
+- New: Update-PSFTeppCompletion - Automatically adds provided values to the completion result of the associated completion script.
+- New: Get-PSFFileContent - Reads content from a file.
+- New: Set-PSFFileContent - Writes content to a file.
+- New: Export-PSFJson - Converts input to json string and writes the result to file.
+- New: Import-PSFJson - Reads json files and returns their content as objects.
+- New: ConvertTo-PSFPsd1 - Converts objects into PSD1 configuration text.
+- New: Export-PSFPowerShellDataFile - Exports data into psd1 config files.
+- New: Register-PSFPsd1Converter - Registers a new piece of logic used to convert specific data types to PSD1 format.
+- New: PSFScope - type granting direct access to the current, script, module or global scope as an object.
+- New: Configuration Setting - `PSFramework.TabExpansion.FuzzyMatch`: Whether to match tab completions with Fuzzy-Matching by default.
+- New: Configuration Setting - `PSFramework.TabExpansion.MatchAnywhere`: Wrap all completion results into quotes, whitespace or not.
+- New: Configuration Setting - `PSFramework.TabExpansion.AlwaysQuote`: Whether to match tab completions with Fuzzy-Matching by default.
+- New: Configuration Setting - `PSFramework.Message.Style.TimeFormat`: The format used in timestamps for messages written on screen.
+- New: Configuration Setting - `PSFramework.Message.Style.Target`: Include the message target (if present) in verbose message output.
+- New: Configuration Export Schema - The "Psd1" schema was added as an alternative name for "MetaJson", offering the same implementation logic.
+- New: Parameter Class PsfFileSingle - Converts input into the path to a single file.
+- New: Parameter Class PsfDirectorySingle - Converts input into the path to a single directory.
+- New: Parameter Class PsfPathSingle - Converts input into the path to a single filesystem path.
+- New: Parameter Class PsfLiteralPathSingle - Converts input into the path to a single filesystem path without resolving wildcards.
+- New: Parameter Class PsfLiteralFileSingle - Converts input into the path to a single file without resolving wildcards.
+- New: Parameter Class PsfLiteralDirectorySingle - Converts input into the path to a single directory without resolving wildcards.
+- New: Parameter Class PsfNewFileSingle - Converts input into the path to a single file, which may or may not exist, but whose parent directory _must_ exist.
+- Upd: Tab Completion - Now sorts by the List Item Text - the options shown in the tab menu - rather than the actual value being inserted into the console.
+- Upd: Tab Completion - Added support for `ToolTipString` and `ListItemTextString` in the result, allowing to localize tab completion tooltip and list items.
+- Upd: Tab Completion - Can now be trained / provided with an explicit list of completions to offer.
+- Upd: Register-PSFTeppScriptblock - add parameter `-FuzzyMatch` to match input against the completions using Fuzzy Logic.
+- Upd: Register-PSFTeppScriptblock - add parameter `-MatchAnywhere` to match input against anywhere within the completions, not just from the start.
+- Upd: Register-PSFTeppScriptblock - add parameter `-AlwaysQuote` to wrap all completion results into quotes, irrespective of whether they contain a whitespace or not.
+- Upd: Register-PSFTeppScriptblock - add parameter `-DontSort` to stop sorting completion results alphabetically.
+- Upd: ConvertTo-PSFHashtable - add parameter `-InheritParameters` that automatically picks up values from the calling command / script.
+- Upd: Write-PSFMessage - add parameter `-NewErrorRecord` to actually write an error when also specifying `-EnableException`, even if the command did not first receive an error record as input. (#659)
+- Upd: Select-PSFObject - Can now select variables directly, as well as properties of variables (#664)
+- Upd: Invoke-PSFProtectedCommand - add parameter `-NonTerminating` to stop sending terminating exceptions in combination with `-EnableException`.
+- Upd: New-PSFHashtable - Added parameter `-PassThru` to create a hashtable that will return the key itself if it does not exist on the hashtable.
+- Upd: New-PSFHashtable - Added parameter `-Calculator` to create a hashtable that will return the result of this scriptblock if the key does not exist on the hashtable.
+- Upd: New-PSFSupportPackage - When specifying a task-name, the command will no longer spam messages on screen, instead sending the message to verbose.
+- Upd: Type Object.ObjectHost - added methods to modify PSObjects in bulk
+- Upd: PSFHashtable - added method `EnablePassThru()`, which will return the Key itself, when the provided key does not yet exist in the hashtable. (#676)
+- Upd: PSFHashtable - added method `SetCalculator()`, which will calculate the value returned using a scriptblock, when the provided key does not yet exist in the hashtable. (#676)
+- Upd: PSFCmdlet - added method `DoContinue()`, allowing cmdlets to trigger a powershell script-based continue action.
+- Upd: Logging Provider logfile - Added option `JsonNoEmptyFirstLine` to make it stop adding an empty line at the beginning of the logfile. As an option to avoid breaking changes for people automatically processing the logfile.
+- Upd: Logging Provider logfile - Added option `CMTraceOverrideComponent` to allow overriding the "Component" section on a per-message basis, vie the `-Data` parameter. (#623)
+- Upd: Logging Provider logfile - Added new filetype `TXT` to the list of supported filetypes. This allows creating simple plaintext logfiles, even when they are generally discouraged. (#654)
+- Upd: Logging Provider logfile - Added option `TXTPattern`: The pattern of any given line in the TXT-based logfile. Use %PROPERTYNAME% as placeholder, e.g. "%Message%". Same properties as with the headers configuration - you need to specify both settings, if your pattern includes non-default properties such as "Data". (#654)
+- Fix: Logging Provider logfile - Renaming header breaks timestamp format (#672)
+- Fix: Logging Provider logfile - Using the `JsonString` parameter breaks header order (#667)
+- Fix: Logging Provider SQL - Fails to log the `Data` field correctly (#680)
+- Fix: Configuration - fails to restore the persisted form of an empty hashtable (#650)
+- Fix: Pathing issue - Programdata resolution fails when environment variable is not available (#671)
+- Fix: ScriptTransformation Attribute - conversion results were not considered valid, when not of the demanded type, but one inheriting from the demanded type. (#646)
+- Fix: ParameterClass Path - Fails on `.ToString()` on Stack Overflow.
+- Fix: Select-PSFObject - fails with "Index was outside the bounds of the array." when combining `-Last` with `-TypeName` or any other parameter that causes the command to intercept the output of `Select-Object` (#666)
+- Fix: ConvertTo-PSFHashtable - fails to correctly resolve the reference command when somebody overrides the Get-Command command in a breaking way.
+- Fix: ConvertTo-PSFHashtable - fails with an index error when the `-ReferenceCommand` command cannot be resolved.
+- Fix: ConvertTo-PSFHashtable - when specifying the `-Inherit` parameter, the `-Exclude` parameter is ignored for inherited values.
+- Fix: Write-PSFMessage - fails to process a Switch value as input. (#655)
+- Fix: Import-PSFPowerShellDataFile - does not import DateTime properties from json correctly on PowerShell 7.
+
## 1.12.346 (2024-09-25)
- Fix: MessageLevel Modifiers break Write-PSFMessage
diff --git a/PSFramework/functions/data/ConvertTo-PSFPsd1.ps1 b/PSFramework/functions/data/ConvertTo-PSFPsd1.ps1
new file mode 100644
index 00000000..6f43f5ce
--- /dev/null
+++ b/PSFramework/functions/data/ConvertTo-PSFPsd1.ps1
@@ -0,0 +1,58 @@
+function ConvertTo-PSFPsd1 {
+ <#
+ .SYNOPSIS
+ Converts objects into PSD1 configuration text.
+
+ .DESCRIPTION
+ Converts objects into PSD1 configuration text.
+
+ Use Register-PSFPsd1Converter to extend/customize how this conversion happens.
+
+ .PARAMETER Depth
+ How many levels deep do you want to process sub-properties?
+ Defaults to 2
+
+ .PARAMETER EnableVerbose
+ Enables deep verbosity when processing objects.
+ By default, individual conversion steps are not tracked for performance reasons.
+ Enable this for extensive amounts of debug messages.
+
+ .PARAMETER Configuration
+ Additional configuration settings to provide for the conversion.
+ Custom converters may use these as implemented in their custom conversion.
+
+ .PARAMETER InputObject
+ The object(s) to convert.
+
+ .EXAMPLE
+ PS C:\> Get-ChildItem | ConvertTo-PSFPsd1
+
+ Takes all files and folders and converts the data into psd1-style data structures.
+ #>
+ [OutputType([string])]
+ [CmdletBinding()]
+ param (
+ [int]
+ $Depth = 2,
+
+ [switch]
+ $EnableVerbose,
+
+ [Hashtable]
+ $Configuration = @{},
+
+ [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+ [AllowNull()]
+ $InputObject
+ )
+ begin {
+ $converter = [PSFramework.Data.Psd1Converter]::new()
+ $converter.Depth = $Depth
+ $converter.EnableVerbose = $EnableVerbose
+ $converter.Config = $Configuration
+ $converter.Cmdlet = $PSCmdlet
+ }
+ process {
+ $converter.Convert($InputObject)
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/data/Export-PSFJson.ps1 b/PSFramework/functions/data/Export-PSFJson.ps1
new file mode 100644
index 00000000..50a4a524
--- /dev/null
+++ b/PSFramework/functions/data/Export-PSFJson.ps1
@@ -0,0 +1,78 @@
+function Export-PSFJson {
+ <#
+ .SYNOPSIS
+ Converts input to json string and writes the result to file.
+
+ .DESCRIPTION
+ Converts input to json string and writes the result to file.
+ Uses ConvertTo-Json under the hood.
+
+ .PARAMETER Path
+ The path to the file(s) to create.
+ The parent directory must exist, the file will be overwritten if it already does.
+
+ .PARAMETER InputObject
+ The data to convert to json and export.
+
+ .PARAMETER Depth
+ How deep the into sub-properties do we want to delve?
+ Defaults to 2.
+ Any nested sub-properties that are deeper than that many levels in will be lost in the result.
+
+ .PARAMETER Compress
+ Whether the Json string should be compressed to save space.
+
+ .PARAMETER Encoding
+ What encoding to write the file in.
+ Defaults to UTF8 (with BOM).
+
+ .EXAMPLE
+ PS C:\> Get-MgUser | Export-PSFJson .\users.json
+
+ Write all users from Microsoft Graph into a json file.
+ #>
+ [CmdletBinding()]
+ param (
+ [Parameter(Mandatory = $true)]
+ [PSFNewFile]
+ $Path,
+
+ [Parameter(ValueFromPipeline = $true)]
+ $InputObject,
+
+ [int]
+ $Depth,
+
+ [switch]
+ $Compress,
+
+ [PSFArgumentCompleter('PSFramework-Encoding')]
+ [PSFEncoding]
+ $Encoding = 'UTF8'
+ )
+ begin {
+ $convertParam = @{ }
+ if ($PSBoundParameters.Keys -contains 'Depth') { $convertParam.Depth = $Depth }
+ if ($PSBoundParameters.Keys -contains 'Compress') { $convertParam.Compress = $Compress }
+ $converter = { ConvertTo-Json @convertParam }.GetSteppablePipeline()
+
+ # Only needed in END, but for propery validation we open it during begin
+ $exporter = { Set-PSFFileContent -Path $Path -Encoding $Encoding }.GetSteppablePipeline()
+
+ try { $converter.Begin($true) }
+ catch { $PSCmdlet.ThrowTerminatingError($_) }
+
+ try { $exporter.Begin($true) }
+ catch { $PSCmdlet.ThrowTerminatingError($_) }
+ }
+ process {
+ $converter.Process($InputObject)
+ }
+ end {
+ $json = $converter.End()
+ try { $exporter.Process($json) }
+ catch { $PSCmdlet.WriteError($_) }
+
+ $exporter.End()
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/data/Export-PSFPowerShellDataFile.ps1 b/PSFramework/functions/data/Export-PSFPowerShellDataFile.ps1
new file mode 100644
index 00000000..a22ff6a7
--- /dev/null
+++ b/PSFramework/functions/data/Export-PSFPowerShellDataFile.ps1
@@ -0,0 +1,81 @@
+function Export-PSFPowerShellDataFile {
+ <#
+ .SYNOPSIS
+ Exports data into psd1 config files.
+
+ .DESCRIPTION
+ Exports data into psd1 config files.
+
+ Use Register-PSFPsd1Converter to extend/customize how this conversion happens.
+
+ .PARAMETER Path
+ The path where to write to.
+ The parent folder must exist.
+ May provide multiple paths.
+
+ .PARAMETER Depth
+ How many levels deep do you want to process sub-properties?
+ Defaults to 2
+
+ .PARAMETER Encoding
+ The encoding to write the text file in.
+ Defaults to: UTF8 (with BOM).
+
+ .PARAMETER EnableVerbose
+ Enables deep verbosity when processing objects.
+ By default, individual conversion steps are not tracked for performance reasons.
+ Enable this for extensive amounts of debug messages.
+
+ .PARAMETER Configuration
+ Additional configuration settings to provide for the conversion.
+ Custom converters may use these as implemented in their custom conversion.
+
+ .PARAMETER InputObject
+ The object(s) to convert and write to file.
+
+ .EXAMPLE
+ PS C:\> Get-ChildItem | Export-PSFPowerShellDataFile -Path .\files.psd1
+
+ Takes all files and folders and converts the data into psd1-style data structures, then write that to "files.psd1" in the current path..
+ #>
+ [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "")]
+ [CmdletBinding()]
+ param (
+ [Parameter(Mandatory = $true)]
+ [PSFNewFile]
+ $Path,
+
+ [int]
+ $Depth = 2,
+
+ [PSFArgumentCompleter('PSFramework-Encoding')]
+ [PSFEncoding]
+ $Encoding = 'UTF8',
+
+ [switch]
+ $EnableVerbose,
+
+ [Hashtable]
+ $Configuration = @{},
+
+ [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+ [AllowNull()]
+ $InputObject
+ )
+ begin {
+ $converter = [PSFramework.Data.Psd1Converter]::new()
+ $converter.Depth = $Depth
+ $converter.EnableVerbose = $EnableVerbose
+ $converter.Config = $Configuration
+ $converter.Cmdlet = $PSCmdlet
+
+ $writer = { Set-PSFFileContent -Path $Path -Encoding $Encoding }.GetSteppablePipeline()
+ $writer.Begin($true)
+ }
+ process {
+ $writer.Process($converter.Convert($InputObject))
+ }
+ end {
+ $writer.End()
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/data/Get-PSFFileContent.ps1 b/PSFramework/functions/data/Get-PSFFileContent.ps1
new file mode 100644
index 00000000..7f3e0995
--- /dev/null
+++ b/PSFramework/functions/data/Get-PSFFileContent.ps1
@@ -0,0 +1,292 @@
+function Get-PSFFileContent {
+ <#
+ .SYNOPSIS
+ Read the contents of a file.
+
+ .DESCRIPTION
+ Read the contents of a file.
+ This is a replacement for Get-Content, trading flexibility in return for focus.
+
+ Notably, it allows for consistent parameterization between PowerShell versions.
+
+ .PARAMETER Path
+ Path to the file(s) to read.
+
+ .PARAMETER LiteralPath
+ Literal Path to the file(s) to read.
+ This does NOT use wildcard expressions when evaluating paths.
+
+ .PARAMETER ReadCount
+ How man lines to include in a single return / dataset.
+ Set to 0 or less to return the entire file as a single string.
+ Example: When reading a file with 13 lines of text, setting "ReadCount" to 5 will return 3 strings: 2 strings of 5 lines each, one with the remaining 3.
+ Defaults to: 1
+
+ .PARAMETER TotalCount
+ How many datasets in total to return.
+ When specified, this allows limiting the returned amount of results.
+ This parameter takes ReadCount into account, not counting individual lines of text, but number of result-sets after considering ReadCount.
+
+ Example 1: File: 50 Lines, ReadCount: 1, TotalCount: 20
+ In this case, the first 20 lines of the text file are returned
+
+ Example 2: File: 50 Lines, ReadCount: 3, TotalCount: 10
+ In this case, the first 10 results of 3-line strings are returned (resulting in 10 strings, covering a total of 30 lines of the text file).
+
+ .PARAMETER Skip
+ How many dataset to skip.
+ The size of a dataset depends on the ReadCount parameter.
+ Skips the first X datasets, unless combined with "Last", in which case it will skip the last X datasets instead.
+
+ .PARAMETER Last
+ Only return the last X datasets from the file.
+ The size of a dataset depends on the ReadCount parameter.
+
+ .PARAMETER AsByteStream
+ Return the content of the file as a binary stream.
+ This parameter changes the behavior of many other parameters, as it is not compatible with "-ReadCount".
+ Each dataset is now always a single byte.
+
+ Example: TotalCount: 48, Skip: 12
+ In this example, it will skip the first 12 bytes in the file and then return the next 48 (or less, if there are fewer bytes in the file in total).
+
+ .PARAMETER Wait
+ Rather than execute the command and then return, wait for some time and keep looking for new entries to be added to the file.
+ This will return new lines / datasets as they are added to the file.
+ This command will look every second for new content in the file.
+
+ .PARAMETER Timeout
+ The amount of time to wait before stopping waiting for new content in the file.
+ Defaults to: 1 hour.
+
+ .PARAMETER Encoding
+ The encoding to interpret the text file under.
+ Has no effect when using "-AsByteStream".
+ Defaults to: UTF8 (with BOM).
+
+ .EXAMPLE
+ PS C:\> Get-PSFFileContent .\response.json | ConvertFrom-Json
+
+ Read a json file and convert into useful objects.
+
+ .EXAMPLE
+ PS C:\> Get-PSFFileContent .\service-2025-08-14.log -Last 20 -Wait
+
+ Read the last 20 lines in the specified logfile, then wait for more lines as they are written to the file.
+
+ .EXAMPLE
+ PS C:\> $certBytes = Get-PSFFileContent -Path .\cert.cer -AsByteStream
+
+ Reads the bytes from the specified certificate file.
+ #>
+ [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseOutputTypeCorrectly", "")]
+ [CmdletBinding(DefaultParameterSetName = 'Text')]
+ param (
+ [Parameter(Position = 0, ValueFromPipeline = $true)]
+ [PSFFile]
+ $Path,
+
+ [PSFLiteralPath]
+ $LiteralPath,
+
+ [Parameter(ParameterSetName = 'Text')]
+ [long]
+ $ReadCount = 1,
+
+ [long]
+ $TotalCount,
+
+ [long]
+ $Skip,
+
+ [long]
+ $Last,
+
+ [Parameter(Mandatory = $true, ParameterSetName = 'Bytes')]
+ [switch]
+ $AsByteStream,
+
+ [switch]
+ $Wait,
+
+ [PSFTimeSpan]
+ $Timeout = '1h',
+
+ [Parameter(ParameterSetName = 'Text')]
+ [PSFArgumentCompleter('PSFramework-Encoding')]
+ [PSFEncoding]
+ $Encoding = 'UTF8'
+ )
+ begin {
+ #region Utility Functions
+ function Read-Stream {
+ [CmdletBinding()]
+ param (
+ [System.IO.StreamReader]
+ $Reader,
+
+ [int]
+ $ReadCount,
+
+ [int]
+ $Count,
+
+ [switch]
+ $All,
+
+ [hashtable]
+ $Counter = @{ Total = 0 }
+ )
+
+ $currentCount = 0
+ while (
+ -not $Reader.EndOfStream -and
+ (
+ ($Count -lt 1) -or
+ ($currentCount -lt $Count)
+ ) -and
+ (
+ (-not $Counter.Limit) -or
+ ($Counter.Limit -lt 1) -or
+ ($Counter.Limit -gt $Counter.Total)
+ )
+ ) {
+ $lines = foreach ($index in 1..$ReadCount) {
+ if (-not $Reader.EndOfStream) { $Reader.ReadLine() }
+ }
+ $lines -join "`n"
+ $currentCount++
+ $Counter.Total++
+
+ if (-not $All -and $PSBoundParameters.Keys -notcontains 'Count') { break }
+ }
+ }
+ #endregion Utility Functions
+
+ $first = $true
+ }
+ process {
+ if ($first) {
+ $files = $Path + $LiteralPath | Remove-PSFNull
+ $first = $false
+ }
+ else { $files = $Path }
+
+ :main foreach ($filePath in $files) {
+ #region Binary Read
+ if ($AsByteStream) {
+ try { $fileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, ([System.IO.FileShare]'ReadWrite, Delete')) }
+ catch {
+ $PSCmdlet.WriteError($_)
+ continue
+ }
+
+ $start = 0
+ $end = $fileStream.Length
+ if ($PSBoundParameters.Keys -contains 'Last') {
+ $start = $end - $Last
+ if ($Skip -gt 0) {
+ $start = $start - $Skip
+ $end = $end - $Skip
+ }
+ }
+ elseif ($PSBoundParameters.Keys -contains 'TotalCount') {
+ $end = $start + $TotalCount
+ if ($Skip -gt 0) {
+ $start = $start + $Skip
+ $end = $end + $Skip
+ }
+ }
+ if ($start -lt 0) { $start = 0 }
+ if ($end -gt $fileStream.Length) { $end = $fileStream.Length }
+ if ($start -eq $end) { continue }
+
+ $length = $end - $start
+
+ $buffer = [byte[]]::new($length)
+
+ try {
+ $fileStream.Position = $Start
+ $null = $fileStream.Read($buffer, 0, $Length)
+ , $buffer
+ }
+ catch { $PSCmdlet.WriteError($_) }
+ finally {
+ $fileStream.Close()
+ $fileStream.Dispose()
+ }
+
+ continue
+ }
+ #endregion Binary Read
+
+ #region Text Read
+ try { $fileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, ([System.IO.FileShare]'ReadWrite, Delete')) }
+ catch {
+ $PSCmdlet.WriteError($_)
+ continue
+ }
+ $reader = [System.IO.StreamReader]::new($fileStream, $Encoding)
+
+ try {
+ if ($PSBoundParameters.Keys -contains 'Last') {
+ $lines = [PSFramework.Utility.LimitedConcurrentQueue[string]]::new(($Last + $Skip))
+ foreach ($result in Read-Stream -Reader $reader -ReadCount $ReadCount -All) {
+ $lines.Enqueue($result)
+ }
+ $total = $Last - ($lines.Size - $lines.Count)
+ # We skipped more than we had
+ if ($total -lt 1) { continue main }
+
+ @($($lines))[0..($total - 1)]
+ }
+
+ if ($Skip -gt 1) {
+ $null = Read-Stream -Reader $reader -ReadCount $ReadCount -Count $Skip
+ }
+ if ($reader.EndOfStream -and -not $Wait) { continue main }
+
+ $counter = @{
+ Total = 0
+ Limit = $TotalCount
+ }
+
+ if (-not $reader.EndOfStream) {
+ if ($ReadCount -lt 1) {
+ $reader.ReadToEnd().Trim("`n`r")
+ if (-not $Wait) { continue main }
+ }
+ else {
+ Read-Stream -Reader $reader -ReadCount $ReadCount -All -Counter $counter
+ }
+ }
+
+ if (-not $Wait) { continue main }
+
+ $start = Get-Date
+ $timeLimit = $start.Add($Timeout)
+
+ while (
+ (
+ ($TotalCount -le 0) -or
+ ($counter.Total -lt $counter.Limit)
+ ) -and
+ (([datetime]::Now) -lt $timeLimit)
+ ) {
+ if (-not $reader.EndOfStream) {
+ Read-Stream -Reader $reader -ReadCount $ReadCount -All -Counter $counter
+ }
+ Start-Sleep -Seconds 1
+ }
+ }
+ catch {
+ $PSCmdlet.WriteError($_)
+ }
+ finally {
+ $fileStream.Close()
+ $fileStream.Dispose()
+ }
+ #endregion Text Read
+ }
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/data/Import-PSFJson.ps1 b/PSFramework/functions/data/Import-PSFJson.ps1
new file mode 100644
index 00000000..02e3d49e
--- /dev/null
+++ b/PSFramework/functions/data/Import-PSFJson.ps1
@@ -0,0 +1,215 @@
+function Import-PSFJson {
+ <#
+ .SYNOPSIS
+ Imports a json document from file and offers its content as objects.
+
+ .DESCRIPTION
+ Imports a json document from file and offers its content as objects.
+
+ WARNING: The FixData parameter is experimental and may experience breaking changes!
+
+ .PARAMETER Path
+ Path to the file to import.
+ Will evaluate wildcards.
+
+ .PARAMETER LiteralPath
+ Path to the file to import.
+ Will NOT evaluate wildcards.
+
+ .PARAMETER Encoding
+ The encoding of the file to read.
+ Defaults to UTF8.
+
+ .PARAMETER AsHashtable
+ Return content as hashtable, rather than PSCustomObject
+
+ .PARAMETER FixData
+ EXPERIMENTAL PARAMETER, MAY SUFFER BREAKING CHANGES
+ Attempt to fix broken data from the data processed.
+ Assumes the json was originally generated through PowerShell and tries to detect and fix issues that happened during export.
+ Most notably: Timestamps no longer being proper timestamps.
+
+ .EXAMPLE
+ PS C:\> Import-PSFJson .\policies.json
+
+ Reads the content of policies.json, parses its structure and returns objects representing its content.
+ #>
+ [CmdletBinding()]
+ param (
+ [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
+ [PSFFileLax]
+ $Path,
+
+ [PSFLiteralPath]
+ $LiteralPath,
+
+ [PSFArgumentCompleter('PSFramework-Encoding')]
+ [PSFEncoding]
+ $Encoding = 'UTF8',
+
+ [switch]
+ $AsHashtable,
+
+ [switch]
+ $FixData
+ )
+ begin {
+ #region Functions
+ function ConvertTo-Hashtable {
+ [OutputType([hashtable])]
+ [CmdletBinding()]
+ param (
+ [Parameter(ValueFromPipeline = $true)]
+ $InputObject
+ )
+
+ begin {
+ $jsonTypes = @(
+ 'System.String'
+ 'System.Int32'
+ 'System.Int64'
+ 'System.Double'
+ 'System.Bool'
+ 'System.DateTime'
+ )
+ }
+ process {
+ $hashtable = $InputObject | ConvertTo-PSFHashtable
+ foreach ($pair in $hashtable.GetEnumerator()) {
+ if ($null -eq $pair.Value) { continue }
+ if ($pair.Value.GetType().FullName -in $jsonTypes) { continue }
+ if ($pair.Value -is [object[]]) {
+ $pair.Value = foreach ($value in $pair.Value) {
+ if ($null -eq $value) { $null; continue }
+ if ($value.GetType().FullName -in $jsonTypes) { $value; continue }
+ if ($value -is [object[]]) { $value; continue } # Accept not resolving double-nested arrays for simplicity
+ ConvertTo-Hashtable -InputObject $value
+ }
+ continue
+ }
+ $pair.Value = ConvertTo-Hashtable -InputObject $pair.Value
+ }
+ $hashtable
+ }
+ }
+ function Convert-JsonData {
+ [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseOutputTypeCorrectly", "")]
+ [CmdletBinding()]
+ param (
+ [Parameter(ValueFromPipeline = $true)]
+ $Data
+ )
+
+ begin {
+ $jsonTypes = @(
+ 'System.String'
+ 'System.Int32'
+ 'System.Int64'
+ 'System.Double'
+ 'System.Bool'
+ 'System.DateTime'
+ )
+ }
+ process {
+ if ($null -eq $Data) { return }
+
+ if ($Data -is [object[]]) {
+ ,@(ConvertFrom-JsonArray -Data $Data)
+ return
+ }
+
+ if ($Data -is [hashtable]) { $properties = $Data.Keys }
+ else { $properties = $Data.PSObject.Properties.Name }
+
+ foreach ($property in $properties) {
+ $item = $Data.$property
+ if ($null -eq $item) { continue }
+ if ($item -is [string] -and $item -match '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{7}\+\d{2}:\d{2}$') {
+ $Data.$Property = $item -as [datetime]
+ continue
+ }
+ if ($item.GetType().FullName -in $jsonTypes) { continue }
+ if ($item -is [object[]]) {
+ $Data.$property = @(ConvertFrom-JsonArray -Data $item)
+ continue
+ }
+
+ # DateTime vNext
+ if (
+ $($item.PSObject.Properties).Count -eq 3 -and
+ $item.PSObject.Properties.Name -contains 'value' -and
+ $item.PSObject.Properties.Name -contains 'DisplayHint' -and
+ $item.PSObject.Properties.Name -contains 'DateTime' -and
+ $item.value -is [datetime]
+ ) {
+ $Data.$property = $item.value
+ continue
+ }
+
+ $Data.$property = Convert-JsonData -Data $item
+ }
+
+ $Data
+ }
+ }
+ function ConvertFrom-JsonArray {
+ [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseOutputTypeCorrectly", "")]
+ [CmdletBinding()]
+ param (
+ $Data
+ )
+
+ $jsonTypes = @(
+ 'System.String'
+ 'System.Int32'
+ 'System.Double'
+ 'System.Bool'
+ 'System.DateTime'
+ )
+
+ foreach ($item in $Data) {
+ if ($null -eq $item) { $null; continue }
+ if ($item -is [string] -and $item -match '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{7}\+\d{2}:\d{2}$') {
+ $item -as [datetime]
+ continue
+ }
+ if ($item.GetType().FullName -in $jsonTypes) { $item; continue }
+ if ($item -is [object[]]) { ,@(ConvertFrom-JsonArray -Data $item); continue }
+ if (
+ $item.PSObject.Properties.Count -eq 3 -and
+ $item.PSObject.Properties.Name -contains 'value' -and
+ $item.PSObject.Properties.Name -contains 'DisplayHint' -and
+ $item.PSObject.Properties.Name -contains 'DateTime' -and
+ $item.value -is [datetime]
+ ) {
+ $item.value
+ continue
+ }
+ Convert-JsonData -Data $item
+ }
+ }
+ #endregion Functions
+ }
+ process {
+ foreach ($entry in $Path.FailedInput) {
+ Write-Error "Could not resolve as file: $entry"
+ }
+
+ foreach ($filePath in $Path + $LiteralPath) {
+ $content = Get-PSFFileContent -LiteralPath $filePath -Encoding $Encoding
+ if (-not $AsHashtable) { $data = $content | ConvertFrom-Json }
+ else {
+ if ($PSVersionTable.PSVersion.Major -gt 5) { $data = $content | ConvertFrom-Json -AsHashtable }
+ else { $data = $content | ConvertFrom-Json | ConvertTo-Hashtable }
+ }
+
+ if (-not $FixData) {
+ $data
+ continue
+ }
+
+ # Fix Data (expensive)
+ Convert-JsonData -Data $data
+ }
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/utility/Import-PSFPowerShellDataFile.ps1 b/PSFramework/functions/data/Import-PSFPowerShellDataFile.ps1
similarity index 98%
rename from PSFramework/functions/utility/Import-PSFPowerShellDataFile.ps1
rename to PSFramework/functions/data/Import-PSFPowerShellDataFile.ps1
index b8679b82..4fb80f9d 100644
--- a/PSFramework/functions/utility/Import-PSFPowerShellDataFile.ps1
+++ b/PSFramework/functions/data/Import-PSFPowerShellDataFile.ps1
@@ -86,8 +86,10 @@
$jsonTypes = @(
'System.String'
'System.Int32'
+ 'System.Int64'
'System.Double'
'System.Bool'
+ 'System.DateTime'
)
}
process {
@@ -96,12 +98,12 @@
if ($null -eq $pair.Value) { continue }
if ($pair.Value.GetType().FullName -in $jsonTypes) { continue }
if ($pair.Value -is [object[]]) {
- $pair.Value = foreach ($value in $pair.Value) {
+ $pair.Value = @(foreach ($value in $pair.Value) {
if ($null -eq $value) { $null; continue }
if ($value.GetType().FullName -in $jsonTypes) { $value; continue }
if ($value -is [object[]]) { $value; continue } # Accept not resolving double-nested arrays for simplicity
ConvertTo-Hashtable -InputObject $value
- }
+ })
continue
}
$pair.Value = ConvertTo-Hashtable -InputObject $pair.Value
diff --git a/PSFramework/functions/data/Register-PSFPsd1Converter.ps1 b/PSFramework/functions/data/Register-PSFPsd1Converter.ps1
new file mode 100644
index 00000000..5df324dc
--- /dev/null
+++ b/PSFramework/functions/data/Register-PSFPsd1Converter.ps1
@@ -0,0 +1,145 @@
+function Register-PSFPsd1Converter {
+ <#
+ .SYNOPSIS
+ Registers a new piece of logic used to convert specific data types to PSD1 format.
+
+ .DESCRIPTION
+ Registers a new piece of logic used to convert specific data types to PSD1 format.
+ This is used by ConvertTo-PSFPsd1 or Export-PSFPowerShellDataFile.
+
+ There are two fundamental ways to define these extensions:
+ - Provide a data type written in C#
+ - Provide a Scriptblock
+
+ In either way, they target a specific datatype that they will convert.
+ When processing elements in a object into a psd1 document, each element - property value or value of a subproperty - is processed based on its data type.
+ The decision tree is thus processed:
+ - Is it null? Then do '$null'
+ - Is it an Enum? Then do "''"
+ - Do we have a converter defined for this exact type? If so, use it.
+ - Is it a dictionary / hashtable? Then use the predefined converter for that
+ - Do we have a converter defined for a type the input can be assigned to (Parent Type, Interface, etc.)? If so, use it (in case of multiple matches, a random one is picked).
+ - Use the predefined default converter for all other PowerShell objects.
+
+ This means, even if you define a converter for a specific interface, if the object processed is also a dictionary, your converter will be ignored.
+
+ > Data Type written in C#
+ For this, you need to define a class implementing the interface: PSFramework.Data.IPsd1Converter
+ Which essentially requires a single "Convert" method to return the string that becomes part of the PSD1 document.
+
+ > Scriptblock
+ A scriptblock as a converter is a fairly simple thing and allows you to do your conversion in script.
+ The item to convert is found under "$_", the scriptblock must return the result string as output.
+ More details on the parameter "Code"'s documentation.
+ ScriptBlocks offer inherently worse performance than C#-based converters.
+
+ .PARAMETER AssignedType
+ The type that should be converted.
+ The same converter can be assigned to multiple types.
+ Can be either a direct datatype or an interface, affecting all types implementing that type.
+ In case of a direct datatype, classes inheriting from that type will also be affected, unless a direct assignments overrides this.
+
+ .PARAMETER Code
+ The script-code that should convert data into PSD1 string.
+ There are several special considerations when implementing this:
+
+ - The value to convert is in the automatic "$_" variable.
+ - It receives two arguments: "Depth" & "Converter"
+ - Depth is current indentation level, each number representing 4 whitespaces. A Depth of 2 becomes 8 whitespaces.
+ - Converter is the entire conversion runtime and offers some tooling for your scriptblock (covered below)
+ - The automatic "$this" variable contains a hashtable with all details, including a few important properties:
+ - "Parents" are parent objects. This fills up as we delve into sub-properties and sub-properties of sub-properties.
+ The Parents are used to determine depth levels compared to the "MaxDepth" property on the Converter. Use this to determine, whether to truncate your results due to depth being exceeded.
+ It also should be used to prevent infinite recursion - if your current object is already part of the parents, stop this from continuing.
+ - "Converter" is the same thing as the argument received.
+ - "Properties" is a hashtable with settings defined with the script converter. Intended for if you want to provide some data with your conversion scriptblock.
+ - "Depth" is the current indentation depth, which is not necessarily the same as the nested property depth used to determine, when to truncate the result.
+ - "Value" is the exact same thing as what is already available in "$_"
+ - The scriptblock must return a string, and only the first output element will be considered
+
+ > Converter
+ The converter object manages the runtime and offers some settings and methods that may be useful:
+ It has the "Convert" method, which allows you to use the conversion system for some of the properties on your object, while doing your own thing on the others.
+ This method comes with two overloads:
+
+ Convert(System.Object Value)
+ Convert(System.Object Value, System.Object[] Parents, int Depth)
+
+ Generally, you want to use the latter one, to ensure MaxDepth, recursion protection and indentation levels remain consistent.
+
+ It also comes with an "EscapeQuotes" method, that allows you to safely escape single-quotes (and not just the ones on your keyboard, but also typographic/"curly" ones).
+ The "MaxDepth" property gives you access to the maximum nested property depth the user wanted to serialize. It's up to you to actually respect that (or not, as you chose).
+ Note: MaxDepth should not be compared to "Depth" (which is the indentation depth), but rather to the number of items in "Parents".
+
+ Finally, the "Config" property on the converter allows your converter scriptblock to accept config settings at the conversion level, rather than on the converter (which would be constant for _all_ conversions).
+ It is a hashtable users may chose to provide when calling ConvertTo-PSFPsd1 or Export-PSFPowerShellDataFile.
+
+ .PARAMETER DefaultResult
+ The default result to use when the scriptblock runs into a terminating error.
+ Will not actually be applied, unless "OnErrorDefault" is set.
+ Defaults to: '$null'
+
+ .PARAMETER OnErrorDefault
+ When the converter fails with a terminating error, use the default value, rather than kill the conversion.
+ By default, an error during a conversion scriptblock will fail the entire transforamtion.
+
+ .PARAMETER Properties
+ A hashtable of extra information to provide to the conversion scriptblock.
+ This data will be the same in all conversion calls, no matter the object being processed.
+ See the description for the code parameter on how to access per-conversion config settings.
+
+ .PARAMETER Converter
+ The instance of a fully implemented (in c#) Converter.
+ It comes with properties and behaviors as you defined it.
+
+ .EXAMPLE
+ Register-PSFPsd1Converter -Code { "'{0}'" -f $this.Converter.EscapeQuotes($_.ComputerName) } -AssignedType ([PSFramework.Parameter.ComputerParameter])
+
+ Registers a converter that will take the [PSFComputer] parameter class and serialize it into the ComputerName, no matter what data was provided for it.
+ #>
+ [CmdletBinding(DefaultParameterSetName = 'Script')]
+ param (
+ [Parameter(Mandatory = $true)]
+ [Type[]]
+ $AssignedType,
+
+ [Parameter(Mandatory = $true, ParameterSetName = 'Script')]
+ [PsfScriptblock]
+ $Code,
+
+ [Parameter(ParameterSetName = 'Script')]
+ [string]
+ $DefaultResult = '$null',
+
+ [Parameter(ParameterSetName = 'Script')]
+ [switch]
+ $OnErrorDefault,
+
+ [Parameter(ParameterSetName = 'Script')]
+ [hashtable]
+ $Properties,
+
+ [Parameter(Mandatory = $true, ParameterSetName = 'Binary')]
+ [PSFramework.Data.IPsd1Converter]
+ $Converter
+ )
+ process {
+ if ($Converter) {
+ foreach ($assignee in $AssignedType) {
+ [PSFramework.Data.DataHost]::Converters[$assignee] = $Converter
+ }
+ return
+ }
+
+ foreach ($assignee in $AssignedType) {
+ $newConverter = [PSFramework.Data.Converters.CustomConverter]::new(
+ $assignee,
+ $Code
+ )
+ $newConverter.DefaultResult = $DefaultResult
+ $newConverter.OnErrorDefault = $OnErrorDefault
+ $newConverter.Properties = $Properties
+ [PSFramework.Data.DataHost]::Converters[$newConverter.AssignedType] = $newConverter
+ }
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/data/Set-PSFFileContent.ps1 b/PSFramework/functions/data/Set-PSFFileContent.ps1
new file mode 100644
index 00000000..98d9ddb9
--- /dev/null
+++ b/PSFramework/functions/data/Set-PSFFileContent.ps1
@@ -0,0 +1,135 @@
+function Set-PSFFileContent {
+ <#
+ .SYNOPSIS
+ Writes content to a file.
+
+ .DESCRIPTION
+ Writes content to a file.
+ This is a replacement for Set-Content, trading flexibility in return for focus.
+
+ Notably, it allows for consistent parameterization between PowerShell versions.
+
+ .PARAMETER Path
+ The file(s) to write to.
+ Supports multiple files, at least the folder must exist.
+
+ .PARAMETER InputObject
+ The content to write.
+ By default, this content will be converted to string and written as a line per object.
+
+ .PARAMETER AsByteStream
+ Instead of writing the content as a text file, write it as a binary blob.
+ This requires the input to be valid bytes!
+ Note: Writing binary filas via input from pipeline is SIGNIFICANTLY slower than providing the bytes as an explicitly bound parameter.
+
+ .PARAMETER Encoding
+ The encoding to write the text file in.
+ Has no effect when using "-AsByteStream".
+ Defaults to: UTF8 (with BOM).
+
+ .PARAMETER NewLine
+ The symbols to use as NewLine.
+ The usual key consideration here is whether to include the carriage return (`r) or not.
+ Defaults to: "`n"
+ If you wish to include the carriage return, set it to "`r`n".
+
+ .PARAMETER Append
+ Whether to append your content to an existing file.
+ Still creates the file, if it does not exist.
+ By default, all previous content will be overwritten.
+
+ .PARAMETER NoFlush
+ Do not flush the contents of the files to disk, as you write them.
+ By default, all contents - lines or bytes - are immediately written to disk ("Flushed"), to ensure no data is lost, in case of the pipeline failing.
+ This increase in data assurance comes at an increased performance cost.
+ Setting this parameter means it will only at the end, when all content has been sent, flush the contents to disk.
+
+ .EXAMPLE
+ PS C:\> Get-MgUser | ConvertTo-Json | Set-PSFFileContent -Path .\users.json
+
+ Writes all users in the tenant as json to disk.
+
+ .EXAMPLE
+ PS C:\> $cert.GetRawCertData() | Set-PSFFileContent -Path .\cert.cer -AsByteStream
+
+ Writes the raw certificate information as a .cer file to disk.
+ This will result in a perfectly valid public certificate.
+ #>
+ [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
+ [CmdletBinding()]
+ param (
+ [Parameter(Mandatory = $true)]
+ [PSFNewFile]
+ $Path,
+
+ [Parameter(ValueFromPipeline = $true)]
+ [AllowEmptyString()]
+ [object[]]
+ $InputObject,
+
+ [switch]
+ $AsByteStream,
+
+ [PSFArgumentCompleter('PSFramework-Encoding')]
+ [PSFEncoding]
+ $Encoding = 'UTF8',
+
+ [string]
+ $NewLine = "`n",
+
+ [switch]
+ $Append,
+
+ [switch]
+ $NoFlush
+ )
+ begin {
+ $mode = 'Create'
+ if ($Append) { $mode = 'OpenOrCreate' }
+
+ try {
+ $writers = foreach ($filePath in $Path) {
+ $fileStream = [System.IO.FileStream]::new($filePath, $mode, 'ReadWrite', 'Read')
+ if ($Append) { $fileStream.Position = $fileStream.Length }
+ if ($AsByteStream) { $fileStream; continue }
+
+ $writer = [System.IO.StreamWriter]::new($fileStream, $Encoding)
+ if (-not $NoFlush) { $writer.AutoFlush = $true }
+ $writer.NewLine = $NewLine
+ $writer
+ }
+ }
+ catch {
+ $PSCmdlet.ThrowTerminatingError($_)
+ }
+ }
+ process {
+ if (-not $AsByteStream) {
+ foreach ($inputItem in $InputObject) {
+ foreach ($writer in $writers) {
+ try { $writer.WriteLine($inputItem) }
+ catch { $PSCmdlet.WriteError($_) }
+ }
+ }
+ }
+ else {
+ try { $bytes = [byte[]]$InputObject }
+ catch {
+ Write-Error "Not a byte-array: $InputObject! Cannot write as byte-stream! $_" -TargetObject $InputObject
+ return
+ }
+ foreach ($writer in $writers) {
+ try { $writer.Write($bytes, 0, $bytes.Length) }
+ catch { $PSCmdlet.WriteError($_) }
+ if (-not $NoFlush) { $writer.Flush() }
+ }
+ }
+ }
+ end {
+ foreach ($writer in $writers) {
+ $writer.Flush()
+ $writer.Close()
+ $writer.Dispose()
+ }
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/tabexpansion/Add-PSFTeppCompletion.ps1 b/PSFramework/functions/tabexpansion/Add-PSFTeppCompletion.ps1
new file mode 100644
index 00000000..7161d06c
--- /dev/null
+++ b/PSFramework/functions/tabexpansion/Add-PSFTeppCompletion.ps1
@@ -0,0 +1,53 @@
+function Add-PSFTeppCompletion {
+ <#
+ .SYNOPSIS
+ Adds a completion result to a tab completion script.
+
+ .DESCRIPTION
+ Adds a completion result to a tab completion script.
+ This allows specifically adding individual values to provide when completing, no matter the actual completion logic.
+ Use Register-PSFTeppScriptblock to define a new completion scriptblock.
+
+ .PARAMETER Name
+ Name of the tab completion scriptblock to add to.
+ Use Register-PSFTeppScriptblock to define a new completion scriptblock.
+
+ .PARAMETER Options
+ The completion objects to provide.
+ Provide either a basic string or a hashtable with some key/value pairs:
+ - Text: Mandatory. The text to complete.
+ - ToolTip: A friendly text to provide some context when completing using CTRL+Space.
+ - ListItemText: The text to show in the completion menu, but different from the actual text inserted.
+ - ToolTipString: A localization key to resolve into the currently configured language for the ToolTip.
+ - ListItemTextString: A localization key to resolve into the currently configured language for the ListItemText.
+
+ .EXAMPLE
+ PS C:\> Add-PSFTeppCompletion -Name 'Alcohol.Type' -Options Wine, Beer, Vodka
+
+ Adds these options to the specified completion results: Wine, Beer, Vodka
+
+ .EXAMPLE
+ PS C:\> Add-PSFTeppCompletion -Name 'Alcohol.Type' -Options @{ Text = 'Mead'; ToolTip = 'Elixir of the angry gods' }
+
+ Add a completion to the completer named "Alcohol.Type", offering the text "Mead" and explaining it with the specified tooltip.
+ #>
+ [CmdletBinding()]
+ param (
+ [PsfArgumentCompleter('PSFramework-tepp-scriptblockname')]
+ [PsfValidateSet(TabCompletion = 'PSFramework-tepp-scriptblockname')]
+ [Parameter(Mandatory = $true)]
+ [string]
+ $Name,
+
+ [Parameter(Mandatory = $true)]
+ [object[]]
+ $Options
+ )
+ process {
+ $completionScript = [PSFramework.TabExpansion.TabExpansionHost]::Scripts[$Name]
+ foreach ($option in $Options) {
+ if ($option -is [string]) { $completionScript.AddTraining($option) }
+ else { $completionScript.AddTraining(($option | ConvertTo-PSFHashtable)) }
+ }
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/tabexpansion/Get-PSFTeppCompletion.ps1 b/PSFramework/functions/tabexpansion/Get-PSFTeppCompletion.ps1
new file mode 100644
index 00000000..24e018da
--- /dev/null
+++ b/PSFramework/functions/tabexpansion/Get-PSFTeppCompletion.ps1
@@ -0,0 +1,52 @@
+function Get-PSFTeppCompletion {
+ <#
+ .SYNOPSIS
+ Lists the registered completion options.
+
+ .DESCRIPTION
+ Lists the registered completion options.
+ Using Add-PSFTeppCompletion, it is possible to manually provide values that will be offered during tab completion for a given argument completion script.
+ Alternatively, a completion scriptblock can be configured for "AutoTraining" during setup via "Register-PSFTeppScriptblock", which enables automatically
+ remembering values previously provided (By later calling Update-PSFTeppCompletion).
+
+ In either case, those values are stored in memory and retrieved using this command.
+
+ .PARAMETER Name
+ Name of the completer scriptblock, for which to retrieve registered options.
+ Defaults to *
+
+ .EXAMPLE
+ PS C:\> Get-PSFTeppCompletion
+
+ List all registered completion options for all completer scriptblocks.
+ #>
+ [CmdletBinding()]
+ param (
+ [PsfArgumentCompleter('PSFramework-tepp-scriptblockname')]
+ [Parameter(ValueFromPipeline = $true)]
+ [string[]]
+ $Name = '*'
+ )
+ begin {
+ $completerScripts = [PSFramework.TabExpansion.TabExpansionHost]::Scripts.Values
+ $processed = @{ }
+ }
+ process {
+ foreach ($entry in $Name) {
+ foreach ($completerScript in $completerScripts) {
+ if ($processed[$completerScript]) { continue }
+ if ($completerScript.Name -notlike $entry) { continue }
+
+ $processed[$completerScript] = $completerScript
+
+ foreach ($completionResult in $completerScript.Trained) {
+ if (-not $completionResult) { continue }
+ $newResult = $completionResult.Clone()
+ $newResult.PSTypeName = 'PSFramework.TabExpansion.CompletionData'
+ $newResult.Completion = $completerScript.Name
+ [PSCustomObject]$newResult
+ }
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/tabexpansion/New-PSFTeppCompletionResult.ps1 b/PSFramework/functions/tabexpansion/New-PSFTeppCompletionResult.ps1
index fc6af2fe..7e26b768 100644
--- a/PSFramework/functions/tabexpansion/New-PSFTeppCompletionResult.ps1
+++ b/PSFramework/functions/tabexpansion/New-PSFTeppCompletionResult.ps1
@@ -19,6 +19,9 @@
.PARAMETER CompletionResultType
The type of object that is being completed.
By default it generates one of type paramter value.
+
+ .PARAMETER AlwaysQuote
+ Always place quotes around results, whether the text has a whitespace or not.
.PARAMETER NoQuotes
Whether to put the result in quotes or not.
@@ -45,6 +48,9 @@
[System.Management.Automation.CompletionResultType]
$CompletionResultType = [System.Management.Automation.CompletionResultType]::ParameterValue,
+
+ [switch]
+ $AlwaysQuote,
[switch]
$NoQuotes
@@ -61,7 +67,10 @@
# not be included, via the -NoQuotes parameter,
# then skip adding quotes.
- if ($CompletionResultType -eq [System.Management.Automation.CompletionResultType]::ParameterValue -and -not $NoQuotes)
+ if ($AlwaysQuote -and $CompletionText -notmatch '^".+"$' -and $CompletionText -notmatch "^'.+'$") {
+ $CompletionText = "'$($CompletionText -replace "'","''")'"
+ }
+ elseif ($CompletionResultType -eq [System.Management.Automation.CompletionResultType]::ParameterValue -and -not $NoQuotes)
{
# Add single quotes for the caller in case they are needed.
# We use the parser to robustly determine how it will treat
diff --git a/PSFramework/functions/tabexpansion/Register-PSFTeppScriptblock.ps1 b/PSFramework/functions/tabexpansion/Register-PSFTeppScriptblock.ps1
index c75947a7..11aacccf 100644
--- a/PSFramework/functions/tabexpansion/Register-PSFTeppScriptblock.ps1
+++ b/PSFramework/functions/tabexpansion/Register-PSFTeppScriptblock.ps1
@@ -39,6 +39,22 @@
.PARAMETER Global
Whether the scriptblock should be executed in the global context.
This parameter is needed to reliably execute in background runspaces, but means no direct access to module content.
+
+ .PARAMETER MatchAnywhere
+ Match input against any part of the completion text, not just the beginning.
+
+ .PARAMETER FuzzyMatch
+ Apply FuzzyMatching to the legal completion text, not just direct word matching.
+
+ .PARAMETER AlwaysQuote
+ All completion results will be wrapped in quotes, not just the ones with a whitespace.
+
+ .PARAMETER DontSort
+ Completion results are no longer sorted alphabetically.
+
+ .PARAMETER AutoTraining
+ Automatically train the tab completion by caching user inputs.
+ Requires using Update-PSFTeppCompletion inside of the respective command, to automatically pick up new values.
.EXAMPLE
Register-PSFTeppScriptblock -Name "psalcohol-liquids" -ScriptBlock { "beer", "mead", "wine", "vodka", "whiskey", "rum" }
@@ -75,11 +91,32 @@
$CacheDuration = 0,
[switch]
- $Global
+ $Global,
+
+ [switch]
+ $MatchAnywhere,
+
+ [switch]
+ $FuzzyMatch,
+
+ [switch]
+ $AlwaysQuote,
+
+ [switch]
+ $DontSort,
+
+ [switch]
+ $AutoTraining
)
process
{
[PSFramework.TabExpansion.TabExpansionHost]::RegisterCompletion($Name, $ScriptBlock, $Mode, $CacheDuration, $Global)
+ $scriptContainer = [PSFramework.TabExpansion.TabExpansionHost]::Scripts[$Name]
+ if ($PSBoundParameters.Keys -contains 'MatchAnywhere') { $scriptContainer.MatchAnywhere = $MatchAnywhere }
+ if ($PSBoundParameters.Keys -contains 'FuzzyMatch') { $scriptContainer.MatchAnywhere = $FuzzyMatch }
+ if ($PSBoundParameters.Keys -contains 'AlwaysQuote') { $scriptContainer.MatchAnywhere = $AlwaysQuote }
+ if ($PSBoundParameters.Keys -contains 'DontSort') { $scriptContainer.MatchAnywhere = $DontSort }
+ if ($PSBoundParameters.Keys -contains 'AutoTraining') { $scriptContainer.AutoTraining = $AutoTraining }
}
}
diff --git a/PSFramework/functions/tabexpansion/Remove-PSFTeppCompletion.ps1 b/PSFramework/functions/tabexpansion/Remove-PSFTeppCompletion.ps1
new file mode 100644
index 00000000..53dc2a81
--- /dev/null
+++ b/PSFramework/functions/tabexpansion/Remove-PSFTeppCompletion.ps1
@@ -0,0 +1,46 @@
+function Remove-PSFTeppCompletion {
+ <#
+ .SYNOPSIS
+ Removes a previously added completion result from a tab completion script.
+
+ .DESCRIPTION
+ Removes a previously added completion result from a tab completion script.
+ These can be added using Add-PSFTeppCompletion or trained using Import-PSFTeppCompletion.
+ This command has no effect on automatically calculated tab completions!
+
+ .PARAMETER Name
+ Name of the tab completion scriptblock to remove from.
+ Use Register-PSFTeppScriptblock to define a new completion scriptblock.
+
+ .PARAMETER Options
+ The completion options to remove.
+ Must be either the string value of the completion or a hashtable with the "Text" key containing the completion value.
+
+ .EXAMPLE
+ PS C:\> Remove-PSFTeppCompletion -Name 'Alcohol.Type' -Options 'Mojito', 'Caipirinha'
+
+ Removes the two listed drinks from the list of legal completions.
+ #>
+ [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
+ [CmdletBinding()]
+ param (
+ [PsfArgumentCompleter('PSFramework-tepp-scriptblockname')]
+ [PsfValidateSet(TabCompletion = 'PSFramework-tepp-scriptblockname')]
+ [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
+ [Alias('Completion')]
+ [string]
+ $Name,
+
+ [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+ [object[]]
+ $Options
+ )
+
+ process {
+ $completionScript = [PSFramework.TabExpansion.TabExpansionHost]::Scripts[$Name]
+ foreach ($option in $Options) {
+ if ($option -is [string]) { $completionScript.RemoveTraining($option) }
+ else { $completionScript.RemoveTraining($option.Text) }
+ }
+ }
+}
\ No newline at end of file
diff --git a/PSFramework/functions/utility/New-PSFHashtable.ps1 b/PSFramework/functions/utility/New-PSFHashtable.ps1
index 20c4d725..781f47af 100644
--- a/PSFramework/functions/utility/New-PSFHashtable.ps1
+++ b/PSFramework/functions/utility/New-PSFHashtable.ps1
@@ -26,6 +26,13 @@
.PARAMETER DefaultValue
The default value returned by the hashtable, when resolving a key not specified on the hashtable.
+
+ .PARAMETER PassThru
+ When resolving a key not specified on the hashtable, return the key instead of nothing.
+
+ .PARAMETER Calculator
+ When resolving a key not specified on the hashtable, use this logic to determine the result.
+ Receives the key as its sole input / argument / $_
.EXAMPLE
PS C:\> New-PSFHashtable
@@ -42,22 +49,47 @@
PS C:\> New-PSFHashtable -Hashtable $originHash -DefaultValue $false
Returns a PSFHashtable that is a copy of the hashtable in $originHash, which will by default return $false when resolving undefined keys.
+
+ .EXAMPLE
+ PS C:\> New-PSFHashtable -Hashtable $originHash -PassThru
+
+ Returns a PSFHashtable that is a copy of the hashtable in $originHash, which will by default return the key itself when resolving undefined keys.
+
+ .EXAMPLE
+ PS C:\> New-PSFHashtable -Calculator { (Get-Volume | Sort-Object SizeRemaining -Descending)[0] }
+
+ Returns an empty PSFHashtable which will by default return the volume with the most space remaining.
#>
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
[OutputType([PSFramework.Object.PsfHashtable])]
- [CmdletBinding()]
+ [CmdletBinding(DefaultParameterSetName = 'Default')]
param (
[Hashtable]
$Hashtable = @{ },
+ [Parameter(ParameterSetName = 'Default')]
[object]
- $DefaultValue
+ $DefaultValue,
+
+ [Parameter(ParameterSetName = 'PassThru')]
+ [switch]
+ $PassThru,
+
+ [Parameter(ParameterSetName = 'Calculator')]
+ [scriptblock]
+ $Calculator
)
process {
$result = [PSFramework.Object.PsfHashtable]::new($Hashtable)
if ($PSBoundParameters.Keys -contains 'DefaultValue') {
$result.SetDefaultValue($DefaultValue)
}
+ if ($PassThru) {
+ $result.EnablePassthru()
+ }
+ if ($Calculator) {
+ $result.SetCalculator($Calculator)
+ }
$result
}
}
\ No newline at end of file
diff --git a/PSFramework/functions/utility/New-PSFSupportPackage.ps1 b/PSFramework/functions/utility/New-PSFSupportPackage.ps1
index 0146f501..1e67f416 100644
--- a/PSFramework/functions/utility/New-PSFSupportPackage.ps1
+++ b/PSFramework/functions/utility/New-PSFSupportPackage.ps1
@@ -199,32 +199,39 @@
$filePathXml = Join-Path -Path $outputPath -ChildPath "powershell_support_pack_$(Get-Date -Format "yyyy_MM_dd-HH_mm_ss").cliDat"
}
$filePathZip = $filePathXml -replace "\.cliDat$", ".zip"
+
+ $messageLevel = 'Important'
+ $headerLevel = 'Critical'
+ if ($TaskName) {
+ $messageLevel = 'Verbose'
+ $headerLevel = 'Verbose'
+ }
}
process
{
if (Test-PSFFunctionInterrupt) { return }
- Write-PSFMessage -Level Critical -String 'New-PSFSupportPackage.Header' -StringValues $filePathZip, (Get-PSFConfigValue -FullName 'psframework.supportpackage.contactmessage' -Fallback '')
+ Write-PSFMessage -Level $headerLevel -String 'New-PSFSupportPackage.Header' -StringValues $filePathZip, (Get-PSFConfigValue -FullName 'psframework.supportpackage.contactmessage' -Fallback '')
$hash = @{ }
if (($Include -band 1) -and -not ($Exclude -band 1))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.Messages'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.Messages'
$hash["Messages"] = Get-PSFMessage
}
if (($Include -band 2) -and -not ($Exclude -band 2))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.MsgErrors'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.MsgErrors'
$hash["Errors"] = Get-PSFMessage -Errors
}
if (($Include -band 4) -and -not ($Exclude -band 4))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.ConsoleBuffer'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.ConsoleBuffer'
$hash["ConsoleBuffer"] = Get-ShellBuffer
}
if (($Include -band 8) -and -not ($Exclude -band 8))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.OperatingSystem'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.OperatingSystem'
$hash["OperatingSystem"] = if ($IsLinux -or $IsMacOs)
{
[PSCustomObject]@{
@@ -244,12 +251,12 @@
{
$hash["CPU"] = if ($IsLinux -and (Test-Path -Path /proc/cpuinfo))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.CPU' -StringValues '/proc/cpuinfo'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.CPU' -StringValues '/proc/cpuinfo'
Get-Content -Raw -Path /proc/cpuinfo
}
else
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.CPU' -StringValues Win32_Processor
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.CPU' -StringValues Win32_Processor
Get-CimInstance -ClassName Win32_Processor
}
}
@@ -257,48 +264,48 @@
{
$hash["Ram"] = if ($IsLinux -and (Test-Path -Path /proc/meminfo))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.RAM' -StringValues '/proc/meminfo'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.RAM' -StringValues '/proc/meminfo'
Get-Content -Raw -Path /proc/meminfo
}
else
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.RAM' -StringValues Win32_PhysicalMemory
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.RAM' -StringValues Win32_PhysicalMemory
Get-CimInstance -ClassName Win32_PhysicalMemory
}
}
if (($Include -band 64) -and -not ($Exclude -band 64))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.PSVersion'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.PSVersion'
$hash["PSVersion"] = $PSVersionTable
}
if (($Include -band 128) -and -not ($Exclude -band 128))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.History'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.History'
$hash["History"] = Get-History
}
if (($Include -band 256) -and -not ($Exclude -band 256))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.Modules'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.Modules'
$hash["Modules"] = Get-Module
}
if ((($Include -band 512) -and -not ($Exclude -band 512)) -and ($PSVersionTable.PSVersion.Major -le 5))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.Snapins'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.Snapins'
$hash["SnapIns"] = Get-PSSnapin
}
if (($Include -band 1024) -and -not ($Exclude -band 1024))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.Assemblies'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.Assemblies'
$hash["Assemblies"] = [appdomain]::CurrentDomain.GetAssemblies() | Select-Object CodeBase, FullName, Location, ImageRuntimeVersion, GlobalAssemblyCache, IsDynamic
}
if (Test-PSFParameterBinding -ParameterName "Variables")
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.Variables' -StringValues ($Variables -join ", ")
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.Variables' -StringValues ($Variables -join ", ")
$hash["Variables"] = $Variables | Get-Variable -ErrorAction Ignore
}
if (($Include -band 2048) -and -not ($Exclude -band 2048) -and (-not $ExcludeError))
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.PSErrors'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.PSErrors'
$hash["PSErrors"] = @()
foreach ($errorItem in $global:Error) { $hash["PSErrors"] += New-Object PSFramework.Message.PsfException($errorItem) }
}
@@ -306,14 +313,14 @@
{
if (Test-Path function:Get-DbatoolsLog)
{
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.DbaTools.Messages'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.DbaTools.Messages'
$hash["DbatoolsMessages"] = Get-DbatoolsLog
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.DbaTools.Errors'
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.DbaTools.Errors'
$hash["DbatoolsErrors"] = Get-DbatoolsLog -Errors
}
foreach ($pair in $script:supportDataProviders.GetEnumerator()) {
- Write-PSFMessage -Level Important -String 'New-PSFSupportPackage.Extension.Collecting' -StringValues $pair.Key
+ Write-PSFMessage -Level $messageLevel -String 'New-PSFSupportPackage.Extension.Collecting' -StringValues $pair.Key
try { $hash["_$($pair.Key)"] = & $pair.Value }
catch {
Write-PSFMessage -Level Warning -String 'New-PSFSupportPackage.Extension.Collecting.Failed' -StringValues $pair.Key -ErrorRecord $_
diff --git a/PSFramework/internal/configurations/message.ps1 b/PSFramework/internal/configurations/message.ps1
index 2afa7713..6457426e 100644
--- a/PSFramework/internal/configurations/message.ps1
+++ b/PSFramework/internal/configurations/message.ps1
@@ -16,8 +16,10 @@ Set-PSFConfig -Module PSFramework -Name 'Developer.Mode.Enable' -Value $false -I
Set-PSFConfig -Module PSFramework -Name 'Message.Style.Breadcrumbs' -Value $false -Initialize -Validation "bool" -Handler { [PSFramework.Message.MessageHost]::EnableMessageBreadcrumbs = $_ } -Description "Controls how messages are displayed. Enables Breadcrumb display, showing the entire callstack. Takes precedence over command name display."
Set-PSFConfig -Module PSFramework -Name 'Message.Style.FunctionName' -Value $true -Initialize -Validation "bool" -Handler { [PSFramework.Message.MessageHost]::EnableMessageDisplayCommand = $_ } -Description "Controls how messages are displayed. Enables command name, showing the name of the writing command. Is overwritten by enabling breadcrumbs."
Set-PSFConfig -Module PSFramework -Name 'Message.Style.Timestamp' -Value $true -Initialize -Validation "bool" -Handler { [PSFramework.Message.MessageHost]::EnableMessageTimestamp = $_ } -Description "Controls how messages are displayed. Enables timestamp display, including a timestamp in each message."
+Set-PSFConfig -Module PSFramework -Name 'Message.Style.Target' -Value $false -Initialize -Validation "bool" -Handler { [PSFramework.Message.MessageHost]::EnableMessageTarget = $_ } -Description "Controls how messages are displayed. Include the message target (if present) in verbose message output."
Set-PSFConfig -Module PSFramework -Name 'Message.Style.Level' -Value $false -Initialize -Validation "bool" -Handler { [PSFramework.Message.MessageHost]::EnableMessageLevel = $_ } -Description "Controls how messages are displayed. Enables level display, including its level in each message."
Set-PSFConfig -Module PSFramework -Name 'Message.Style.NoColor' -Value $false -Initialize -Validation "bool" -Handler { [PSFramework.Message.MessageHost]::NoColor = $_ } -Description "Controls how messages are displayed. Disables colorization of the messages shown on screen. This prevents messages being broken into multiple lines on some agent system such as the universal console or Azure DevOps logs."
+Set-PSFConfig -Module PSFramework -Name 'Message.Style.TimeFormat' -Value 'HH:mm:ss' -Initialize -Validation "string" -Handler { [PSFramework.Message.MessageHost]::TimeFormat = $_ } -Description "Controls how messages are displayed. The format used in timestamps for messages written on screen"
Set-PSFConfig -Module PSFramework -Name 'Message.Style.Prefix' -Value $false -Initialize -Validation "bool" -Handler { [PSFramework.Message.MessageHost]::EnableMessagePrefix = $_ } -Description "Controls how messages are displayed. Enables message prefix display, including a prefix in each message."
Set-PSFConfig -Module PSFramework -Name 'Message.Style.Prefix.Error' -Value "##vso[task.logissue type=error;]" -Initialize -Validation "string" -Handler { [PSFramework.Message.MessageHost]::PrefixValueError = $_ } -Description "Prefix value to use when the level is Warning and the tag 'error' is supplied."
diff --git a/PSFramework/internal/configurations/tabexpansion.ps1 b/PSFramework/internal/configurations/tabexpansion.ps1
new file mode 100644
index 00000000..c85fad9b
--- /dev/null
+++ b/PSFramework/internal/configurations/tabexpansion.ps1
@@ -0,0 +1,4 @@
+# Settings around the Tab Expansion Experience
+Set-PSFConfig -Module PSFramework -Name 'TabExpansion.FuzzyMatch' -Value $false -Initialize -Handler { [PSFramework.TabExpansion.TabExpansionHost]::FuzzyMatch = $args[0] } -Validation 'bool' -Description 'Whether to match tab completions with Fuzzy-Matching by default.'
+Set-PSFConfig -Module PSFramework -Name 'TabExpansion.AlwaysQuote' -Value $false -Initialize -Handler { [PSFramework.TabExpansion.TabExpansionHost]::AlwaysQuote = $args[0] } -Validation 'bool' -Description 'Wrap all completion results into quotes, whitespace or not.'
+Set-PSFConfig -Module PSFramework -Name 'TabExpansion.MatchAnywhere' -Value $false -Initialize -Handler { [PSFramework.TabExpansion.TabExpansionHost]::MatchAnywhere = $args[0] } -Validation 'bool' -Description 'Whether to match tab completions with Fuzzy-Matching by default.'
\ No newline at end of file
diff --git a/PSFramework/internal/configurationschemata/metajson.ps1 b/PSFramework/internal/configurationschemata/metajson.ps1
index 79cd0bea..a18ffe4e 100644
--- a/PSFramework/internal/configurationschemata/metajson.ps1
+++ b/PSFramework/internal/configurationschemata/metajson.ps1
@@ -1,4 +1,4 @@
-Register-PSFConfigSchema -Name MetaJson -Schema {
+$code = {
param (
[string]
$Resource,
@@ -311,4 +311,6 @@
return
}
}
-}
\ No newline at end of file
+}
+Register-PSFConfigSchema -Name MetaJson -Schema $code
+Register-PSFConfigSchema -Name Psd1 -Schema $code
\ No newline at end of file
diff --git a/PSFramework/internal/loggingProviders/logfile.provider.ps1 b/PSFramework/internal/loggingProviders/logfile.provider.ps1
index 5358e9bb..9acbb4e0 100644
--- a/PSFramework/internal/loggingProviders/logfile.provider.ps1
+++ b/PSFramework/internal/loggingProviders/logfile.provider.ps1
@@ -15,16 +15,16 @@
)
$hash = @{
- '%date%' = (Get-Date -Format 'yyyy-MM-dd')
- '%dayofweek%' = (Get-Date).DayOfWeek
- '%day%' = (Get-Date).Day
- '%hour%' = (Get-Date).Hour
- '%minute%' = (Get-Date).Minute
- '%username%' = $env:USERNAME
- '%userdomain%' = $env:USERDOMAIN
+ '%date%' = (Get-Date -Format 'yyyy-MM-dd')
+ '%dayofweek%' = (Get-Date).DayOfWeek
+ '%day%' = (Get-Date).Day
+ '%hour%' = (Get-Date).Hour
+ '%minute%' = (Get-Date).Minute
+ '%username%' = $env:USERNAME
+ '%userdomain%' = $env:USERDOMAIN
'%computername%' = $env:COMPUTERNAME
- '%processid%' = $PID
- '%logname%' = $logname
+ '%processid%' = $PID
+ '%logname%' = $logname
}
$hash.$Match
@@ -64,84 +64,93 @@
$MessageItem
)
- #region Type-Based Output
- switch ($FileType) {
- #region Csv
- "Csv"
- {
- if (-not $CsvDelimiter) {
- $CsvDelimiter = ','
- }
+ process {
+ #region Type-Based Output
+ switch ($FileType) {
+ #region Csv
+ "Csv" {
+ if (-not $CsvDelimiter) {
+ $CsvDelimiter = ','
+ }
- if ($script:firstEntry) {
- if ($script:csvConverter) {
- $null = $script:csvConverter.End()
- $script:csvConverter = $null
+ if ($script:firstEntry) {
+ if ($script:csvConverter) {
+ $null = $script:csvConverter.End()
+ $script:csvConverter = $null
+ }
}
+ if (-not $script:csvConverter) {
+ $script:csvConverter = { ConvertTo-Csv -NoTypeInformation -Delimiter $CsvDelimiter }.GetSteppablePipeline()
+ $script:csvConverter.Begin($true)
+ }
+ $converted = $script:csvConverter.Process($Message)
+ if ($script:firstEntry) {
+ if ($IncludeHeader -and (Test-EmptyFile -Path $script:currentPath)) { $script:writer.WriteLine($converted[0]) }
+ $script:writer.WriteLine($converted[1])
+ }
+ else { $script:writer.WriteLine($converted[0]) }
}
- if (-not $script:csvConverter) {
- $script:csvConverter = { ConvertTo-Csv -NoTypeInformation -Delimiter $CsvDelimiter }.GetSteppablePipeline()
- $script:csvConverter.Begin($true)
- }
- $converted = $script:csvConverter.Process($Message)
- if ($script:firstEntry) {
- if ($IncludeHeader -and (Test-EmptyFile -Path $script:currentPath)) { $script:writer.WriteLine($converted[0]) }
- $script:writer.WriteLine($converted[1])
- }
- else { $script:writer.WriteLine($converted[0]) }
- }
- #endregion Csv
- #region Json
- "Json"
- {
- if (-not $script:JsonSettings.JsonString) { $data = $Message | ConvertTo-Json -Compress:$script:JsonSettings.JsonCompress }
- else { $data = $Message | ConvertFrom-Enumeration | ConvertTo-Json -Compress:$script:JsonSettings.JsonCompress }
+ #endregion Csv
+ #region Json
+ "Json" {
+ if (-not $script:JsonSettings.JsonString) { $data = $Message | ConvertTo-Json -Compress:$script:JsonSettings.JsonCompress }
+ else { $data = $Message | ConvertFrom-Enumeration | ConvertTo-Json -Compress:$script:JsonSettings.JsonCompress }
- if (-not $script:JsonSettings.JsonNoComma) {
- $script:writer.WriteLine(",")
- $script:writer.Write($data)
+ if ($script:JsonSettings.JsonNoComma) {
+ $script:writer.WriteLine($data)
+ }
+ else {
+ if (-not $script:firstEntry -or (-not $script:JsonSettings.JsonNoEmptyFirstLine)) {
+ $script:writer.WriteLine(",")
+ }
+ $script:writer.Write($data)
+ }
}
- else {
- $script:writer.WriteLine($data)
+ #endregion Json
+ #region XML
+ "XML" {
+ [xml]$xml = $message | ConvertTo-Xml -NoTypeInformation
+ $script:writer.WriteLine($xml.Objects.InnerXml)
}
- }
- #endregion Json
- #region XML
- "XML"
- {
- [xml]$xml = $message | ConvertTo-Xml -NoTypeInformation
- $script:writer.WriteLine($xml.Objects.InnerXml)
- }
- #endregion XML
- #region Html
- "Html"
- {
- [xml]$xml = $message | ConvertTo-Html -Fragment
+ #endregion XML
+ #region Html
+ "Html" {
+ [xml]$xml = $message | ConvertTo-Html -Fragment
- if ($script:firstEntry -and $IncludeHeader) {
- $script:writer.WriteLine($xml.table.tr[0].OuterXml)
+ if ($script:firstEntry -and $IncludeHeader) {
+ $script:writer.WriteLine($xml.table.tr[0].OuterXml)
+ }
+ $script:writer.WriteLine($xml.table.tr[1].OuterXml)
}
- $script:writer.WriteLine($xml.table.tr[1].OuterXml)
- }
- #endregion Html
- #region CMTrace
- "CMTrace"
- {
- $cType = 1
- if ($MessageItem.Level -eq 'Warning') { $cType = 2 }
- if ($MessageItem.ErrorRecord) { $cType = 3 }
- $fileEntry = ''
- if ($MessageItem.File) { $fileEntry = Split-Path -Path $MessageItem.File -Leaf }
+ #endregion Html
+ #region CMTrace
+ "CMTrace" {
+ $cType = 1
+ if ($MessageItem.Level -eq 'Warning') { $cType = 2 }
+ if ($MessageItem.ErrorRecord) { $cType = 3 }
+ $fileEntry = ''
+ if ($MessageItem.File) { $fileEntry = Split-Path -Path $MessageItem.File -Leaf }
+
+ $component = "{0}:{1} > {2}" -f $fileEntry, $MessageItem.Line, $MessageItem.FunctionName
+ if ($script:cmTraceSettings.CMTraceOverrideComponent -and $MessageItem.Data.Component) {
+ $component = $MessageItem.Data.Component
+ }
- $format = ''
- $line = $format -f $MessageItem.LogMessage, $MessageItem.Timestamp, $MessageItem.Line, $MessageItem.TargetObject, $cType, $MessageItem.Runspace, $fileEntry, $MessageItem.FunctionName
- $script:writer.WriteLine($line)
+ $format = ''
+ $line = $format -f $MessageItem.LogMessage, $MessageItem.Timestamp, $MessageItem.Line, $MessageItem.TargetObject, $cType, $MessageItem.Runspace, $fileEntry, $MessageItem.FunctionName, $component
+ $script:writer.WriteLine($line)
+ }
+ #endregion CMTrace
+ #region TXT
+ 'TXT' {
+ $script:writer.WriteLine($script:txtBuilder.Convert($Message))
+ }
+ #endregion TXT
}
- #endregion CMTrace
- }
- #endregion Type-Based Output
+ #endregion Type-Based Output
- $script:firstEntry = $false
+ $script:firstEntry = $false
+ }
}
function Invoke-LogRotate {
@@ -161,16 +170,16 @@
)
$hash = @{
- '%date%' = (Get-Date -Format 'yyyy-MM-dd')
- '%dayofweek%' = (Get-Date).DayOfWeek
- '%day%' = (Get-Date).Day
- '%hour%' = (Get-Date).Hour
- '%minute%' = (Get-Date).Minute
- '%username%' = $env:USERNAME
- '%userdomain%' = $env:USERDOMAIN
+ '%date%' = (Get-Date -Format 'yyyy-MM-dd')
+ '%dayofweek%' = (Get-Date).DayOfWeek
+ '%day%' = (Get-Date).Day
+ '%hour%' = (Get-Date).Hour
+ '%minute%' = (Get-Date).Minute
+ '%username%' = $env:USERNAME
+ '%userdomain%' = $env:USERDOMAIN
'%computername%' = $env:COMPUTERNAME
- '%processid%' = $PID
- '%logname%' = $logname
+ '%processid%' = $PID
+ '%logname%' = $logname
}
$hash.$Match
@@ -219,7 +228,7 @@
)
process {
- $data = @{ }
+ $data = [ordered]@{ }
foreach ($property in $InputObject.PSObject.Properties) {
if ($property.Value -is [enum]) {
$data[$property.Name] = $property.Value -as [string]
@@ -280,6 +289,7 @@ $begin_event = {
$script:currentPath = ''
$script:writer = $null
$script:firstEntry = $true
+ $script:txtBuilder = [PSFramework.Logging.TxtBuilder]::new()
}
$start_event = {
@@ -287,24 +297,21 @@ $start_event = {
$script:logfile_headers = Get-ConfigValue -Name 'Headers' | ForEach-Object {
switch ($_) {
- 'Tags'
- {
+ 'Tags' {
@{
- Name = 'Tags'
+ Name = 'Tags'
Expression = { $_.Tags -join "," }
}
}
- 'Message'
- {
+ 'Message' {
@{
- Name = 'Message'
+ Name = 'Message'
Expression = { $_.LogMessage }
}
}
- 'Timestamp'
- {
+ 'Timestamp' {
@{
- Name = 'Timestamp'
+ Name = 'Timestamp'
Expression = {
if (Get-ConfigValue -Name 'UTC') {
if (-not (Get-ConfigValue -Name 'TimeFormat')) { $_.Timestamp.ToUniversalTime() }
@@ -317,8 +324,7 @@ $start_event = {
}
}
}
- 'DataCompact'
- {
+ 'DataCompact' {
@{
Name = "DataCompact"
Expression = {
@@ -330,13 +336,44 @@ $start_event = {
}
}
}
- { "$_" -match '^[\w\.]+ as \S+$' }
- {
+ { "$_" -match '^[\w\.]+ as \S+$' } {
$value, $name = $_ -split ' as '
+
+ $code = switch ($value) {
+ Tags {
+ { $_.Tags -join "," }
+ }
+ Message {
+ { $_.LogMessage }
+ }
+ Timestamp {
+ {
+ if (Get-ConfigValue -Name 'UTC') {
+ if (-not (Get-ConfigValue -Name 'TimeFormat')) { $_.Timestamp.ToUniversalTime() }
+ else { $_.Timestamp.ToUniversalTime().ToString((Get-ConfigValue -Name 'TimeFormat')) }
+ }
+ else {
+ if (-not (Get-ConfigValue -Name 'TimeFormat')) { $_.Timestamp }
+ else { $_.Timestamp.ToString((Get-ConfigValue -Name 'TimeFormat')) }
+ }
+ }
+ }
+ DataCompact {
+ {
+ if (-not $_.Data) { return }
+ $lines = foreach ($pair in $_.Data.GetEnumerator()) {
+ '{0}={1}' -f $pair.Key, $pair.Value
+ }
+ $lines -join ", "
+ }
+ }
+ default { [ScriptBlock]::Create("`$_.$value") }
+ }
+
@{
- Name = $name
+ Name = $name
# Dynamic code is safe due to the pattern constraint of "\w\." - only letters, numbers and dots are allowed
- Expression = [ScriptBlock]::Create("`$_.$value")
+ Expression = $code
}
}
default { $_ }
@@ -366,16 +403,24 @@ $start_event = {
$script:logfile_paramWriteLogFileMessage = @{
IncludeHeader = Get-ConfigValue -Name 'IncludeHeader'
- FileType = Get-ConfigValue -Name 'FileType'
+ FileType = Get-ConfigValue -Name 'FileType'
CsvDelimiter = Get-ConfigValue -Name 'CsvDelimiter'
}
# Cache path for final move action
$script:logPathList[$script:currentPath] = $script:currentPath
$script:JsonSettings = @{
- JsonCompress = Get-ConfigValue -Name JsonCompress
- JsonString = Get-ConfigValue -Name JsonString
- JsonNoComma = Get-ConfigValue -Name JsonNoComma
+ JsonCompress = Get-ConfigValue -Name JsonCompress
+ JsonString = Get-ConfigValue -Name JsonString
+ JsonNoComma = Get-ConfigValue -Name JsonNoComma
+ JsonNoEmptyFirstLine = Get-ConfigValue -Name JsonNoEmptyFirstLine
+ }
+
+ $script:cmTraceSettings = @{
+ CMTraceOverrideComponent = Get-ConfigValue -Name CMTraceOverrideComponent
+ }
+ if ($script:logfile_paramWriteLogFileMessage.FileType -eq 'TXT') {
+ $script:txtBuilder.Load((Get-ConfigValue -Name TXTPattern))
}
}
@@ -389,7 +434,7 @@ $message_event = {
# Set to end of file, in case another process wrote
$script:writer.BaseStream.Position = $script:writer.BaseStream.Length
}
- try { $Message | Select-Object $script:logfile_headers | Write-LogFileMessage @script:logfile_paramWriteLogFileMessage -MessageItem $Message }
+ try { $Message | Microsoft.PowerShell.Utility\Select-Object $script:logfile_headers | Write-LogFileMessage @script:logfile_paramWriteLogFileMessage -MessageItem $Message }
finally {
$script:writer.Flush()
$script:writer.BaseStream.Flush()
@@ -426,7 +471,7 @@ $configuration_Settings = {
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.Logname' -Value "" -Initialize -Validation string -Description "A special string you can use as a placeholder in the logfile path (by using '%logname%' as placeholder)"
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.IncludeHeader' -Value $true -Initialize -Validation bool -Description "Whether a written csv file will include headers"
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.Headers' -Value @('ComputerName', 'File', 'FunctionName', 'Level', 'Line', 'Message', 'ModuleName', 'Runspace', 'Tags', 'TargetObject', 'Timestamp', 'Type', 'Username') -Initialize -Validation stringarray -Description "The properties to export, in the order to select them."
- Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.FileType' -Value "CSV" -Initialize -Validation psframework.logfilefiletype -Description "In what format to write the logfile. Supported styles: CSV, XML, Html, Json or CMTrace. Html, XML and Json will be written as fragments."
+ Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.FileType' -Value "CSV" -Initialize -Validation psframework.logfilefiletype -Description "In what format to write the logfile. Supported styles: CSV, XML, Html, Json, TXT or CMTrace. Html, XML and Json will be written as fragments."
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.CsvDelimiter' -Value "," -Initialize -Validation string -Description "The delimiter to use when writing to csv."
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.TimeFormat' -Value "$([System.Globalization.CultureInfo]::CurrentUICulture.DateTimeFormat.ShortDatePattern) $([System.Globalization.CultureInfo]::CurrentUICulture.DateTimeFormat.LongTimePattern)" -Initialize -Validation string -Description "The format used for timestamps in the logfile"
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.Encoding' -Value "UTF8" -Initialize -Validation string -Description "In what encoding to write the logfile."
@@ -439,33 +484,37 @@ $configuration_Settings = {
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.JsonCompress' -Value $false -Initialize -Validation bool -Description "Will compress the json entries, condensing each entry into a single line."
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.JsonString' -Value $false -Initialize -Validation bool -Description "Will convert all enumerated properties to string values when converting to json. This causes the level property to be 'Debug','Host', ... rather than 8,2,..."
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.JsonNoComma' -Value $false -Initialize -Validation bool -Description "Prevent adding commas between two json entries."
+ Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.JsonNoEmptyFirstLine' -Value $false -Initialize -Validation bool -Description "Prevent the empty first line when commas have not been disabled."
+ Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.CMTraceOverrideComponent' -Value $false -Initialize -Validation bool -Description 'When Enabled, messages that include a "Data" hashtable with a "Component" entry will use that Entry for the log message Component element, rather than the auto-calculated one.'
+ Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.TXTPattern' -Value '%Timestamp% [%Level%] %Message%' -Initialize -Validation string -Description 'The pattern of any given line in the TXT-based logfile. Use %PROPERTYNAME% as placeholder, e.g. "%Message%". Same properties as with the headers configuration - you need to specify both settings, if your pattern includes non-default properties such as "Data".'
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.MoveOnFinal' -Value '' -Initialize -Validation string -Description "Path to a target folder to move logfiles to when shutting down the logging provider instance. This happens automatically when PSFramework ends or the provider instance is disabled again."
Set-PSFConfig -Module PSFramework -Name 'Logging.LogFile.CopyOnFinal' -Value '' -Initialize -Validation string -Description "Path to a target folder to copy logfiles to when shutting down the logging provider instance. This happens automatically when PSFramework ends or the provider instance is disabled again."
}
$paramRegisterPSFLoggingProvider = @{
- Name = "logfile"
- Version2 = $true
- ConfigurationRoot = 'PSFramework.Logging.LogFile'
- InstanceProperties = 'CsvDelimiter', 'FilePath', 'FileType', 'Headers', 'IncludeHeader', 'Logname', 'TimeFormat', 'Encoding', 'UTC', 'LogRotatePath', 'LogRetentionTime', 'LogRotateFilter', 'LogRotateRecurse', 'MutexName', 'JsonCompress', 'JsonString', 'JsonNoComma', 'MoveOnFinal', 'CopyOnFinal'
- FunctionDefinitions = $functionDefinitions
- BeginEvent = $begin_event
- StartEvent = $start_event
- MessageEvent = $message_event
- EndEvent = $end_event
- FinalEvent = $final_event
+ Name = "logfile"
+ Version2 = $true
+ ConfigurationRoot = 'PSFramework.Logging.LogFile'
+ InstanceProperties = 'CsvDelimiter', 'FilePath', 'FileType', 'Headers', 'IncludeHeader', 'Logname', 'TimeFormat', 'Encoding', 'UTC', 'LogRotatePath', 'LogRetentionTime', 'LogRotateFilter', 'LogRotateRecurse', 'MutexName', 'JsonCompress', 'JsonString', 'JsonNoComma', 'JsonNoEmptyFirstLine', 'CMTraceOverrideComponent', 'TXTPattern', 'MoveOnFinal', 'CopyOnFinal'
+ FunctionDefinitions = $functionDefinitions
+ BeginEvent = $begin_event
+ StartEvent = $start_event
+ MessageEvent = $message_event
+ EndEvent = $end_event
+ FinalEvent = $final_event
ConfigurationDefaultValues = @{
- IncludeHeader = $true
- Headers = 'ComputerName', 'File', 'FunctionName', 'Level', 'Line', 'Message', 'ModuleName', 'Runspace', 'Tags', 'TargetObject', 'Timestamp', 'Type', 'Username'
- FileType = 'CSV'
- CsvDelimiter = ','
- TimeFormat = "$([System.Globalization.CultureInfo]::CurrentUICulture.DateTimeFormat.ShortDatePattern) $([System.Globalization.CultureInfo]::CurrentUICulture.DateTimeFormat.LongTimePattern)"
- Encoding = 'UTF8'
+ IncludeHeader = $true
+ Headers = 'ComputerName', 'File', 'FunctionName', 'Level', 'Line', 'Message', 'ModuleName', 'Runspace', 'Tags', 'TargetObject', 'Timestamp', 'Type', 'Username'
+ FileType = 'CSV'
+ CsvDelimiter = ','
+ TimeFormat = "$([System.Globalization.CultureInfo]::CurrentUICulture.DateTimeFormat.ShortDatePattern) $([System.Globalization.CultureInfo]::CurrentUICulture.DateTimeFormat.LongTimePattern)"
+ Encoding = 'UTF8'
LogRetentionTime = '30d'
- LogRotateFilter = '*'
+ LogRotateFilter = '*'
LogRotateRecurse = $false
+ TXTPattern = '%Timestamp% [%Level%] %Message%'
}
- ConfigurationSettings = $configuration_Settings
+ ConfigurationSettings = $configuration_Settings
}
Register-PSFLoggingProvider @paramRegisterPSFLoggingProvider
\ No newline at end of file
diff --git a/PSFramework/internal/loggingProviders/sql.provider.ps1 b/PSFramework/internal/loggingProviders/sql.provider.ps1
index 3b42b7c3..03cf9477 100644
--- a/PSFramework/internal/loggingProviders/sql.provider.ps1
+++ b/PSFramework/internal/loggingProviders/sql.provider.ps1
@@ -58,7 +58,12 @@
)
process {
- $queryParameters = @($script:converter.Process($ObjectToProcess))[0]
+ $queryParameters = @{ }
+ foreach ($header in $script:sql_headers) {
+ if ($header -is [string]) { $queryParameters[$header] = $($ObjectToProcess.$header) }
+ elseif ($header.Name) { $queryParameters[$header.Name] = $(([PsfScriptBlock]$header.Expression).InvokeEx($false, $ObjectToProcess, $ObjectToProcess, $ObjectToProcess, $false, $false, $ObjectToProcess)) }
+ else { $queryParameters[$header.Label] = $(([PsfScriptBlock]$header.Expression).InvokeEx($false, $ObjectToProcess, $ObjectToProcess, $ObjectToProcess, $false, $false, $ObjectToProcess)) }
+ }
$insertQuery = Get-Query -Parameters $queryParameters
try {
@@ -260,14 +265,6 @@ $start_event = {
default { $_ }
}
- if ($script:converter) {
- $null = $script:converter.End()
- $script:converter = $null
- }
- # Cache the conversion logic once as a steppable pipeline to avoid having to do it
- $script:converter = { Microsoft.PowerShell.Utility\Select-Object $script:sql_headers | PSFramework\ConvertTo-PSFHashtable }.GetSteppablePipeline()
- $script:converter.Begin($true)
-
$script:insertQuery = ''
}
@@ -280,10 +277,7 @@ $message_event = {
}
$end_event = {
- if ($script:converter) {
- $null = $script:converter.End()
- $script:converter = $null
- }
+
}
# Action that is performed when stopping the logging script.
@@ -299,6 +293,7 @@ $configuration_Settings = {
Set-PSFConfig -Module PSFramework -Name 'Logging.Sql.Table' -Value "LoggingTable" -Initialize -Validation 'string' -Description "SQL server database table."
Set-PSFConfig -Module PSFramework -Name 'Logging.Sql.SqlServer' -Value "" -Initialize -Description "SQL server hosting logs."
Set-PSFConfig -Module PSFramework -Name 'Logging.Sql.Schema' -Value "dbo" -Initialize -Description "SQL server schema."
+ Set-PSFConfig -Module PSFramework -Name 'Logging.Sql.Headers' -Value 'Message', 'Timestamp', 'Level', 'Tags', 'Data', 'ComputerName', 'Runspace', 'UserName', 'ModuleName', 'FunctionName', 'File', 'Line', 'CallStack', 'TargetObject', 'ErrorRecord' -Initialize -Description "SQL server schema."
}
# Registered parameters for the logging provider.
diff --git a/PSFramework/internal/scripts/cmdlets.ps1 b/PSFramework/internal/scripts/cmdlets.ps1
index 928d7ae6..126dfe8c 100644
--- a/PSFramework/internal/scripts/cmdlets.ps1
+++ b/PSFramework/internal/scripts/cmdlets.ps1
@@ -7,6 +7,7 @@ $commonParam = @{
Module = $ExecutionContext.SessionState.Module
}
+Import-PSFCmdlet @commonParam -Name Assert-PSFInternalCommand -Type ([PSFramework.Commands.AssertPSFInternalCommandCommand])
Import-PSFCmdlet @commonParam -Name ConvertTo-PSFHashtable -Type ([PSFramework.Commands.ConvertToPSFHashtableCommand])
Import-PSFCmdlet @commonParam -Name Invoke-PSFCallback -Type ([PSFramework.Commands.InvokePSFCallbackCommand])
Import-PSFCmdlet @commonParam -Name Invoke-PSFProtectedCommand -Type ([PSFramework.Commands.InvokePSFProtectedCommand])
@@ -16,5 +17,6 @@ Import-PSFCmdlet @commonParam -Name Set-PSFObjectOrder -Type ([PSFramework.Comma
Import-PSFCmdlet @commonParam -Name Set-PSFConfig -Type ([PSFramework.Commands.SetPSFConfigCommand])
Import-PSFCmdlet @commonParam -Name Test-PSFShouldProcess -Type ([PSFramework.Commands.TestPSFShouldProcessCommand])
Import-PSFCmdlet @commonParam -Name Write-PSFMessage -Type ([PSFramework.Commands.WritePSFMessageCommand])
+Import-PSFCmdlet @commonParam -Name Update-PSFTeppCompletion -Type ([PSFramework.Commands.UpdatePSFTeppCompletionCommand])
Set-Alias -Name Sort-PSFObject -Value Set-PSFObjectOrder -Force -ErrorAction SilentlyContinue
\ No newline at end of file
diff --git a/PSFramework/internal/scripts/teppSimpleCompleter.ps1 b/PSFramework/internal/scripts/teppSimpleCompleter.ps1
index c5836125..0a23c385 100644
--- a/PSFramework/internal/scripts/teppSimpleCompleter.ps1
+++ b/PSFramework/internal/scripts/teppSimpleCompleter.ps1
@@ -31,6 +31,9 @@
.PARAMETER CompletionResultType
The type of object that is being completed.
By default it generates one of type paramter value.
+
+ .PARAMETER AlwaysQuote
+ Always place quotes around results, whether the text has a whitespace or not.
.PARAMETER NoQuotes
Whether to put the result in quotes or not.
@@ -56,6 +59,9 @@
[System.Management.Automation.CompletionResultType]
$CompletionResultType = [System.Management.Automation.CompletionResultType]::ParameterValue,
+
+ [switch]
+ $AlwaysQuote,
[switch]
$NoQuotes
@@ -71,7 +77,10 @@
# not be included, via the -NoQuotes parameter,
# then skip adding quotes.
- if ($CompletionResultType -eq [System.Management.Automation.CompletionResultType]::ParameterValue -and -not $NoQuotes) {
+ if ($AlwaysQuote -and $CompletionText -notmatch '^".+"$' -and $CompletionText -notmatch "^'.+'$") {
+ $CompletionText = "'$($CompletionText -replace "'","''")'"
+ }
+ elseif ($CompletionResultType -eq [System.Management.Automation.CompletionResultType]::ParameterValue -and -not $NoQuotes) {
# Add single quotes for the caller in case they are needed.
# We use the parser to robustly determine how it will treat
# the argument. If we end up with too many tokens, or if
@@ -81,7 +90,7 @@
$tokens = $null
$null = [System.Management.Automation.Language.Parser]::ParseInput("Write-Output $CompletionText", [ref]$tokens, [ref]$null)
if ($tokens.Length -ne 3 -or ($tokens[1] -is [System.Management.Automation.Language.StringExpandableToken] -and $tokens[1].Kind -eq [System.Management.Automation.Language.TokenKind]::Generic)) {
- $CompletionText = "'$CompletionText'"
+ $CompletionText = "'$($CompletionText -replace "'","''")'"
}
}
return New-Object System.Management.Automation.CompletionResult($CompletionText, $listItemToUse, $CompletionResultType, $toolTipToUse.Trim())
@@ -110,10 +119,15 @@
if ($entry -is [hashtable]) {
if ($entry['ToolTip']) { $toolTip = $entry['ToolTip'] -as [string] }
if ($entry['ListItemText']) { $listItemText = $entry['ListItemText'] -as [string] }
+ if ($entry['ToolTipString']) { $toolTip = [PSFramework.Localization.LocalizationHost]::ReadLog($entry['ToolTipString']) }
+ if ($entry['ListItemTextString']) { $listItemText = [PSFramework.Localization.LocalizationHost]::ReadLog($entry['ListItemTextString']) }
}
if ($entry.PSObject.Properties.Name -contains 'ToolTip' -and $entry.ToolTip) { $toolTip = $entry.ToolTip -as [string] }
if ($entry.PSObject.Properties.Name -contains 'ListItemText' -and $entry.ListItemText) { $listItemText = $entry.ListItemText -as [string] }
+ if ($entry.PSObject.Properties.Name -contains 'ToolTipString' -and $entry.ToolTipString) { $toolTip = [PSFramework.Localization.LocalizationHost]::ReadLog($entry.ToolTipString) }
+ if ($entry.PSObject.Properties.Name -contains 'ListItemTextString' -and $entry.ListItemTextString) { $listItemText = [PSFramework.Localization.LocalizationHost]::ReadLog($entry.ListItemTextString) }
+
[PSCustomObject]@{
Text = $text
ToolTip = $toolTip
@@ -125,28 +139,46 @@
$start = Get-Date
$scriptContainer = [PSFramework.TabExpansion.TabExpansionHost]::Scripts[""]
- if ($scriptContainer.ShouldExecute) {
- $scriptContainer.LastExecution = $start
-
- $innerScript = $scriptContainer.InnerScriptBlock
- [PSFramework.Utility.UtilityHost]::ImportScriptBlock($innerScript)
- $items = @()
- try { $items = & $innerScript | ConvertTo-TeppCompletionEntry }
- catch { $null = $scriptContainer.ErrorRecords.Enqueue($_) }
-
- foreach ($item in ($items | Where-Object Text -Like "$wordToComplete*" | Sort-Object Text)) {
- New-PSFTeppCompletionResult -CompletionText $item.Text -ToolTip $item.ToolTip -ListItemText $item.ListItemText
+ if (-not $scriptContainer) {
+ Write-PSFMessage -Message "Tab Expansion script not found: '{0}'" -StringValues ''
+ throw "Tab Expansion script not found: ''"
+ }
+ $alwaysQuote = $scriptContainer.AlwaysQuote
+ $sortParam = @{ Property = 'ListItemText' }
+ if ($scriptContainer.DontSort) { $sortParam = @{ Property = { 1 }}}
+
+ if (-not $scriptContainer.ShouldExecute) {
+ if ($scriptContainer.Trained.Count -gt 0) {
+ $allItems = @($scriptContainer.LastCompletion) + ($scriptContainer.Trained | ConvertTo-TeppCompletionEntry)
}
-
- $scriptContainer.LastDuration = (Get-Date) - $start
- if ($items) {
- $scriptContainer.LastResult = $items.Text
- $scriptContainer.LastCompletion = $items
+ else { $allItems = $scriptContainer.LastCompletion }
+ foreach ($item in ($scriptContainer.LastCompletion | Where-Object Text -match $scriptContainer.GetPattern($wordToComplete) | Sort-Object @sortParam)) {
+ New-PSFTeppCompletionResult -CompletionText $item.Text -ToolTip $item.ToolTip -ListItemText $item.ListItemText -AlwaysQuote:$alwaysQuote
}
+ return
}
- else {
- foreach ($item in ($scriptContainer.LastCompletion | Where-Object Text -Like "$wordToComplete*" | Sort-Object Text)) {
- New-PSFTeppCompletionResult -CompletionText $item.Text -ToolTip $item.ToolTip -ListItemText $item.ListItemText
- }
+
+ $scriptContainer.LastExecution = $start
+
+ $innerScript = $scriptContainer.InnerScriptBlock
+ [PSFramework.Utility.UtilityHost]::ImportScriptBlock($innerScript)
+ $items = @()
+ try { $items = & $innerScript | ConvertTo-TeppCompletionEntry }
+ catch { $null = $scriptContainer.ErrorRecords.Enqueue($_) }
+
+ if ($scriptContainer.Trained.Count -gt 0) {
+ $allItems = @($items) + ($scriptContainer.Trained | ConvertTo-TeppCompletionEntry)
+ }
+ else { $allItems = $items }
+
+
+ foreach ($item in ($allItems | Where-Object Text -match $scriptContainer.GetPattern($wordToComplete) | Sort-Object @sortParam)) {
+ New-PSFTeppCompletionResult -CompletionText $item.Text -ToolTip $item.ToolTip -ListItemText $item.ListItemText -AlwaysQuote:$alwaysQuote
+ }
+
+ $scriptContainer.LastDuration = (Get-Date) - $start
+ if ($items) {
+ $scriptContainer.LastResult = $items.Text
+ $scriptContainer.LastCompletion = $items
}
}
\ No newline at end of file
diff --git a/PSFramework/tests/extensions/HaveParameters.ps1 b/PSFramework/tests/extensions/HaveParameters.ps1
new file mode 100644
index 00000000..a8ad2487
--- /dev/null
+++ b/PSFramework/tests/extensions/HaveParameters.ps1
@@ -0,0 +1,92 @@
+function HaveParameters {
+ [CmdletBinding()]
+ param (
+ $ActualValue,
+
+ [string[]]
+ $Parameters,
+
+ [switch]
+ $Negate,
+
+ $CallerSessionState
+ )
+ end {
+ $commonParameters = 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'ProgressAction'
+ if ($global:__pester_data.CommonParameters) { $commonParameters = $global:__pester_data.CommonParameters }
+
+ #region Resolve Command
+ if ($null -eq $ActualValue) {
+ return [PSCustomObject]@{
+ Succeeded = $false
+ FailureMessage = "Did not receive a command to test"
+ }
+ }
+
+ $command = $ActualValue
+ if ($command -isnot [System.Management.Automation.CommandInfo]) {
+ try { $command = Get-Command $ActualValue -ErrorAction Stop }
+ catch {
+ return [PSCustomObject]@{
+ Succeeded = $false
+ FailureMessage = "Unable to resolve command: $ActualValue"
+ }
+ }
+ }
+ #endregion Resolve Command
+
+ #region Negation
+ if ($Negate) {
+ $found = @()
+ foreach ($parameter in $Parameters) {
+ if ($parameter -notin $command.Parameters.Keys) { continue }
+ $found += $parameter
+ }
+
+ if ($found) {
+ return [PSCustomObject]@{
+ Succeeded = $false
+ FailureMessage = "Parameters found on $($command.Name): $($found -join ', ')"
+ }
+ }
+ return [PSCustomObject]@{
+ Succeeded = $true
+ FailureMessage = "None of the forbidden parameters found on $($command.Name) (Forbidden: $($Parameters -join ', '))"
+ }
+ }
+ #endregion Negation
+
+ #region Regular Parameter Test
+ $notFound = @()
+ $excessFound = @()
+
+ foreach ($parameter in $command.Parameters.Keys) {
+ if ($parameter -in $commonParameters) { continue }
+ if ($parameter -in $Parameters) { continue }
+ $excessFound += $parameter
+ }
+
+ foreach ($parameter in $Parameters) {
+ if ($parameter -in $command.Parameters.Keys) { continue }
+ $notFound += $parameter
+ }
+
+ if (-not $notFound -and -not $excessFound) {
+ return [PSCustomObject]@{
+ Succeeded = $true
+ FailureMessage = "All expected parameters found on $($command.Name) (Expected: $($Parameters -join ', '))"
+ }
+ }
+
+ $fragments = @()
+ if ($notFound) { $fragments += "Missing: $($notFound -join ', ')" }
+ if ($excessFound) { $fragments += "Unexpected: $($excessFound -join ', ')" }
+
+ return [PSCustomObject]@{
+ Succeeded = $false
+ FailureMessage = "Parameters found on $($command.Name) not as desired | Expected: $($Parameters -join ', ') | $($fragments -join ' | ')"
+ }
+ #endregion Regular Parameter Test
+ }
+}
+Add-ShouldOperator -Name HaveParameters -Test $function:HaveParameters
\ No newline at end of file
diff --git a/PSFramework/tests/functions/configuration/Export-PSFConfig.Tests.ps1 b/PSFramework/tests/functions/configuration/Export-PSFConfig.Tests.ps1
index 7d702d72..27fd7de3 100644
--- a/PSFramework/tests/functions/configuration/Export-PSFConfig.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Export-PSFConfig.Tests.ps1
@@ -17,7 +17,7 @@
(Get-Command Export-PSFConfig).ParameterSets.Name | Should -Be 'FullName', 'Module', 'Config', 'ModuleName'
foreach ($key in (Get-Command Export-PSFConfig).Parameters.Keys)
{
- $key | Should -BeIn 'FullName', 'Module', 'Name', 'Config', 'ModuleName', 'ModuleVersion', 'Scope', 'OutPath', 'SkipUnchanged', 'EnableException', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
+ $key | Should -BeIn 'FullName', 'Module', 'Name', 'Config', 'ModuleName', 'ModuleVersion', 'Scope', 'OutPath', 'SkipUnchanged', 'EnableException', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'ProgressAction'
}
}
diff --git a/PSFramework/tests/functions/configuration/Get-PSFConfig.Tests.ps1 b/PSFramework/tests/functions/configuration/Get-PSFConfig.Tests.ps1
index bf7986db..314490f9 100644
--- a/PSFramework/tests/functions/configuration/Get-PSFConfig.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Get-PSFConfig.Tests.ps1
@@ -13,7 +13,7 @@
# Catch any signature changes to force revisiting the command
It "Should have the designed for parameters & sets" {
(Get-Command Get-PSFConfig).ParameterSets.Name | Should -Be 'FullName', 'Module'
- (Get-Command Get-PSFConfig).Parameters.Keys | Should -Be 'FullName', 'Name', 'Module', 'Persisted', 'Force', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
+ Get-Command Get-PSFConfig | Should -HaveParameters 'FullName', 'Name', 'Module', 'Persisted', 'Force'
}
It "Should find the correct Configuration item" {
diff --git a/PSFramework/tests/functions/configuration/Get-PSFConfigValue.Tests.ps1 b/PSFramework/tests/functions/configuration/Get-PSFConfigValue.Tests.ps1
index f5914480..43849789 100644
--- a/PSFramework/tests/functions/configuration/Get-PSFConfigValue.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Get-PSFConfigValue.Tests.ps1
@@ -15,7 +15,7 @@
(Get-Command Get-PSFConfigValue).ParameterSets.Name | Should -Be '__AllParameterSets'
foreach ($key in (Get-Command Get-PSFConfigValue).Parameters.Keys)
{
- $key | Should -BeIn 'FullName', 'Fallback', 'NotNull', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
+ $key | Should -BeIn 'FullName', 'Fallback', 'NotNull', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'ProgressAction'
}
}
diff --git a/PSFramework/tests/functions/configuration/Import-PSFConfig.Tests.ps1 b/PSFramework/tests/functions/configuration/Import-PSFConfig.Tests.ps1
index d54440f2..05da341d 100644
--- a/PSFramework/tests/functions/configuration/Import-PSFConfig.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Import-PSFConfig.Tests.ps1
@@ -27,7 +27,7 @@
(Get-Command Import-PSFConfig).ParameterSets.Name | Should -Be 'Path', 'ModuleName', 'Environment'
foreach ($key in (Get-Command Import-PSFConfig).Parameters.Keys)
{
- $key | Should -BeIn 'Path', 'ModuleName', 'ModuleVersion', 'Scope', 'Schema', 'IncludeFilter', 'ExcludeFilter', 'Peek', 'AllowDelete', 'PassThru', 'EnvironmentPrefix', 'Simple', 'EnableException', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
+ $key | Should -BeIn 'Path', 'ModuleName', 'ModuleVersion', 'Scope', 'Schema', 'IncludeFilter', 'ExcludeFilter', 'Peek', 'AllowDelete', 'PassThru', 'EnvironmentPrefix', 'Simple', 'EnableException', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'ProgressAction'
}
}
diff --git a/PSFramework/tests/functions/configuration/Register-PSFConfig.Tests.ps1 b/PSFramework/tests/functions/configuration/Register-PSFConfig.Tests.ps1
index ac9585f2..e8cb8e2a 100644
--- a/PSFramework/tests/functions/configuration/Register-PSFConfig.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Register-PSFConfig.Tests.ps1
@@ -13,8 +13,7 @@
# Catch any signature changes to force revisiting the command
It "Should have the designed for parameters & sets" {
(Get-Command Register-PSFConfig).ParameterSets.Name | Should -Be 'Default', 'Name'
- $properties = 'Config', 'FullName', 'Module', 'Name', 'Scope', 'EnableException', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
- Compare-Object $properties ((Get-Command Register-PSFConfig).Parameters.Keys | Remove-PSFNull -Enumerate) | Should -BeNullOrEmpty
+ Get-Command Register-PSFConfig | Should -HaveParameters 'Config', 'FullName', 'Module', 'Name', 'Scope', 'EnableException'
}
Context "Validating registry persistence" {
diff --git a/PSFramework/tests/functions/configuration/Register-PSFConfigValidation.Tests.ps1 b/PSFramework/tests/functions/configuration/Register-PSFConfigValidation.Tests.ps1
index b7b5ca83..77d7c8b3 100644
--- a/PSFramework/tests/functions/configuration/Register-PSFConfigValidation.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Register-PSFConfigValidation.Tests.ps1
@@ -13,8 +13,7 @@
# Catch any signature changes to force revisiting the command
It "Should have the designed for parameters & sets" {
(Get-Command Register-PSFConfigValidation).ParameterSets.Name | Should -Be '__AllParameterSets'
- $properties = 'Name', 'ScriptBlock', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
- Compare-Object $properties ((Get-Command Register-PSFConfigValidation).Parameters.Keys | Remove-PSFNull -Enumerate) | Should -BeNullOrEmpty
+ Get-Command Register-PSFConfigValidation | Should -HaveParameters 'Name', 'ScriptBlock'
}
Context "Ensuring validation can be created, assigned and used" {
diff --git a/PSFramework/tests/functions/configuration/Remove-PSFConfig.Tests.ps1 b/PSFramework/tests/functions/configuration/Remove-PSFConfig.Tests.ps1
index c0f7d331..cc4211bb 100644
--- a/PSFramework/tests/functions/configuration/Remove-PSFConfig.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Remove-PSFConfig.Tests.ps1
@@ -15,7 +15,7 @@
(Get-Command Remove-PSFConfig).ParameterSets.Name | Should -Be 'Default', 'Name'
foreach ($key in (Get-Command Remove-PSFConfig).Parameters.Keys)
{
- $key | Should -BeIn 'Config', 'FullName', 'Module', 'Name', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'WhatIf', 'Confirm'
+ $key | Should -BeIn 'Config', 'FullName', 'Module', 'Name', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'WhatIf', 'Confirm', 'ProgressAction'
}
}
diff --git a/PSFramework/tests/functions/configuration/Set-PSFConfig.Tests.ps1 b/PSFramework/tests/functions/configuration/Set-PSFConfig.Tests.ps1
index 277d511c..f0bf9ded 100644
--- a/PSFramework/tests/functions/configuration/Set-PSFConfig.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Set-PSFConfig.Tests.ps1
@@ -16,7 +16,7 @@
# Catch any signature changes to force revisiting the command
It "Should have the designed for parameters & sets" {
(Get-Command Set-PSFConfig).ParameterSets.Name | Should -Be 'FullName', 'Persisted', 'Module'
- (Get-Command Set-PSFConfig).Parameters.Keys | Should -Be 'FullName', 'Module', 'Name', 'Value', 'PersistedValue', 'PersistedType', 'Description', 'Validation', 'Handler', 'Hidden', 'Default', 'Initialize', 'SimpleExport', 'ModuleExport', 'AllowDelete', 'DisableValidation', 'DisableHandler', 'PassThru', 'EnableException', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
+ Get-Command Set-PSFConfig | Should -HaveParameters 'FullName', 'Module', 'Name', 'Value', 'PersistedValue', 'PersistedType', 'Description', 'Validation', 'Handler', 'Hidden', 'Default', 'Initialize', 'SimpleExport', 'ModuleExport', 'AllowDelete', 'DisableValidation', 'DisableHandler', 'PassThru', 'EnableException'
}
Describe "Basic functionality tests" {
diff --git a/PSFramework/tests/functions/configuration/Unregister-PSFConfig.Tests.ps1 b/PSFramework/tests/functions/configuration/Unregister-PSFConfig.Tests.ps1
index af2b6bc8..36e3ba30 100644
--- a/PSFramework/tests/functions/configuration/Unregister-PSFConfig.Tests.ps1
+++ b/PSFramework/tests/functions/configuration/Unregister-PSFConfig.Tests.ps1
@@ -13,8 +13,7 @@
# Catch any signature changes to force revisiting the command
It "Should have the designed for parameters & sets" {
(Get-Command Unregister-PSFConfig).ParameterSets.Name | Should -Be 'Pipeline', 'Module'
- $properties = 'ConfigurationItem', 'PersistedItem', 'FullName', 'Module', 'Name', 'Scope', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
- Compare-Object $properties ((Get-Command Unregister-PSFConfig).Parameters.Keys | Remove-PSFNull -Enumerate) | Should -BeNullOrEmpty
+ Get-Command Unregister-PSFConfig | Should -HaveParameters 'ConfigurationItem', 'PersistedItem', 'FullName', 'Module', 'Name', 'Scope'
}
function New-Location
diff --git a/PSFramework/tests/functions/parameter/PsfFile.Parameter.Tests.ps1 b/PSFramework/tests/functions/parameter/PsfFile.Parameter.Tests.ps1
index 2fa8b53a..2c4f2cc4 100644
--- a/PSFramework/tests/functions/parameter/PsfFile.Parameter.Tests.ps1
+++ b/PSFramework/tests/functions/parameter/PsfFile.Parameter.Tests.ps1
@@ -1,4 +1,4 @@
-Describe "Parameter Class: PsfFile Unit Tests" {
+Describe "Parameter Class: Path Parameter Class Unit Tests" {
BeforeAll {
function Get-File {
[CmdletBinding()]
@@ -11,8 +11,62 @@
}
}
+ function Get-File2 {
+ [CmdletBinding()]
+ param (
+ [PsfFile]
+ $File,
+
+ [PsfFileLax]
+ $FileLax,
+
+ [PsfFileSingle]
+ $FileSingle,
+
+ [PsfDirectory]
+ $Directory,
+
+ [PsfDirectoryLax]
+ $DirectoryLax,
+
+ [PsfDirectorySingle]
+ $DirectorySingle,
+
+ [PsfPath]
+ $Path,
+
+ [PsfPathLax]
+ $PathLax,
+
+ [PsfPathSingle]
+ $PathSingle,
+
+ [PsfLiteralPath]
+ $LiteralPath,
+
+ [PsfLiteralPathLax]
+ $LiteralPathLax,
+
+ [PsfLiteralPathSingle]
+ $LiteralPathSingle,
+
+ [PsfLiteralFileSingle]
+ $LiteralFileSingle,
+
+ [PsfLiteralDirectorySingle]
+ $LiteralDirectorySingle,
+
+ [PsfNewFile]
+ $NewFile,
+
+ [PsfNewFileSingle]
+ $NewFileSingle
+ )
+ $PSBoundParameters.Values | Write-Output
+ }
+
$folder = New-PSFTempDirectory -ModuleName PSFTest -Name TempFolder
- $folder = (Resolve-Path -LiteralPath $folder).ProviderPath
+ $folder = (Get-Item -LiteralPath (Resolve-Path -LiteralPath $folder).ProviderPath).FullName
"Test" | Set-Content -Path "$folder\test1.txt"
"Test" | Set-Content -Path "$folder\test2.txt"
"Test" | Set-Content -Path "$folder\test3.txt"
@@ -32,37 +86,205 @@
Remove-PSFTempItem -ModuleName PSFTest -Name TempFolder
}
- It "Should process an explicit path without error" {
- Get-File -Path "$folder\test1.txt" | Should -Be "$folder\test1.txt"
- }
- It "Should process wildcard paths, disregarding folders" {
- Get-File -Path "$folder\tes*" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
- }
- It "Should error on folders" {
- { Get-File -Path "$folder\test" } | Should -Throw
- }
- It "Should error on wildcard paths that do not resolve to at least one file" {
- { Get-File -Path "$folder\test\*" } | Should -Throw
- }
- It "Should process multiple paths" {
- Get-File -Path "$folder\test[12].txt", "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
- }
- It "Should accept a FileInfo object" {
- Get-File -Path $file1 | Should -Be $file1.FullName
- }
- It "Should accept multiple FileInfo objects" {
- Get-File -Path $file1, $file2 | Should -Be "$folder\test1.txt", "$folder\test2.txt"
- }
- It "Should deduplicate multiple same paths" {
- Get-File -Path $file1, $file1 | Should -Be "$folder\test1.txt"
- }
- It "Should accept a mix of different types of objects" {
- Get-File -Path $file1, $file2, "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ #region Path
+ Describe "Testing the Path-Classes that interpret wildcards" {
+ #region PsfFile
+ It "Should process an explicit path without error" {
+ Get-File -Path "$folder\test1.txt" | Should -Be "$folder\test1.txt"
+ }
+ It "Should process wildcard paths, disregarding folders" {
+ Get-File -Path "$folder\tes*" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ }
+ It "Should error on folders" {
+ { Get-File -Path "$folder\test" } | Should -Throw
+ }
+ It "Should error on wildcard paths that do not resolve to at least one file" {
+ { Get-File -Path "$folder\test\*" } | Should -Throw
+ }
+ It "Should process multiple paths" {
+ Get-File -Path "$folder\test[12].txt", "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ }
+ It "Should accept a FileInfo object" {
+ Get-File -Path $file1 | Should -Be $file1.FullName
+ }
+ It "Should accept multiple FileInfo objects" {
+ Get-File -Path $file1, $file2 | Should -Be "$folder\test1.txt", "$folder\test2.txt"
+ }
+ It "Should deduplicate multiple same paths" {
+ Get-File -Path $file1, $file1 | Should -Be "$folder\test1.txt"
+ }
+ It "Should accept a mix of different types of objects" {
+ Get-File -Path $file1, $file2, "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ }
+ It "Should not accept a DirectoryInfo object" {
+ { Get-File -Path (Get-Item -Path $folder) } | Should -Throw
+ }
+ It "Should accept a custom object that has registered a conversion" {
+ Get-File -Path $testObject | Should -Be "$folder\test3.txt"
+ }
+ #endregion PsfFile
+
+ It "Should process [PsfFileLax] correctly" {
+ Get-File2 -FileLax $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -FileLax $file1, $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -FileLax $file1, $file2, "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ Get-File2 -FileLax $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ Get-File2 -FileLax $folder | Should -BeNullOrEmpty
+ Get-File2 -FileLax "$folder\test4.txt" | Should -BeNullOrEmpty
+ Get-File2 -FileLax "$folder\*.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ }
+
+ It "Should process [PsfFileSingle] correctly" {
+ Get-File2 -FileSingle $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -FileSingle $file2 | Should -Be "$folder\test2.txt"
+ { Get-File2 -FileSingle $file1, $file2 } | Should -Throw
+ { Get-File2 -FileSingle $folder } | Should -Throw
+ { Get-File2 -FileSingle "$folder\*.txt" } | Should -Throw
+ { Get-File2 -FileSingle "$folder\test4.txt" } | Should -Throw
+ }
+
+ It "Should process [PsfDirectory] correctly" {
+ Get-File2 -Directory $folder | Should -Be $folder
+ Get-File2 -Directory (Get-Item -LiteralPath $folder) | Should -Be $folder
+ Get-File2 -Directory (Get-Item -LiteralPath $folder), (Get-Item -Path .) | Should -Be $folder, (Get-Item -Path .).FullName
+ { Get-File2 -Directory $file1 } | Should -Throw
+ { Get-File2 -Directory "$($folder)2" } | Should -Throw
+ }
+
+ It "Should process [PsfDirectoryLax] correctly" {
+ Get-File2 -DirectoryLax $folder | Should -Be $folder
+ Get-File2 -DirectoryLax (Get-Item -LiteralPath $folder) | Should -Be $folder
+ Get-File2 -DirectoryLax (Get-Item -LiteralPath $folder), (Get-Item -Path .) | Should -Be $folder, (Get-Item -Path .).FullName
+ { Get-File2 -DirectoryLax $file1 } | Should -Not -Throw
+ { Get-File2 -DirectoryLax "$($folder)2" } | Should -Not -Throw
+ }
+
+ It "Should process [PsfDirectorySingle] correctly" {
+ Get-File2 -DirectorySingle $folder | Should -Be $folder
+ Get-File2 -DirectorySingle (Get-Item -LiteralPath $folder) | Should -Be $folder
+ { Get-File2 -DirectorySingle (Get-Item -LiteralPath $folder), (Get-Item -Path .) } | Should -Throw
+ { Get-File2 -DirectorySingle $file1 } | Should -Throw
+ { Get-File2 -DirectorySingle "$($folder)2" } | Should -Throw
+ }
+
+ It "Should process [PsfPath] correctly" {
+ Get-File2 -Path $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -Path $file1, $folder | Should -Be "$folder\test1.txt", $folder
+ Get-File2 -Path $file1, $folder, $folder | Should -Be "$folder\test1.txt", $folder
+ Get-File2 -Path $file1, $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -Path $file1, $file2, "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ { Get-File2 -Path $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" } | Should -Throw
+ Get-File2 -Path $folder | Should -Be $folder
+ { Get-File2 -Path "$folder\test4.txt" } | Should -Throw
+ Get-File2 -Path "$folder\*.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ }
+
+ It "Should process [PsfPathLax] correctly" {
+ Get-File2 -PathLax $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -PathLax $file1, $folder | Should -Be "$folder\test1.txt", $folder
+ Get-File2 -PathLax $file1, $folder, $folder | Should -Be "$folder\test1.txt", $folder
+ Get-File2 -PathLax $file1, $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -PathLax $file1, $file2, "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ Get-File2 -PathLax $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ Get-File2 -PathLax $folder | Should -Be $folder
+ Get-File2 -PathLax "$folder\test4.txt" | Should -BeNullOrEmpty
+ Get-File2 -PathLax "$folder\*.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ }
+
+ It "Should process [PsfPathSingle] correctly" {
+ Get-File2 -PathSingle $file1 | Should -Be "$folder\test1.txt"
+ { Get-File2 -PathSingle $file1, $folder } | Should -Throw
+ { Get-File2 -PathSingle $file1, $folder, $folder } | Should -Throw
+ { Get-File2 -PathSingle $file1, $file1 } | Should -Throw
+ { Get-File2 -PathSingle $file1, $file2, "$folder\test3.txt" } | Should -Throw
+ { Get-File2 -PathSingle $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" } | Should -Throw
+ Get-File2 -PathSingle $folder | Should -Be $folder
+ { Get-File2 -PathSingle "$folder\test4.txt" } | Should -Throw
+ { Get-File2 -PathSingle "$folder\*.txt" } | Should -Throw
+ Get-File2 -PathSingle "$folder\*3.txt" | Should -Be "$folder\test3.txt"
+ }
}
- It "Should not accept a DirectoryInfo object" {
- { Get-File -Path (Get-Item -Path $folder) } | Should -Throw
+ #endregion Path
+
+ #region LiteralPath
+ Describe "Testing the Path-Classes that take things literal" {
+ It "Should process [PsfLiteralPath] correctly" {
+ Get-File2 -LiteralPath $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -LiteralPath $folder | Should -Be $folder
+ Get-File2 -LiteralPath (Get-Item -LiteralPath $folder) | Should -Be $folder
+ Get-File2 -LiteralPath $file1, $file2 | Should -Be "$folder\test1.txt", "$folder\test2.txt"
+ Get-File2 -LiteralPath $file1, $file2, "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ { Get-File2 -LiteralPath $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" } | Should -Throw
+ { Get-File2 -LiteralPath "$folder\*.txt" } | Should -Throw
+ }
+
+ It "Should process [PsfLiteralPathLax] correctly" {
+ Get-File2 -LiteralPathLax $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -LiteralPathLax $folder | Should -Be $folder
+ Get-File2 -LiteralPathLax (Get-Item -LiteralPath $folder) | Should -Be $folder
+ Get-File2 -LiteralPathLax $file1, $file2 | Should -Be "$folder\test1.txt", "$folder\test2.txt"
+ Get-File2 -LiteralPathLax $file1, $file2, "$folder\test3.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ Get-File2 -LiteralPathLax $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" | Should -Be "$folder\test1.txt", "$folder\test2.txt", "$folder\test3.txt"
+ Get-File2 -LiteralPathLax "$folder\*.txt" | Should -BeNullOrEmpty
+ }
+
+ It "Should process [PsfLiteralPathSingle] correctly" {
+ Get-File2 -LiteralPathSingle $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -LiteralPathSingle $folder | Should -Be $folder
+ Get-File2 -LiteralPathSingle (Get-Item -LiteralPath $folder) | Should -Be $folder
+ { Get-File2 -LiteralPathSingle $file1, $file2 } | Should -Throw
+ { Get-File2 -LiteralPathSingle $file1, $file2, "$folder\test3.txt" } | Should -Throw
+ { Get-File2 -LiteralPathSingle $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" } | Should -Throw
+ { Get-File2 -LiteralPathSingle "$folder\*.txt" } | Should -Throw
+ }
+
+ It "Should process [PsfLiteralFileSingle] correctly" {
+ Get-File2 -LiteralFileSingle $file1 | Should -Be "$folder\test1.txt"
+ { Get-File2 -LiteralFileSingle $folder } | Should -Throw
+ { Get-File2 -LiteralFileSingle (Get-Item -LiteralPath $folder) } | Should -Throw
+ { Get-File2 -LiteralFileSingle $file1, $file2 } | Should -Throw
+ { Get-File2 -LiteralFileSingle $file1, $file2, "$folder\test3.txt" } | Should -Throw
+ { Get-File2 -LiteralFileSingle $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" } | Should -Throw
+ { Get-File2 -LiteralFileSingle "$folder\*.txt" } | Should -Throw
+ }
+
+ It "Should process [PsfLiteralDirectorySingle] correctly" {
+ { Get-File2 -LiteralDirectorySingle $file1 } | Should -Throw
+ Get-File2 -LiteralDirectorySingle $folder | Should -Be $folder
+ Get-File2 -LiteralDirectorySingle (Get-Item -LiteralPath $folder) | Should -Be $folder
+ { Get-File2 -LiteralDirectorySingle $file1, $file2 } | Should -Throw
+ { Get-File2 -LiteralDirectorySingle $file1, $file2, "$folder\test3.txt" } | Should -Throw
+ { Get-File2 -LiteralDirectorySingle $file1, $file2, "$folder\test3.txt", "$folder\test4.txt" } | Should -Throw
+ { Get-File2 -LiteralDirectorySingle "$folder\*.txt" } | Should -Throw
+ }
}
- It "Should accept a custom object that has registered a conversion" {
- Get-File -Path $testObject | Should -Be "$folder\test3.txt"
+ #endregion LiteralPath
+
+ #region NewFile
+ Describe "Testing the Path-Classes that accept paths to new files" {
+ It "Should process [PsfNewFile] correctly" {
+ Get-File2 -NewFile $file1 | Should -Be "$folder\test1.txt"
+ Get-File2 -NewFile $file1, $file2 | Should -Be "$folder\test1.txt", "$folder\test2.txt"
+ { Get-File2 -NewFile $file1, $file2, $folder } | Should -Throw
+ { Get-File2 -NewFile $folder } | Should -Throw
+ Get-File2 -NewFile "$folder\test5.txt" | Should -Be "$folder\test5.txt"
+ Get-File2 -NewFile "$folder\test5.txt", "$folder\test6.txt" | Should -Be "$folder\test5.txt", "$folder\test6.txt"
+ Get-File2 -NewFile $file1, "$folder\test5.txt", "$folder\test6.txt" | Should -Be "$folder\test1.txt", "$folder\test5.txt", "$folder\test6.txt"
+ { Get-File2 -NewFile "$folder abc\test1.txt" } | Should -Throw
+ { Get-File2 -NewFile "$folder abc\test1.txt", "$folder\test1.txt" } | Should -Throw
+ }
+
+ It "Should process [PsfNewFileSingle] correctly" {
+ Get-File2 -NewFileSingle $file1 | Should -Be "$folder\test1.txt"
+ { Get-File2 -NewFileSingle $file1, $file2 } | Should -Throw
+ { Get-File2 -NewFileSingle $file1, $file2, $folder } | Should -Throw
+ { Get-File2 -NewFileSingle $folder } | Should -Throw
+ Get-File2 -NewFileSingle "$folder\test5.txt" | Should -Be "$folder\test5.txt"
+ { Get-File2 -NewFileSingle "$folder\test5.txt", "$folder\test6.txt" } | Should -Throw
+ { Get-File2 -NewFileSingle $file1, "$folder\test5.txt", "$folder\test6.txt" } | Should -Throw
+ { Get-File2 -NewFileSingle "$folder abc\test1.txt" } | Should -Throw
+ { Get-File2 -NewFileSingle "$folder abc\test1.txt", "$folder\test1.txt" } | Should -Throw
+ }
}
+ #endregion NewFile
}
\ No newline at end of file
diff --git a/PSFramework/tests/functions/pipeline/Remove-PSFNull.Tests.ps1 b/PSFramework/tests/functions/pipeline/Remove-PSFNull.Tests.ps1
index 1ac8a9ae..65660385 100644
--- a/PSFramework/tests/functions/pipeline/Remove-PSFNull.Tests.ps1
+++ b/PSFramework/tests/functions/pipeline/Remove-PSFNull.Tests.ps1
@@ -4,7 +4,7 @@
(Get-Command Remove-PSFNull).ParameterSets.Name | Should -Be '__AllParameterSets'
foreach ($key in (Get-Command Remove-PSFNull).Parameters.Keys)
{
- $key | Should -BeIn 'InputObject', 'AllowEmptyStrings', 'AllowEmptyCollections', 'Enumerate', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable'
+ $key | Should -BeIn 'InputObject', 'AllowEmptyStrings', 'AllowEmptyCollections', 'Enumerate', 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'ProgressAction'
}
}
diff --git a/PSFramework/tests/general/FileIntegrity.Exceptions.ps1 b/PSFramework/tests/general/FileIntegrity.Exceptions.ps1
index 09ec543a..c98da514 100644
--- a/PSFramework/tests/general/FileIntegrity.Exceptions.ps1
+++ b/PSFramework/tests/general/FileIntegrity.Exceptions.ps1
@@ -20,7 +20,7 @@ $global:MayContainCommand = @{
"Write-Host" = @('Write-PSFHostColor.ps1')
"Write-Verbose" = @()
"Write-Warning" = @('assembly.ps1')
- "Write-Error" = @('Import-PSFPowerShellDataFile.ps1', 'Invoke-PSFCommand.ps1', 'Stop-PSFFunction.ps1')
+ "Write-Error" = @('Import-PSFJson.ps1', 'Import-PSFPowerShellDataFile.ps1', 'Invoke-PSFCommand.ps1', 'Set-PSFFileContent.ps1', 'Stop-PSFFunction.ps1')
"Write-Output" = @('filesystem.provider.ps1', 'gelf.provider.ps1', 'Import-PSFPowerShellDataFile.ps1', 'logfile.provider.ps1', 'input.ps1', 'teppCoreCode.ps1')
"Write-Information" = @()
"Write-Debug" = @()
diff --git a/PSFramework/tests/general/Help.Tests.ps1 b/PSFramework/tests/general/Help.Tests.ps1
index ff070ced..e9ad8f3f 100644
--- a/PSFramework/tests/general/Help.Tests.ps1
+++ b/PSFramework/tests/general/Help.Tests.ps1
@@ -89,7 +89,7 @@ foreach ($command in $commands) {
Context "Test parameter help for $commandName" {
- $common = 'Debug', 'ErrorAction', 'ErrorVariable', 'InformationAction', 'InformationVariable', 'OutBuffer', 'OutVariable', 'PipelineVariable', 'Verbose', 'WarningAction', 'WarningVariable'
+ $common = 'Debug', 'ErrorAction', 'ErrorVariable', 'InformationAction', 'InformationVariable', 'OutBuffer', 'OutVariable', 'PipelineVariable', 'Verbose', 'WarningAction', 'WarningVariable', 'ProgressAction'
$parameters = $command.ParameterSets.Parameters | Sort-Object -Property Name -Unique | Where-Object Name -notin $common
$parameterNames = $parameters.Name
diff --git a/PSFramework/tests/pester.ps1 b/PSFramework/tests/pester.ps1
index 66e85ab9..68a0081d 100644
--- a/PSFramework/tests/pester.ps1
+++ b/PSFramework/tests/pester.ps1
@@ -12,7 +12,10 @@
$Exclude = "",
[switch]
- $NoError
+ $NoError,
+
+ [switch]
+ $NoImport
)
Write-Host "Starting Tests"
@@ -20,19 +23,22 @@ Write-Host "Starting Tests"
Write-Host "Importing Module"
$global:testroot = $PSScriptRoot
-$global:__pester_data = @{ }
+$global:__pester_data = @{
+ CommonParameters = 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'ProgressAction'
+}
-Remove-Module PSFramework -ErrorAction Ignore
-Import-Module "$PSScriptRoot\..\PSFramework.psd1"
-Import-Module PSModuleDevelopment
-Import-Module "$PSScriptRoot\..\PSFramework.psm1" -Force
+if (-not $NoImport) {
+ Remove-Module PSFramework -ErrorAction Ignore
+ Import-Module "$PSScriptRoot\..\PSFramework.psd1"
+ Import-Module PSModuleDevelopment
+ Import-Module "$PSScriptRoot\..\PSFramework.psm1" -Force
-# Need to import explicitly so we can use the configuration class
-Import-Module Pester
+ # Need to import explicitly so we can use the configuration class
+ Import-Module Pester
+}
# Load Extensions
-foreach ($file in Get-ChildItem "$PSScriptRoot\extensions" -Filter '*.ps1')
-{
+foreach ($file in Get-ChildItem "$PSScriptRoot\extensions" -Filter '*.ps1') {
. $file.FullName
}
@@ -47,11 +53,9 @@ $config = [PesterConfiguration]::Default
$config.TestResult.Enabled = $true
#region Run General Tests
-if ($TestGeneral)
-{
+if ($TestGeneral) {
Write-PSFMessage -Level Important -Message "Modules imported, proceeding with general tests"
- foreach ($file in (Get-ChildItem "$PSScriptRoot\general" | Where-Object Name -like "*.Tests.ps1"))
- {
+ foreach ($file in (Get-ChildItem "$PSScriptRoot\general" | Where-Object Name -Like "*.Tests.ps1")) {
if ($file.Name -notlike $Include) { continue }
if ($file.Name -like $Exclude) { continue }
@@ -60,17 +64,16 @@ if ($TestGeneral)
$config.Run.Path = $file.FullName
$config.Run.PassThru = $true
$config.Output.Verbosity = $Output
- $results = Invoke-Pester -Configuration $config
- foreach ($result in $results)
- {
+ $results = Invoke-Pester -Configuration $config
+ foreach ($result in $results) {
$totalRun += $result.TotalCount
$totalFailed += $result.FailedCount
- $result.Tests | Where-Object Result -ne 'Passed' | ForEach-Object {
+ $result.Tests | Where-Object Result -NE 'Passed' | ForEach-Object {
$testresults += [pscustomobject]@{
- Block = $_.Block
- Name = "It $($_.Name)"
- Result = $_.Result
- Message = $_.ErrorRecord.DisplayErrorMessage
+ Block = $_.Block
+ Name = "It $($_.Name)"
+ Result = $_.Result
+ Message = $_.ErrorRecord.DisplayErrorMessage
}
}
}
@@ -81,11 +84,9 @@ if ($TestGeneral)
$global:__pester_data.ScriptAnalyzer | Out-Host
#region Test Commands
-if ($TestFunctions)
-{
+if ($TestFunctions) {
Write-PSFMessage -Level Important -Message "Proceeding with individual tests"
- foreach ($file in (Get-ChildItem "$PSScriptRoot\functions" -Recurse -File | Where-Object Name -like "*Tests.ps1"))
- {
+ foreach ($file in (Get-ChildItem "$PSScriptRoot\functions" -Recurse -File | Where-Object Name -Like "*Tests.ps1")) {
if ($file.Name -notlike $Include) { continue }
if ($file.Name -like $Exclude) { continue }
@@ -94,17 +95,16 @@ if ($TestFunctions)
$config.Run.Path = $file.FullName
$config.Run.PassThru = $true
$config.Output.Verbosity = $Output
- $results = Invoke-Pester -Configuration $config
- foreach ($result in $results)
- {
+ $results = Invoke-Pester -Configuration $config
+ foreach ($result in $results) {
$totalRun += $result.TotalCount
$totalFailed += $result.FailedCount
- $result.Tests | Where-Object Result -ne 'Passed' | ForEach-Object {
+ $result.Tests | Where-Object Result -NE 'Passed' | ForEach-Object {
$testresults += [pscustomobject]@{
- Block = $_.Block
- Name = "It $($_.Name)"
- Result = $_.Result
- Message = $_.ErrorRecord.DisplayErrorMessage
+ Block = $_.Block
+ Name = "It $($_.Name)"
+ Result = $_.Result
+ Message = $_.ErrorRecord.DisplayErrorMessage
}
}
}
@@ -120,7 +120,6 @@ $testresults | Sort-Object Block, Name, Result, Message | Format-List
if ($totalFailed -eq 0) { Write-PSFMessage -Level Critical -Message "All $totalRun tests executed without a single failure!" }
else { Write-PSFMessage -Level Critical -Message "$totalFailed tests out of $totalRun tests failed!" }
-if ($totalFailed -gt 0)
-{
+if ($totalFailed -gt 0) {
throw "$totalFailed / $totalRun tests failed!"
}
\ No newline at end of file
diff --git a/PSFramework/xml/PSFramework.Format.ps1xml b/PSFramework/xml/PSFramework.Format.ps1xml
index a7e6a8bd..7bfe5518 100644
--- a/PSFramework/xml/PSFramework.Format.ps1xml
+++ b/PSFramework/xml/PSFramework.Format.ps1xml
@@ -714,6 +714,53 @@
+
+
+ PSFramework.TabExpansion.ScriptContainer
+
+ PSFramework.TabExpansion.ScriptContainer
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Name
+
+
+ LastExecution
+
+
+ LastDuration
+
+
+ Global
+
+
+ AutoTraining
+
+
+ FuzzyMatch
+
+
+ MatchAnywhere
+
+
+
+
+
+
+
PSFramework.TaskEngine.PsfTask
diff --git a/build/psf-prerequisites.ps1 b/build/psf-prerequisites.ps1
new file mode 100644
index 00000000..572bb540
--- /dev/null
+++ b/build/psf-prerequisites.ps1
@@ -0,0 +1,4 @@
+Invoke-WebRequest https://raw.githubusercontent.com/PowershellFrameworkCollective/PSFramework.NuGet/refs/heads/master/bootstrap.ps1 | Invoke-Expression
+Install-PSFPowerShellGet
+
+Install-PSFModule -Name Pester,PSScriptAnalyzer, PlatyPS, PSModuleDevelopment
\ No newline at end of file
diff --git a/build/vsts-help-update.ps1 b/build/vsts-help-update.ps1
index a6935569..294d1652 100644
--- a/build/vsts-help-update.ps1
+++ b/build/vsts-help-update.ps1
@@ -1,5 +1,12 @@
Import-Module PlatyPS -ErrorAction Stop
Import-Module "$PSScriptRoot\..\PSFramework\PSFramework.psd1" -Force -ErrorAction Stop
-foreach ($file in Get-ChildItem -Path "$PSScriptRoot\..\help\en-us" -Filter *.md) {
+
+$helpRoot = "$PSScriptRoot\..\help\en-us"
+
+foreach ($file in Get-ChildItem -Path $helpRoot -Filter *.md) {
Update-MarkdownHelp -Path $file.FullName
+}
+foreach ($command in Get-Command -Module PSFramework -CommandType Cmdlet) {
+ if (Test-Path -Path "$helpRoot\$($command.Name).md") { continue }
+ New-MarkdownHelp -Command $command.Name -OutputFolder $helpRoot
}
\ No newline at end of file
diff --git a/build/vsts-release.ps1 b/build/vsts-release.ps1
new file mode 100644
index 00000000..7c2ee833
--- /dev/null
+++ b/build/vsts-release.ps1
@@ -0,0 +1,32 @@
+[CmdletBinding()]
+param (
+
+)
+
+# Step 1: Generate Module Content
+$moduleVersion = (Import-PowerShellDataFile -Path "$PSScriptRoot\..\PSFramework\PSFramework.psd1").ModuleVersion
+& "$PSScriptRoot\vsts-build.ps1" -SkipPublish
+
+# Step 2: Zip Module Content
+Compress-Archive -Path "$PSScriptRoot\..\publish\PSFramework\*" -DestinationPath "$PSScriptRoot\..\publish\PSFramework.zip" -Force
+
+# Step 3: Create Release
+$response = Invoke-RestMethod -Method POST -Uri 'https://api.github.com/repos/PowershellFrameworkCollective/PSFramework/releases' -Headers @{
+ Authorization = "Bearer $env:GH_TOKEN"
+ Accept = 'application/vnd.github+json'
+ 'X-GitHub-Api-Version' = '2022-11-28'
+} -Body (@{
+ tag_name = "v$moduleVersion"
+ name = "v$moduleVersion"
+ body = "Releasing v$moduleVersion of the PSFramework module."
+ make_latest = 'true'
+} | ConvertTo-Json -Depth 10 -Compress)
+
+# Step 4: Upload ZIP as Release content
+
+Invoke-RestMethod -Method POST -Uri "$($response.assets_url -replace 'api\.github\.com', 'uploads.github.com')?name=PSFramework.zip" -Headers @{
+ Authorization = "Bearer $env:GH_TOKEN"
+ Accept = 'application/vnd.github+json'
+ 'X-GitHub-Api-Version' = '2022-11-28'
+ 'Content-Type' = 'application/octet-stream'
+} -InFile "$PSScriptRoot\..\publish\PSFramework.zip"
diff --git a/help/en-us/Assert-PSFInternalCommand.md b/help/en-us/Assert-PSFInternalCommand.md
new file mode 100644
index 00000000..5cd6317f
--- /dev/null
+++ b/help/en-us/Assert-PSFInternalCommand.md
@@ -0,0 +1,85 @@
+---
+external help file: PSFramework.dll-Help.xml
+Module Name: PSFramework
+online version:
+schema: 2.0.0
+---
+
+# Assert-PSFInternalCommand
+
+## SYNOPSIS
+Verifies, that the command calling it in turn was only called from another command within the same module.
+
+## SYNTAX
+
+```
+Assert-PSFInternalCommand -PSCmdlet [-ProgressAction ] []
+```
+
+## DESCRIPTION
+Verifies, that the command calling it in turn was only called from another command within the same module.
+
+Modules can have their internal commands accessed directly from outside of their own module.
+For example, by loading the psm1 file - or their own ps1 file, if they are shipped separately - it becomes possible, to circumvent the verified interface of the publicly exposed command.
+In a secure code management scenario, where validated modules are allowlisted, this might allow attackers
+to execute commands flagged as trusted, that should not be exposed directly.
+
+With this command, we can prevent this issue, but potentially make development harder.
+It is recommended to place this command only as part of the build step - for example by putting it into the code commented out,
+then remove the comment during build, before publishing the module.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+PS C:\> Assert-PSFInternalCommand -PSCmdlet $PSCmdlet
+```
+
+Ensures the current command calling Assert-PSFInternalCommand was only called from another command in the same module.
+
+## PARAMETERS
+
+### -PSCmdlet
+The $PSCmdlet variable of the calling command.
+This ensures that any exceptions are thrown in the context of the calling command, making this Cmdlet functionally invisible.
+
+```yaml
+Type: PSCmdlet
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ProgressAction
+{{ Fill ProgressAction Description }}
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### None
+
+## OUTPUTS
+
+### System.Object
+## NOTES
+
+## RELATED LINKS
diff --git a/help/en-us/ConvertTo-PSFHashtable.md b/help/en-us/ConvertTo-PSFHashtable.md
index 9737bf4d..447df11b 100644
--- a/help/en-us/ConvertTo-PSFHashtable.md
+++ b/help/en-us/ConvertTo-PSFHashtable.md
@@ -14,7 +14,7 @@ Converts an object into a hashtable.
```
ConvertTo-PSFHashtable [-Include ] [-Exclude ] [-CaseSensitive] [-IncludeEmpty] [-Inherit]
- [-Remap ] [-InputObject ] [-ReferenceCommand ]
+ [-InheritParameters] [-Remap ] [-InputObject ] [-ReferenceCommand ]
[-ReferenceParameterSetName ] [-AsPsfHashtable] [-ProgressAction ]
[]
```
@@ -223,6 +223,23 @@ Accept pipeline input: False
Accept wildcard characters: False
```
+### -InheritParameters
+Automatically include all values from the parameters of the calling command or script.
+This will include all parameters that were explicitly bound or have default parameter values, unless they have been excluded or are not part of a spceified -ReferenceCommand.
+Combine with -IncludeEmpty to also include parameters with neither default value nor being bound.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
### CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
diff --git a/help/en-us/Invoke-PSFProtectedCommand.md b/help/en-us/Invoke-PSFProtectedCommand.md
index 403e6d3b..425f8575 100644
--- a/help/en-us/Invoke-PSFProtectedCommand.md
+++ b/help/en-us/Invoke-PSFProtectedCommand.md
@@ -18,7 +18,8 @@ Invoke-PSFProtectedCommand -ScriptBlock -Action [-Target
[-EnableException ] [-PSCmdlet ] [-Continue] [-ContinueLabel ] [-Tag ]
[-RetryCount ] [-RetryWait ] [-RetryWaitEscalation ]
[-RetryErrorType ] [-RetryCondition ] [-ErrorEvent ]
- [-Level ] [-ProgressAction ] [-WhatIf] [-Confirm] []
+ [-Level ] [-NonTerminating] [-ProgressAction ] [-WhatIf] [-Confirm]
+ []
```
### String
@@ -27,7 +28,8 @@ Invoke-PSFProtectedCommand -ScriptBlock -ActionString [-A
[-Target
[Cmdlet(VerbsData.ConvertTo, "PSFHashtable")]
[OutputType(new Type[] { typeof(Hashtable) })]
- public class ConvertToPSFHashtableCommand : PSCmdlet
+ public class ConvertToPSFHashtableCommand : PSFCmdlet
{
#region Parameters
///
@@ -47,6 +48,12 @@ public class ConvertToPSFHashtableCommand : PSCmdlet
[Parameter()]
public SwitchParameter Inherit;
+ ///
+ /// Inherit from all parameters of the calling command, including all non-bound parameters.
+ ///
+ [Parameter()]
+ public SwitchParameter InheritParameters;
+
///
/// Remap individual keys in the hashtable provided.
/// Effectively renames entries in the hashtable.
@@ -82,6 +89,7 @@ public class ConvertToPSFHashtableCommand : PSCmdlet
StringComparer _Comparison = StringComparer.InvariantCultureIgnoreCase;
List _ToInclude = new List();
+ List _ReferenceParameters = new List();
#region Cmdlet Methods
///
@@ -107,10 +115,12 @@ protected override void BeginProcessing()
CommandInfo info = null;
using (PowerShell ps = PowerShell.Create(RunspaceMode.CurrentRunspace))
{
- ps.AddCommand("Get-Command")
+ ps.AddCommand(InvokeCommand.GetCmdlet("Get-Command"))
.AddParameter("Name", ReferenceCommand)
.AddParameter("ErrorAction", ActionPreference.SilentlyContinue);
- info = ps.Invoke()[0]?.BaseObject as CommandInfo;
+ var result = ps.Invoke();
+ if (result != null && result.Count > 0)
+ info = result[0].BaseObject as CommandInfo;
}
PSFCoreHost.WriteDebug("ConvertTo-PSFHashTable: ReferenceCommand", info);
@@ -118,7 +128,10 @@ protected override void BeginProcessing()
if (info == null)
throw new CommandNotFoundException($"Unable to find command: {ReferenceCommand}");
if (String.IsNullOrEmpty(ReferenceParameterSetName))
+ {
_ToInclude.AddRange(info.Parameters.Keys.ToArray());
+ _ReferenceParameters.AddRange(info.Parameters.Keys.ToArray());
+ }
else
{
var parameterSets = info.ParameterSets.Where(o => String.Equals(o.Name, ReferenceParameterSetName, StringComparison.InvariantCultureIgnoreCase));
@@ -126,6 +139,7 @@ protected override void BeginProcessing()
throw new ArgumentException($"Parameterset {ReferenceParameterSetName} not found on command {info.Name}!");
PSFCoreHost.WriteDebug("ConvertTo-PSFHashTable: ReferenceCommand / ParameterSet", parameterSets);
_ToInclude.AddRange(parameterSets.First().Parameters.Select(o => o.Name).ToArray());
+ _ReferenceParameters.AddRange(parameterSets.First().Parameters.Select(o => o.Name).ToArray());
}
}
@@ -156,8 +170,16 @@ protected override void ProcessRecord()
}
else
+ {
foreach (string name in inputItem.Properties.Select(o => o.Name))
- result[name] = inputItem.Properties[name].Value;
+ {
+ try { result[name] = inputItem.Properties[name].Value; }
+ catch (Exception e){
+ PSFCoreHost.WriteDebug($"ConvertTo-PSFHashTable: Failed to access property {name}: {e.Message}", e);
+ result[name] = null;
+ }
+ }
+ }
if (Exclude.Length > 0)
foreach (string key in Exclude.Where(o => result.ContainsKey(o)))
@@ -170,22 +192,37 @@ protected override void ProcessRecord()
foreach (string key in keys.Where(o => !_ToInclude.Contains(o.ToString(), _Comparison) && result.ContainsKey(o)))
result.Remove(key);
if (Inherit.ToBool())
- foreach (string name in _ToInclude.Where(o => !result.ContainsKey(o)).Where(o => GetVariableValue(o) != null))
+ foreach (string name in _ToInclude.Where(o => !result.ContainsKey(o) && GetVariableValue(o) != null && (Exclude == null || !Exclude.Contains(o, StringComparer.OrdinalIgnoreCase))))
result[name] = GetVariableValue(name);
if (IncludeEmpty.ToBool())
foreach (string name in _ToInclude.Where(o => !result.ContainsKey(o)))
result[name] = null;
}
+ if (InheritParameters.ToBool())
+ {
+ CallStackFrame caller = GetCaller();
+ Dictionary parameters = GetCommandParameters(caller.InvocationInfo.MyCommand);
+ foreach (ParameterAst parameter in parameters.Values)
+ {
+ if (result.ContainsKey(parameter.Name.VariablePath.UserPath) || (Exclude != null && Exclude.Contains(parameter.Name.VariablePath.UserPath, StringComparer.OrdinalIgnoreCase)))
+ continue;
+ if (!IsValidParameter(parameter, IncludeEmpty.ToBool(), caller.InvocationInfo.BoundParameters))
+ continue;
+ if (_ReferenceParameters.Count > 0 && !_ReferenceParameters.Contains(parameter.Name.VariablePath.UserPath, StringComparer.OrdinalIgnoreCase))
+ continue;
+ result[parameter.Name.VariablePath.UserPath] = GetVariableValue(parameter.Name.VariablePath.UserPath);
+ }
+ }
if (Remap != null)
{
foreach (string key in Remap.Keys)
{
- if (result.ContainsKey(key))
- {
- object value = result[key];
- result.Remove(key);
- result[Remap[key]] = value;
- }
+ if (!result.ContainsKey(key))
+ continue;
+
+ object value = result[key];
+ result.Remove(key);
+ result[Remap[key]] = value;
}
}
@@ -196,5 +233,38 @@ protected override void ProcessRecord()
}
}
#endregion Cmdlet Methods
+
+ #region Internal Helpers
+ private bool IsValidParameter(ParameterAst Parameter, bool IncludeEmpty, Dictionary BoundParameters)
+ {
+ if (Parameter.DefaultValue != null || IncludeEmpty)
+ return true;
+
+ if (BoundParameters.ContainsKey(Parameter.Name.VariablePath.UserPath))
+ return true;
+
+ return false;
+ }
+
+ private Dictionary GetCommandParameters(CommandInfo Command)
+ {
+ Dictionary result = new Dictionary(StringComparer.OrdinalIgnoreCase);
+
+ if (Command as FunctionInfo == null && Command as ScriptInfo == null && Command as ExternalScriptInfo == null)
+ return result;
+
+ if (Command as FunctionInfo != null)
+ foreach (ParameterAst parameter in ((FunctionDefinitionAst)((FunctionInfo)Command).ScriptBlock.Ast).Body.ParamBlock.Parameters)
+ result[parameter.Name.VariablePath.UserPath] = parameter;
+ else if (Command as ExternalScriptInfo != null)
+ foreach (ParameterAst parameter in ((ScriptBlockAst)((ExternalScriptInfo)Command).ScriptBlock.Ast).ParamBlock.Parameters)
+ result[parameter.Name.VariablePath.UserPath] = parameter;
+ else
+ foreach (ParameterAst parameter in ((ScriptBlockAst)((ScriptInfo)Command).ScriptBlock.Ast).ParamBlock.Parameters)
+ result[parameter.Name.VariablePath.UserPath] = parameter;
+
+ return result;
+ }
+ #endregion Internal Helpers
}
}
\ No newline at end of file
diff --git a/library/PSFramework/Commands/InvokePSFProtectedCommand.cs b/library/PSFramework/Commands/InvokePSFProtectedCommand.cs
index 8c2a464e..24e47a75 100644
--- a/library/PSFramework/Commands/InvokePSFProtectedCommand.cs
+++ b/library/PSFramework/Commands/InvokePSFProtectedCommand.cs
@@ -2,6 +2,7 @@
using PSFramework.Utility;
using System;
using System.Collections;
+using System.Diagnostics;
using System.Linq;
using System.Management.Automation;
using System.Text;
@@ -122,6 +123,12 @@ public class InvokePSFProtectedCommand : PSFCmdlet
///
[Parameter()]
public Message.MessageLevel Level = Message.MessageLevel.SomewhatVerbose;
+
+ ///
+ /// Make the final error generated a nonterminating error
+ ///
+ [Parameter()]
+ public SwitchParameter NonTerminating;
#endregion Parameters
#region Private Fields
@@ -289,6 +296,29 @@ protected override void ProcessRecord()
private void Terminate(Exception error)
{
ErrorEventAction(error);
+ if (NonTerminating.ToBool())
+ {
+ WriteMessage(_ErrorMessage, Message.MessageLevel.Error, _Caller.CallerFunction, _Caller.CallerModule, _Caller.CallerFile, _Caller.CallerLine, Tag, Target, null, error);
+ if (EnableException)
+ {
+ if (error as RuntimeException != null)
+ PSCmdlet.WriteError(((RuntimeException)error).ErrorRecord);
+ else
+ PSCmdlet.WriteError(
+ new ErrorRecord(
+ error,
+ "ItFailed",
+ ErrorCategory.NotSpecified,
+ Target
+ )
+ );
+ }
+
+ if (Continue)
+ DoContinue(ContinueLabel);
+ return;
+ }
+
ScriptBlock errorBlock = ScriptBlock.Create(_ErrorScript);
object[] arguments = new object[] { _ErrorMessage, error, Target, Continue, ContinueLabel, _Caller.CallerFunction, _Caller.CallerModule, _Caller.CallerFile, _Caller.CallerLine, PSCmdlet, EnableException };
PSCmdlet.InvokeCommand.InvokeScript(false, errorBlock, null, arguments);
diff --git a/library/PSFramework/Commands/PSFCmdlet.cs b/library/PSFramework/Commands/PSFCmdlet.cs
index 5f3b2763..1930d058 100644
--- a/library/PSFramework/Commands/PSFCmdlet.cs
+++ b/library/PSFramework/Commands/PSFCmdlet.cs
@@ -7,7 +7,7 @@
using System.Collections.Generic;
using System.Linq;
using System.Management.Automation;
-using System.Reflection.Emit;
+using System.Reflection;
namespace PSFramework.Commands
{
@@ -109,7 +109,8 @@ public bool TestFeature(string Name)
/// Tags to attach to this message
/// A target object to specify
/// Add additional metadata to the message written
- public void WriteMessage(string Message, MessageLevel Level, string FunctionName, string ModuleName, string File, int Line, string[] Tag, object Target, Hashtable Data = null)
+ /// Exception to include in the message
+ public void WriteMessage(string Message, MessageLevel Level, string FunctionName, string ModuleName, string File, int Line, string[] Tag, object Target, Hashtable Data = null, Exception Error = null)
{
using (PowerShell ps = PowerShell.Create(RunspaceMode.CurrentRunspace))
{
@@ -122,8 +123,11 @@ public void WriteMessage(string Message, MessageLevel Level, string FunctionName
.AddParameter("File", File)
.AddParameter("Line", Line)
.AddParameter("Tag", Tag)
- .AddParameter("Target", Target)
- .AddParameter("Data", Data);
+ .AddParameter("Target", Target);
+ if (Data != null)
+ ps.AddParameter("Data", Data);
+ if (Error != null)
+ ps.AddParameter("Exception", Error);
ps.Invoke();
}
}
@@ -141,7 +145,8 @@ public void WriteMessage(string Message, MessageLevel Level, string FunctionName
/// Tags to attach to this message
/// A target object to specify
/// Add additional metadata to the message written
- public void WriteLocalizedMessage(string String, object[] StringValues, MessageLevel Level, string FunctionName, string ModuleName, string File, int Line, string[] Tag, object Target, Hashtable Data = null)
+ /// Exception to include in the message
+ public void WriteLocalizedMessage(string String, object[] StringValues, MessageLevel Level, string FunctionName, string ModuleName, string File, int Line, string[] Tag, object Target, Hashtable Data = null, Exception Error = null)
{
using (PowerShell ps = PowerShell.Create(RunspaceMode.CurrentRunspace))
{
@@ -155,8 +160,11 @@ public void WriteLocalizedMessage(string String, object[] StringValues, MessageL
.AddParameter("File", File)
.AddParameter("Line", Line)
.AddParameter("Tag", Tag)
- .AddParameter("Target", Target)
- .AddParameter("Data", Data);
+ .AddParameter("Target", Target);
+ if (Data != null)
+ ps.AddParameter("Data", Data);
+ if (Error != null)
+ ps.AddParameter("Exception", Error);
ps.Invoke();
}
}
@@ -243,6 +251,21 @@ public void StopLocalizedCommand(string String, object[] StringValues, Exception
///
public bool IsStopping;
+ ///
+ /// Throw a continue exception, equivalent to calling continue in script
+ ///
+ ///
+ public void DoContinue(string Label = "")
+ {
+ ConstructorInfo[] constructors = typeof(ContinueException).GetConstructors(BindingFlags.NonPublic | BindingFlags.Instance);
+ ConstructorInfo constructor = constructors.Where(o => o.GetParameters().Count() == 0).First();
+ if (String.IsNullOrEmpty(Label))
+ throw (ContinueException)constructor.Invoke(new object[0]);
+
+ constructor = constructors.Where(o => o.GetParameters().Count() == 1 && o.GetParameters()[0].Name == "label").First();
+ throw (ContinueException)constructor.Invoke(new object[] { Label });
+ }
+
///
/// Invokes all applicable callback scripts.
///
diff --git a/library/PSFramework/Commands/SelectPSFObjectCommand.cs b/library/PSFramework/Commands/SelectPSFObjectCommand.cs
index 2fc3c9ab..445ed655 100644
--- a/library/PSFramework/Commands/SelectPSFObjectCommand.cs
+++ b/library/PSFramework/Commands/SelectPSFObjectCommand.cs
@@ -207,36 +207,11 @@ protected override void ProcessRecord()
_Pipeline.Process(InputObject);
else
{
- PSObject item = PSObject.AsPSObject(_Pipeline.Process(InputObject).GetValue(0));
-
- if (KeepInputObject.ToBool())
- {
- PSObject tempItem = item;
- item = InputObject;
- foreach (PSPropertyInfo info in tempItem.Properties.Where(o => !item.Properties.Select(n => n.Name).Contains(o.Name)))
- item.Properties.Add(info);
- }
-
- if (Alias != null)
- foreach (SelectAliasParameter alias in Alias)
- foreach (PSAliasProperty aliasItem in alias.Aliases)
- item.Members.Add(aliasItem);
- if (ScriptMethod != null)
- foreach (SelectScriptMethodParameter method in ScriptMethod)
- foreach (PSScriptMethod methodItem in method.Methods)
- item.Members.Add(methodItem);
- if (ScriptProperty != null)
- foreach (SelectScriptPropertyParameter property in ScriptProperty)
- foreach (PSScriptProperty propertyItem in property.Value)
- item.Members.Add(propertyItem);
-
- if (ShowProperty.Length > 0)
- item.Members.Add(new PSMemberSet("PSStandardMembers", _DisplayPropertySet));
- else if (ShowExcludeProperty.Length > 0)
- item.Members.Add(new PSMemberSet("PSStandardMembers", new PSMemberInfo[] { new PSPropertySet("DefaultDisplayPropertySet", item.Properties.Select(o => o.Name).Where(o => !ShowExcludeProperty.Contains(o))) }));
- if (!String.IsNullOrEmpty(TypeName))
- item.TypeNames.Insert(0, TypeName);
- WriteObject(item);
+ Array items = _Pipeline.Process(InputObject);
+ if (items.Length == 0)
+ return;
+ foreach (object item in items)
+ WriteObject(ConvertResult(item));
}
}
@@ -245,8 +220,55 @@ protected override void ProcessRecord()
///
protected override void EndProcessing()
{
- _Pipeline.End();
+ Array items = _Pipeline.End();
+
+ if (items.Length == 0)
+ return;
+ foreach (object item in items)
+ WriteObject(ConvertResult(item));
}
#endregion Command Implementation
+
+ #region Internal Helpers
+ ///
+ /// Converts a select-object result based on extra elements to add
+ ///
+ /// The item to convert / extend
+ /// A fully converted object
+ private PSObject ConvertResult(object Item)
+ {
+ PSObject item = PSObject.AsPSObject(Item);
+
+ if (KeepInputObject.ToBool())
+ {
+ PSObject tempItem = item;
+ item = InputObject;
+ foreach (PSPropertyInfo info in tempItem.Properties.Where(o => !item.Properties.Select(n => n.Name).Contains(o.Name)))
+ item.Properties.Add(info);
+ }
+
+ if (Alias != null)
+ foreach (SelectAliasParameter alias in Alias)
+ foreach (PSAliasProperty aliasItem in alias.Aliases)
+ item.Members.Add(aliasItem);
+ if (ScriptMethod != null)
+ foreach (SelectScriptMethodParameter method in ScriptMethod)
+ foreach (PSScriptMethod methodItem in method.Methods)
+ item.Members.Add(methodItem);
+ if (ScriptProperty != null)
+ foreach (SelectScriptPropertyParameter property in ScriptProperty)
+ foreach (PSScriptProperty propertyItem in property.Value)
+ item.Members.Add(propertyItem);
+
+ if (ShowProperty.Length > 0)
+ item.Members.Add(new PSMemberSet("PSStandardMembers", _DisplayPropertySet));
+ else if (ShowExcludeProperty.Length > 0)
+ item.Members.Add(new PSMemberSet("PSStandardMembers", new PSMemberInfo[] { new PSPropertySet("DefaultDisplayPropertySet", item.Properties.Select(o => o.Name).Where(o => !ShowExcludeProperty.Contains(o))) }));
+ if (!String.IsNullOrEmpty(TypeName))
+ item.TypeNames.Insert(0, TypeName);
+
+ return item;
+ }
+ #endregion Internal Helpers
}
}
diff --git a/library/PSFramework/Commands/UpdatePSFTeppCompletionCommand.cs b/library/PSFramework/Commands/UpdatePSFTeppCompletionCommand.cs
new file mode 100644
index 00000000..54d17d3e
--- /dev/null
+++ b/library/PSFramework/Commands/UpdatePSFTeppCompletionCommand.cs
@@ -0,0 +1,55 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Text;
+using System.Threading.Tasks;
+
+using PSFramework.Meta;
+using PSFramework.TabExpansion;
+
+namespace PSFramework.Commands
+{
+ ///
+ /// Imports provided values to parameters configured for an auto-training completer.
+ ///
+ [Cmdlet(VerbsData.Update, "PSFTeppCompletion")]
+ public class UpdatePSFTeppCompletionCommand : PSFCmdlet
+ {
+ ///
+ /// Execute the main (and only) step: Copying over values provided to the calling command as parameter into the completion cache.
+ /// Only applies to parameters configured for auto-training tab completers.
+ ///
+ protected override void ProcessRecord()
+ {
+ CallStackFrame caller = GetCaller();
+ foreach (var pair in caller.InvocationInfo.BoundParameters)
+ {
+ // If the parameter does not exist, something weird is happening and we want no part in it
+ if (!caller.InvocationInfo.MyCommand.Parameters.ContainsKey(pair.Key))
+ continue;
+
+ PsfArgumentCompleterAttribute attribute = (PsfArgumentCompleterAttribute)caller.InvocationInfo.MyCommand.Parameters[pair.Key].Attributes.Where(o => o.TypeId.ToString() == "PSFramework.TabExpansion.PsfArgumentCompleterAttribute").FirstOrDefault();
+ // Without our Argument Completer attribute, there is nothing to cache
+ if (attribute == null || attribute.CompletionName == "")
+ continue;
+
+ // Do not cache if completer does not exist or is not configured to autocache
+ if (!TabExpansionHost.Scripts.ContainsKey(attribute.CompletionName) || !TabExpansionHost.Scripts[attribute.CompletionName].AutoTraining)
+ continue;
+
+ // Do not cache empty values
+ if (pair.Value == null)
+ continue;
+
+ string converted = LanguagePrimitives.ConvertTo(pair.Value);
+
+ // Do not cache values that resolve to empty-string or their typename
+ if (String.IsNullOrEmpty(converted) || converted == pair.Value.GetType().FullName)
+ continue;
+
+ TabExpansionHost.Scripts[attribute.CompletionName].AddTraining(converted);
+ }
+ }
+ }
+}
diff --git a/library/PSFramework/Commands/WritePSFMessageCommand.cs b/library/PSFramework/Commands/WritePSFMessageCommand.cs
index dae1752b..0a577eca 100644
--- a/library/PSFramework/Commands/WritePSFMessageCommand.cs
+++ b/library/PSFramework/Commands/WritePSFMessageCommand.cs
@@ -1,4 +1,5 @@
using PSFramework.Message;
+using PSFramework.Utility;
using System;
using System.Collections;
using System.Collections.Generic;
@@ -147,8 +148,16 @@ public class WritePSFMessageCommand : PSCmdlet
/// This is less user friendly, but allows catching exceptions in calling scripts.
///
[Parameter()]
+ [TypeTransformation(typeof(Boolean))]
public bool EnableException;
+ ///
+ /// Create a new error record, using the current message, then write it.
+ /// This parameter is only respected if EnableException is set to true.
+ ///
+ [Parameter()]
+ public SwitchParameter NewErrorRecord;
+
///
/// Enables breakpoints on the current message. By default, setting '-Debug' will NOT cause an interrupt on the current position.
///
@@ -525,7 +534,7 @@ whether this function was called from Stop-PSFFunction.
InvokeCommand.InvokeScript(@"$VerbosePreference = 'Continue'");
//SessionState.PSVariable.Set("VerbosePreference", ActionPreference.Continue);
- WriteVerbose(_MessageStreams);
+ WriteVerbose(_MessageStreams);
channels = channels | LogEntryType.Verbose;
}
@@ -567,10 +576,22 @@ whether this function was called from Stop-PSFFunction.
}
#region Error handling p2
- if (ErrorRecord != null)
- if (!_fromStopFunction && EnableException)
+ if (!_fromStopFunction && EnableException)
+ {
+ if (NewErrorRecord)
+ {
+ ErrorRecord record = new ErrorRecord(
+ new Exception(_errorQualifiedMessage),
+ "ErrorMessage",
+ ErrorCategory.NotSpecified,
+ Target
+ );
+ PSCmdlet.WriteError(record);
+ }
+ else if (ErrorRecord != null)
foreach (ErrorRecord record in ErrorRecord)
PSCmdlet.WriteError(record);
+ }
#endregion Error handling p2
}
#endregion Cmdlet Implementation
@@ -782,7 +803,10 @@ private string GetMessageColor()
levelDisplay = $"[{Level}]";
string timeStamp = "";
if (MessageHost.EnableMessageTimestamp)
- timeStamp = $"[{_timestamp.ToString("HH:mm:ss")}]";
+ timeStamp = $"[{_timestamp.ToString(MessageHost.TimeFormat)}]";
+ string target = "";
+ if (MessageHost.EnableMessageTarget && Target != null)
+ target = $"[{Target.ToString()}]";
string breadCrumbs = "";
if (MessageHost.EnableMessageBreadcrumbs)
breadCrumbs = _BreadCrumbsStringColored;
@@ -790,7 +814,7 @@ private string GetMessageColor()
if (MessageHost.EnableMessageDisplayCommand && !MessageHost.EnableMessageBreadcrumbs)
functionText = $"[{FunctionName}]";
- string header = String.Join("", timeStamp, functionText, levelDisplay, breadCrumbs);
+ string header = String.Join("", timeStamp, functionText, levelDisplay, target, breadCrumbs);
if (MessageHost.EnableMessageBreadcrumbs)
_messageColor = String.Join("", header, _errorQualifiedMessage);
diff --git a/library/PSFramework/Configuration/ConfigurationHost.cs b/library/PSFramework/Configuration/ConfigurationHost.cs
index fd36354a..10c033cd 100644
--- a/library/PSFramework/Configuration/ConfigurationHost.cs
+++ b/library/PSFramework/Configuration/ConfigurationHost.cs
@@ -139,6 +139,8 @@ public static object ConvertFromPersistedValue(string PersistedValue, Configurat
case ConfigurationValueType.ConsoleColor:
return Enum.Parse(typeof(ConsoleColor), PersistedValue);
case ConfigurationValueType.Hashtable:
+ if (PersistedValue == "")
+ return new Hashtable(StringComparer.OrdinalIgnoreCase);
string[] hashItems = PersistedValue.Split(new string[1] { "þHþ" }, StringSplitOptions.None);
Hashtable tempTable = new Hashtable();
foreach (string tempValue in hashItems)
diff --git a/library/PSFramework/Data/Converters/ArrayConverter.cs b/library/PSFramework/Data/Converters/ArrayConverter.cs
new file mode 100644
index 00000000..03932e0a
--- /dev/null
+++ b/library/PSFramework/Data/Converters/ArrayConverter.cs
@@ -0,0 +1,38 @@
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PSFramework.Data.Converters
+{
+ ///
+ /// Converts data structures into PSD1 Strings
+ ///
+ public class ArrayConverter : IPsd1Converter
+ {
+ ///
+ /// Converts to psd1 string
+ ///
+ /// The object to convert
+ /// The indentation level
+ /// The conversion runtime object, including its settings.
+ /// The parent objects. Used in complex data types to prevent infinite recursion.
+ /// The converted PSD1 representation of the value provided
+ public string Convert(object Value, object[] Parents, int Depth, Psd1Converter Converter)
+ {
+ StringBuilder sb = new StringBuilder();
+ string indent = new string(' ', Depth * 4);
+ string newIndent = new string(' ', (Depth + 1) * 4);
+ sb.AppendLine("@(");
+
+ foreach (object item in (IEnumerable)Value)
+ sb.AppendLine($"{newIndent}{DataHost.Convert(item, Parents, Depth + 1, Converter)}");
+
+ sb.Append($"{indent})");
+ return sb.ToString();
+ }
+ }
+}
diff --git a/library/PSFramework/Data/Converters/AssemblyConverter.cs b/library/PSFramework/Data/Converters/AssemblyConverter.cs
new file mode 100644
index 00000000..aa4f853f
--- /dev/null
+++ b/library/PSFramework/Data/Converters/AssemblyConverter.cs
@@ -0,0 +1,29 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Reflection;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PSFramework.Data.Converters
+{
+ ///
+ /// Converts data structures into PSD1 Strings
+ ///
+ public class AssemblyConverter : IPsd1Converter
+ {
+ ///
+ /// Converts to psd1 string
+ ///
+ /// The object to convert
+ /// The indentation level
+ /// The conversion runtime object, including its settings.
+ /// The parent objects. Used in complex data types to prevent infinite recursion.
+ /// The converted PSD1 representation of the value provided
+ public string Convert(object Value, object[] Parents, int Depth, Psd1Converter Converter)
+ {
+ return $"'{((Assembly)Value).FullName}'";
+ }
+ }
+}
diff --git a/library/PSFramework/Data/Converters/BoolConverter.cs b/library/PSFramework/Data/Converters/BoolConverter.cs
new file mode 100644
index 00000000..d94c0fc7
--- /dev/null
+++ b/library/PSFramework/Data/Converters/BoolConverter.cs
@@ -0,0 +1,28 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PSFramework.Data.Converters
+{
+ ///
+ /// Converts data structures into PSD1 Strings
+ ///
+ public class BoolConverter : IPsd1Converter
+ {
+ ///
+ /// Converts to psd1 string
+ ///
+ /// The object to convert
+ /// The indentation level
+ /// The conversion runtime object, including its settings.
+ /// The parent objects. Used in complex data types to prevent infinite recursion.
+ /// The converted PSD1 representation of the value provided
+ public string Convert(object Value, object[] Parents, int Depth, Psd1Converter Converter)
+ {
+ return $"${Value}";
+ }
+ }
+}
diff --git a/library/PSFramework/Data/Converters/CustomConverter.cs b/library/PSFramework/Data/Converters/CustomConverter.cs
new file mode 100644
index 00000000..93841d1d
--- /dev/null
+++ b/library/PSFramework/Data/Converters/CustomConverter.cs
@@ -0,0 +1,100 @@
+using PSFramework.Utility;
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Management.Automation.Language;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PSFramework.Data.Converters
+{
+ ///
+ /// Converts data structures into PSD1 Strings
+ ///
+ public class CustomConverter : IPsd1Converter
+ {
+ ///
+ /// The type the custom converter is assigned to
+ ///
+ public Type AssignedType;
+
+ ///
+ /// The code calculating the new PSD1-String
+ ///
+ public PsfScriptBlock Code;
+
+ ///
+ /// Any additional properties to assign to this.
+ /// These properties are made available to the code via the $this variable
+ ///
+ public Hashtable Properties = new Hashtable(StringComparer.OrdinalIgnoreCase);
+
+ ///
+ /// The result to return as a default.
+ /// This is mostly used in combination with "OnErrorDefault"
+ ///
+ public string DefaultResult = "$null";
+
+ ///
+ /// Whether in case of an error it should just return a default string, rather than failing the entire conversion.
+ ///
+ public bool OnErrorDefault = false;
+
+ ///
+ /// Converts to psd1 string
+ ///
+ /// The object to convert
+ /// The indentation level
+ /// The conversion runtime object, including its settings.
+ /// The parent objects. Used in complex data types to prevent infinite recursion.
+ /// The converted PSD1 representation of the value provided
+ public string Convert(object Value, object[] Parents, int Depth, Psd1Converter Converter)
+ {
+ Hashtable data = new Hashtable(StringComparer.OrdinalIgnoreCase);
+ data["Converter"] = Converter;
+ data["Properties"] = Properties;
+ data["Depth"] = Depth;
+ data["Parents"] = Parents;
+ data["Value"] = Value;
+
+ System.Collections.ObjectModel.Collection results = null;
+ try { results = Code.InvokeEx(false, Value, Value, data, false, false, Depth, Converter); }
+ catch (Exception e) {
+ Converter.WriteVerbose($"Custom Converter Error. Assigned Type: {AssignedType.Name} | Data: {Value} | Error: {e.Message}");
+ if (OnErrorDefault)
+ return DefaultResult;
+ throw e;
+ }
+
+ if (results.Count < 1)
+ {
+ Converter.WriteVerbose($"Custom Converter Failed. Assigned Type: {AssignedType.Name} | Data: {Value} | No results returned");
+ if (OnErrorDefault)
+ return DefaultResult;
+ throw new InvalidOperationException("Custom converter returned no content!");
+ }
+ if (String.IsNullOrEmpty(LanguagePrimitives.ConvertTo(results[0].BaseObject)))
+ {
+ Converter.WriteVerbose($"Custom Converter Failed. Assigned Type: {AssignedType.Name} | Data: {Value} | Results is null or empty");
+ if (OnErrorDefault)
+ return DefaultResult;
+ throw new InvalidOperationException("Custom converter returned null or an empty string!");
+ }
+
+ return LanguagePrimitives.ConvertTo(results[0].BaseObject);
+ }
+
+ ///
+ /// Creates a new custom converter
+ ///
+ /// The type that should be converted
+ /// The code doing the conversion
+ public CustomConverter(Type AssignedType, PsfScriptBlock Code)
+ {
+ this.AssignedType = AssignedType;
+ this.Code = Code;
+ }
+ }
+}
diff --git a/library/PSFramework/Data/Converters/DBNullConverter.cs b/library/PSFramework/Data/Converters/DBNullConverter.cs
new file mode 100644
index 00000000..f42654d3
--- /dev/null
+++ b/library/PSFramework/Data/Converters/DBNullConverter.cs
@@ -0,0 +1,28 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PSFramework.Data.Converters
+{
+ ///
+ /// Converts data structures into PSD1 Strings
+ ///
+ public class DBNullConverter : IPsd1Converter
+ {
+ ///
+ /// Converts to psd1 string
+ ///
+ /// The object to convert
+ /// The indentation level
+ /// The conversion runtime object, including its settings.
+ /// The parent objects. Used in complex data types to prevent infinite recursion.
+ /// The converted PSD1 representation of the value provided
+ public string Convert(object Value, object[] Parents, int Depth, Psd1Converter Converter)
+ {
+ return "$null";
+ }
+ }
+}
diff --git a/library/PSFramework/Data/Converters/DateTimeConverter.cs b/library/PSFramework/Data/Converters/DateTimeConverter.cs
new file mode 100644
index 00000000..b81262e0
--- /dev/null
+++ b/library/PSFramework/Data/Converters/DateTimeConverter.cs
@@ -0,0 +1,28 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PSFramework.Data.Converters
+{
+ ///
+ /// Converts data structures into PSD1 Strings
+ ///
+ public class DateTimeConverter : IPsd1Converter
+ {
+ ///
+ /// Converts to psd1 string
+ ///
+ /// The object to convert
+ /// The indentation level
+ /// The conversion runtime object, including its settings.
+ /// The parent objects. Used in complex data types to prevent infinite recursion.
+ /// The converted PSD1 representation of the value provided
+ public string Convert(object Value, object[] Parents, int Depth, Psd1Converter Converter)
+ {
+ return String.Format("'{0:yyyy-MM-dd HH:mm:ss.fffff zzz}'", Value);
+ }
+ }
+}
diff --git a/library/PSFramework/Data/Converters/DoubleConverter.cs b/library/PSFramework/Data/Converters/DoubleConverter.cs
new file mode 100644
index 00000000..e203b3cb
--- /dev/null
+++ b/library/PSFramework/Data/Converters/DoubleConverter.cs
@@ -0,0 +1,28 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PSFramework.Data.Converters
+{
+ ///
+ /// Converts data structures into PSD1 Strings
+ ///
+ public class DoubleConverter : IPsd1Converter
+ {
+ ///
+ /// Converts to psd1 string
+ ///
+ /// The object to convert
+ /// The indentation level
+ /// The conversion runtime object, including its settings.
+ /// The parent objects. Used in complex data types to prevent infinite recursion.
+ /// The converted PSD1 representation of the value provided
+ public string Convert(object Value, object[] Parents, int Depth, Psd1Converter Converter)
+ {
+ return $"{Value}";
+ }
+ }
+}
diff --git a/library/PSFramework/Data/Converters/FileSystemInfoConverter.cs b/library/PSFramework/Data/Converters/FileSystemInfoConverter.cs
new file mode 100644
index 00000000..67fb674d
--- /dev/null
+++ b/library/PSFramework/Data/Converters/FileSystemInfoConverter.cs
@@ -0,0 +1,67 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using System.Management.Automation.Language;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PSFramework.Data.Converters
+{
+ ///
+ /// Converts data structures into PSD1 Strings
+ ///
+ public class FileSystemInfoConverter : IPsd1Converter
+ {
+ ///
+ /// Converts to psd1 string
+ ///
+ /// The object to convert
+ /// The indentation level
+ /// The conversion runtime object, including its settings.
+ /// The parent objects. Used in complex data types to prevent infinite recursion.
+ /// The converted PSD1 representation of the value provided
+ public string Convert(object Value, object[] Parents, int Depth, Psd1Converter Converter)
+ {
+ object[] newParents = new object[] { Value };
+
+ if (Parents != null)
+ {
+ if (Parents.Contains(Value))
+ return $"'{Value.GetType().FullName} (recursed)'";
+ if (Converter.MaxDepth > 0 && Parents.Length >= Converter.MaxDepth)
+ return $"'{Value.GetType().FullName}'";
+
+ List