en-US/about_ConvertFrom-PowerShellDataFile.txt
|
TOPIC
ConvertFrom-PowerShellDataFile SHORT DESCRIPTION CommandName: ConvertFrom-PowerShellDataFile - CommandType: Function Convert contents of a PowerShell Data File to a hashtable. LONG DESCRIPTION This Command takes the path to a PowerShell Data File (*.psd1) as input, then parses the files contents, and constructs a System.Collections.Hashtable Object from the data stored in the file. PowerShell Data Files, commonly known for their use as Module Manifest files, are PowerShell Files which accept a restricted form of what is considered valid PowerShell Script Syntax. These restrictions include not being capable storing ScriptBlocks, or executable Commands, for example. Rather, .psd1 files typically contain only structured hastables, and supports the use of nested hashtables, a vast array of data types, and these data types can be very highly specified. (Ex. Key = [string]3) As such, conversion of a .psd1 files contents into an in-console Hashtable object is a simple task, as its contents are already inevitably going to be structured heirarchically as a hashtable by design, in the majority of cases. If, however, data stored in the .psd1 file exist independent of a hashtable (i.e. Sets of Key/Value pairs which are NOT contained within a '@{ }' block), then a new hashtable is simply constructed around that data. This also works for cases where the file DOES contain one or more hashtables, AS WELL as content existing externally from those hastables. In which case, the existing hastables become nested within the newly constructed parent hashtable. This conversion is accomplished with the built-in Cmdlet 'Import-PowerShellDataFile'. The output of this Cmdlet is stored within a previously created hashtable object, and finally, a new Variable is created which uses the input files BaseName (Filename without extension or parent path) as its name, and is then assigned the contents of the newly created hashtable as its stored value. The final resulting output is a hashtable object containing the full contents of the input file, which can be referenced/called via a Variable sharing its name with the filename. (Ex. If your input file was a Module Manifest with the filename 'MyModule.psd1', the resulting hashtable can be returned by referencing the newly created Variable '$MyModule') SYNTAX ConvertFrom-PowerShellDataFile [-FilePath] <String> [-Confirm] [-WhatIf] [<CommonParameters>] (CURRENTLY IMPLEMENTED) ConvertFrom-PowerShellDataFile [-FilePath] <String> [-ReturnValue] <String> [-RequireValidation] [-Confirm] [-WhatIf] [<CommonParameters>] (INCLUDES PARAMETERS NOT YET IMPLEMENTED) ALIASES Alias - Name: cfpsd1 Value: ConvertFrom-PowerShellDataFile EXAMPLES PS C:\> ConvertFrom-PowerShellDataFile -FilePath 'C:\test\MyModule\PSScriptAnalyzerSettings.psd1' (Converts the contents of the file 'PSScriptAnalyzerSettings.psd1' into a hashtable, which is then stored in the Variable: '$PSScriptAnalyzerSettings') PS C:\> ConvertFrom-PowerShellDataFile -FilePath 'C:\test\MyModule\MyModule.psd1' -RequireValidation (IF the file 'MyModule.psd1' is recognized as a VALID PowerShell Module Manifest, its cotnents are then converted into a hashtable stored in the Variable: '$MyModule') PS C:\> ConvertFrom-PowerShellDataFile -FilePath 'C:\test\MyModule\MyModule.psd1' -ReturnValue 'RootModule' -RequireValidation (IF the file 'MyModule.psd1' is recognized as a VALID PowerShell Module Manifest, its contents are then converted into a hashtable stored in the Variable: '$MyModule'. Finally, the Value stored in the Key 'RootModule' is returned and displayed automatically in the Console Window, post-conversion. Expected Output: 'MyModule.psm1') RELATED LINKS SFX.PoshUtilities.DataFileTools @ GitHub - 'https://github.com/SupernautFX/SFX.PoshUtilities.DataFileTools' SFX.PoshUtilities.DataFileTools @ PowerShell Gallery - 'https://powershellgallery.com/packages/SFX.PoshUtilities.DataFileTools/' SEE ALSO Developer GitHub - 'https://github.com/SupernautFX' CHANGELOG TODO: Implement 'ReturnValue' and 'RequireValidation' Features ASOF: Saturday 10/23/2021 INFO: ONLY implemented the most BASIC skeleton code for these two Parameters thus far. Enough so that they both accept input, however, neither will actually generate any specific Output. As of now, 'ReturnValue' accepts input but is currently in a state where all of its core implementation code is commented out, so as to avoid conflicts which could potentially lead to terminating Errors and therefore cause the Function to fail to convert file contents if/when a value is passed to the Parameter. Instead, however, anytime the value of 'ReturnValue' is seen to be anything other than '$null'/Empty, a Verbose Message is returned to inform the User of the Parameters current state as Not Yet Implemented. The same is true for the 'RequireValidation' Parameter. TODO: Implement Multi-File Processing ASOF: Saturday 10/23/2021 INFO: Intend to implement the ability for multiple .psd1 files to be processed and converted to hashtables with the resulting objects stored in Variables, each sharing its name with the source files BaseName, all at once. This feature will ONLY be implemented once both 'ReurnValue' and 'RequireValidation' are implemented successfully, as there is potential for conflict when using ReturnValue in conjunction with an array of file paths as input, unless a system of indexing to assign various values passed to ReturnValue to specific files, as ReturnValue itself already accepts an array of values, and such a system would be difficult to implement, namely in such a way which does not over-complicate matters of use and functionality for the end-user. As such, the existence of the ReturnValue Parameter and how it is implemented will determine how Multi-File Processing is implemented, namely, whether an additional Parameter is added which explicitly accepts an array of path values (Ex. a PathList Parameter) and restrict the use of ReturnValue alongside any Path Parameter besides 'FilePath', which accepts only a single value, via use of Parameter Sets, or if it will simply involve the change being made to the FilePath Parameter such that it accepts an array of values. Likewise, RequireValidation may cause/result in potentially terminating Errors anytime it is used in conjuction with an array of file paths, where not every file is a valid Module Manifest, nor does every file need to be. This could either lead to only some files being processed and others throwing exceptions, whether the User intended for the entire array of files to be validated or not, or even in no file being processed regardless of whether or not it is a Valid Manifest, and a terminating Error thrown. BUG: 'ReturnValue' and 'RequireValidation' Parameters Non-Functional ASOF: Friday 10/22/2021 INFO: 'ReturnValue' and 'RequireValidation' Parameters were inproperly implemented, and resulted in incorrect output from the Command when used. FIX: 'ReturnValue' and 'RequireValidation' Parameters - Feature Removal ASOF: Friday 10/22/2021 INFO: Both of the aforementioned Parameters have been functionally removed temporarily and replaced with Verbose Messages informing the User that they are not currently implemented, when specified alongside the Command itself. See "REMOVEDFEATURE: 'ReturnValue' and 'RequireValidation' (INITIAL TEST IMPLEMENTATION)" for more details. ADDEDFEATURE: 'FilePath' Parameter Now Pipeline Capable ASOF: Saturday 10/23/2021 INFO: ConvertFrom-PowerShellDataFile is now officially 100% FULLY Pipeline Capable. Meaning it can now be called from ANY position in the Pipeline OTHER than as the FIRST Command. FilePath now accepts Values from the output of previous Commands in the pipeline, in general, as well as by Property Name. As a result, if the output of a Command happens to be the Path to a .psd1 file, then ConvertFrom-PowerShellDataFile can be called NEXT in the pipeline without need to explicitly specify any file path, and its output can also still be piped to any other command that accepts the appropriate data types as pipeline values. (Ex. Get-ChildItem -Path 'C:\test\files' -Include *.psd1 | ConvertFrom-PowerShellDataFile - Is now perfectly valid syntax for use of the Command. This simple addition to the Parameter block of the function immediately opens up a swath of potential for the Command, as pipeline usage is one of the core, central pillars of PowerShell and is considered one of its greatest strengths, one that makes it such an incredible, and highly capable Scripting Language, on par with, and even surpassing some full blown Programming Languages which share PowerShells Object-Oriented design.) REMOVEDFEATURE: 'ReturnValue' and 'RequireValidation' (INITIAL TEST IMPLEMENTATION) ASOF: Friday 10/22/2021 INFO: 'ReturnValue' and 'RequireValidation' Parameters had previously been implemented, albeit in a VERY rushed and incorrect manner, which resulted in neither of the Parameters working correctly. As such their entire fumctionality has been removed, instead replaced by Messages logged/written to the Verbose Data Stream informing the User of their current state as 'NOT YET IMPLEMENTED' features anytime either of the two Parameters are attempted to be explicitly invoked as arguments of the Command itself. This removal is temporary, and it is intended to be re-implemented in a working state in the next update. |