Get-FileVersion: New command

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `Get-FileVersion`
+  - New public command to return the version information for a file. This command
+    returns the full `System.Diagnostics.FileVersionInfo` object.
+
+### Changed
+
+- Updated build scripts to Sampler 0.119.0-preview0005.
+- `Get-FileProductVersion`
+  - Changed to use the new `Get-FileVersion` command internally instead of
+    directly accessing `Get-Item` and `VersionInfo`.
+
 ### Fixed
 
 - New-*Exception
@@ -16,10 +29,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     TurnOffTypeChecking is used [#184](https://github.com/dsccommunity/DscResource.Common/issues/184).
 - Fix typo in `Clear-ZeroedEnumPropertyValue` help text. Fixes [#181](https://github.com/dsccommunity/DscResource.Common/issues/181).
 
-### Changed
-
-- Updated build scripts to Sampler 0.119.0-preview0005.
-
 ## [0.24.2] - 2025-08-27
 
 ### Changed

source/Private/Assert-RequiredCommandParameter.ps1

@@ -92,12 +92,7 @@ function Assert-RequiredCommandParameter
                         }
 
                         $PSCmdlet.ThrowTerminatingError(
-                            [System.Management.Automation.ErrorRecord]::new(
-                                $errorMessage,
-                                'ARCP0001', # cspell: disable-line
-                                [System.Management.Automation.ErrorCategory]::InvalidOperation,
-                                'Command parameters'
-                            )
+                            (New-ErrorRecord -Exception $errorMessage -ErrorId 'ARCP0001' -ErrorCategory ([System.Management.Automation.ErrorCategory]::InvalidOperation) -TargetObject 'Command parameters')
                         )
                     }
                 }
@@ -123,12 +118,7 @@ function Assert-RequiredCommandParameter
                     }
 
                     $PSCmdlet.ThrowTerminatingError(
-                        [System.Management.Automation.ErrorRecord]::new(
-                            $errorMessage,
-                            'ARCP0002', # cspell: disable-line
-                            [System.Management.Automation.ErrorCategory]::InvalidOperation,
-                            'Command parameters'
-                        )
+                        (New-ErrorRecord -Exception $errorMessage -ErrorId 'ARCP0002' -ErrorCategory ([System.Management.Automation.ErrorCategory]::InvalidOperation) -TargetObject 'Command parameters')
                     )
                 }
 

source/Public/Assert-ElevatedUser.ps1

@@ -56,12 +56,7 @@ function Assert-ElevatedUser
     if (-not $isElevated)
     {
         $PSCmdlet.ThrowTerminatingError(
-            [System.Management.Automation.ErrorRecord]::new(
-                $ErrorMessage,
-                'UserNotElevated',
-                [System.Management.Automation.ErrorCategory]::InvalidOperation,
-                'Command parameters'
-            )
+            (New-ErrorRecord -Exception $ErrorMessage -ErrorId 'UserNotElevated' -ErrorCategory ([System.Management.Automation.ErrorCategory]::InvalidOperation) -TargetObject 'Command parameters')
         )
     }
 }

source/Public/Get-FileProductVersion.ps1

@@ -13,6 +13,14 @@
         Get-FileProductVersion -Path 'C:\Temp\setup.exe'
 
         Returns the product version of the file setup.exe as a System.Version object.
+
+    .INPUTS
+        None.
+
+    .OUTPUTS
+        `System.Version`
+
+        Returns the product version as a System.Version object.
 #>
 function Get-FileProductVersion
 {
@@ -27,14 +35,30 @@ function Get-FileProductVersion
 
     try
     {
-        $fileItem = Get-Item -Path $Path -ErrorAction 'Stop'
-
-        return [System.Version] $fileItem.VersionInfo.ProductVersion
+        $fileVersionInfo = Get-FileVersion -Path $Path -ErrorAction 'Stop'
     }
     catch
     {
         $errorMessage = $script:localizedData.Get_FileProductVersion_GetFileProductVersionError -f $Path, $_.Exception.Message
+        $exception = New-Exception -Message $errorMessage -ErrorRecord $_
+
+        $PSCmdlet.ThrowTerminatingError(
+            (New-ErrorRecord -Exception $exception -ErrorId 'GFPV0001' -ErrorCategory ([System.Management.Automation.ErrorCategory]::ReadError) -TargetObject $Path) # cSpell: disable-line
+        )
+    }
+
+    $productVersionString = $fileVersionInfo.ProductVersion
 
-        Write-Error -Message $errorMessage
+    $parsedVersion = $null
+    if (-not [System.Version]::TryParse($productVersionString, [ref] $parsedVersion))
+    {
+        $errorMessage = $script:localizedData.Get_FileProductVersion_InvalidVersionFormat -f $productVersionString, $Path
+        $exception = New-Exception -Message $errorMessage
+
+        $PSCmdlet.ThrowTerminatingError(
+            (New-ErrorRecord -Exception $exception -ErrorId 'GFPV0002' -ErrorCategory ([System.Management.Automation.ErrorCategory]::InvalidData) -TargetObject $Path) # cSpell: disable-line
+        )
     }
+
+    return $parsedVersion
 }

source/Public/Get-FileVersion.ps1

@@ -0,0 +1,67 @@
+<#
+    .SYNOPSIS
+        Returns the version information for a file.
+
+    .DESCRIPTION
+        Returns the version information for a file including the product version,
+        file version, and other version-related metadata.
+
+    .PARAMETER Path
+        Specifies the file for which to return the version information.
+
+    .EXAMPLE
+        Get-FileVersion -Path 'E:\setup.exe'
+
+        Returns the version information for the file setup.exe.
+
+    .EXAMPLE
+        Get-Item -Path 'E:\setup.exe' | Get-FileVersion
+
+        Returns the version information for the file setup.exe using pipeline input.
+
+    .EXAMPLE
+        'E:\setup.exe' | Get-FileVersion
+
+        Returns the version information for the file setup.exe using pipeline input.
+
+    .INPUTS
+        System.IO.FileInfo
+
+        Accepts a file path via the pipeline.
+
+    .INPUTS
+        System.String
+
+        Accepts a string path via the pipeline.
+
+    .OUTPUTS
+        System.Diagnostics.FileVersionInfo
+
+        Returns the file version information.
+#>
+function Get-FileVersion
+{
+    [OutputType([System.Diagnostics.FileVersionInfo])]
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
+        [Alias('FullName')]
+        [System.IO.FileInfo]
+        $Path
+    )
+
+    process
+    {
+        $file = Get-Item -Path $Path -ErrorAction 'Stop'
+
+        if ($file.PSIsContainer)
+        {
+            $PSCmdlet.ThrowTerminatingError(
+                (New-ErrorRecord -Exception ($script:localizedData.Get_FileVersion_PathIsNotFile -f $file.FullName) -ErrorId 'GFV0001' -ErrorCategory ([System.Management.Automation.ErrorCategory]::InvalidArgument) -TargetObject $file.FullName) # cSpell: disable-line
+            )
+        }
+
+        $file.VersionInfo
+    }
+}

source/Public/Get-PSModulePath.ps1

@@ -135,12 +135,7 @@ function Get-PSModulePath
                     if ([System.String]::IsNullOrEmpty($documentsFolder))
                     {
                         $PSCmdlet.ThrowTerminatingError(
-                            [System.Management.Automation.ErrorRecord]::new(
-                                ($script:localizedData.PSModulePath_MissingMyDocumentsPath -f (Get-UserName)),
-                                'MissingMyDocumentsPath',
-                                [System.Management.Automation.ErrorCategory]::ResourceUnavailable,
-                                (Get-UserName)
-                            )
+                            (New-ErrorRecord -Exception ($script:localizedData.PSModulePath_MissingMyDocumentsPath -f (Get-UserName)) -ErrorId 'MissingMyDocumentsPath' -ErrorCategory ([System.Management.Automation.ErrorCategory]::ResourceUnavailable) -TargetObject (Get-UserName))
                         )
                     }
 

source/Public/New-ErrorRecord.ps1

@@ -52,7 +52,7 @@
             [System.Management.Automation.ErrorCategory]::InvalidOperation,
             $null
         )
-        $newException = [System.Exception]::new('New error')
+        $newException = New-Exception -Message 'New error'
         $newErrorRecord = New-ErrorRecord -ErrorRecord $existingErrorRecord -Exception $newException
         $newErrorRecord.Exception.Message
 

source/en-US/DscResource.Common.strings.psd1

@@ -55,7 +55,11 @@ ConvertFrom-StringData @'
     SearchingForCertificateUsingFilters = Looking for certificate in Store '{0}' using filter '{1}'. (DRC0047)
 
     ## Get-FileProductVersion
-    Get_FileProductVersion_GetFileProductVersionError = Failed to get product version for file '{0}'. Error: {1}
+    Get_FileProductVersion_GetFileProductVersionError = Failed to get product version for file '{0}'. Error: {1} (GFPV0001)
+    Get_FileProductVersion_InvalidVersionFormat = The product version '{0}' for file '{1}' is not a valid version string. (GFPV0002)
+
+    ## Get-FileVersion
+    Get_FileVersion_PathIsNotFile = The specified path is not a file. (GFV0001)
 
     ## Get-PSModulePath
     PSModulePath_MissingMyDocumentsPath = The My Documents folder does not exist for user '{0}'. (DRC0048)

tests/Integration/Commands/Get-FileVersion.Integration.Tests.ps1

@@ -0,0 +1,112 @@
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Suppressing this rule because Script Analyzer does not understand Pester syntax.')]
+param ()
+
+BeforeDiscovery {
+    try
+    {
+        if (-not (Get-Module -Name 'DscResource.Test'))
+        {
+            # Assumes dependencies have been resolved, so if this module is not available, run 'noop' task.
+            if (-not (Get-Module -Name 'DscResource.Test' -ListAvailable))
+            {
+                # Redirect all streams to $null, except the error stream (stream 2)
+                & "$PSScriptRoot/../../../build.ps1" -Tasks 'noop' 3>&1 4>&1 5>&1 6>&1 > $null
+            }
+
+            # If the dependencies have not been resolved, this will throw an error.
+            Import-Module -Name 'DscResource.Test' -Force -ErrorAction 'Stop'
+        }
+    }
+    catch [System.IO.FileNotFoundException]
+    {
+        throw 'DscResource.Test module dependency not found. Please run ".\build.ps1 -Tasks noop" first to set up the test environment.'
+    }
+}
+
+BeforeAll {
+    $script:moduleName = 'DscResource.Common'
+
+    Import-Module -Name $script:moduleName -Force -ErrorAction 'Stop'
+}
+
+Describe 'Get-FileVersion' -Tag 'Integration' {
+    Context 'When running on Windows' -Skip:(-not $IsWindows) {
+        Context 'When getting version information from notepad.exe' {
+            BeforeAll {
+                $script:notepadPath = Join-Path -Path $env:SystemRoot -ChildPath 'System32\notepad.exe'
+            }
+
+            It 'Should return version information for notepad.exe' {
+                $result = Get-FileVersion -Path $script:notepadPath -ErrorAction Stop
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [System.Diagnostics.FileVersionInfo]
+                $result.ProductVersion | Should -Not -BeNullOrEmpty
+                $result.FileVersion | Should -Not -BeNullOrEmpty
+            }
+
+            It 'Should return version information using pipeline input' {
+                $result = $script:notepadPath | Get-FileVersion -ErrorAction Stop
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [System.Diagnostics.FileVersionInfo]
+                $result.ProductVersion | Should -Not -BeNullOrEmpty
+            }
+
+            It 'Should return version information using Get-Item pipeline input' {
+                $result = Get-Item -Path $script:notepadPath | Get-FileVersion -ErrorAction Stop
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [System.Diagnostics.FileVersionInfo]
+                $result.ProductVersion | Should -Not -BeNullOrEmpty
+            }
+        }
+
+        Context 'When getting version information from powershell.exe' {
+            BeforeAll {
+                $script:powershellPath = Join-Path -Path $env:SystemRoot -ChildPath 'System32\WindowsPowerShell\v1.0\powershell.exe'
+            }
+
+            It 'Should return version information for powershell.exe' {
+                $result = Get-FileVersion -Path $script:powershellPath -ErrorAction Stop
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [System.Diagnostics.FileVersionInfo]
+                $result.ProductVersion | Should -Not -BeNullOrEmpty
+                $result.FileVersion | Should -Not -BeNullOrEmpty
+                $result.ProductName | Should -Not -BeNullOrEmpty
+            }
+        }
+
+        Context 'When passing an invalid path' {
+            It 'Should throw an error for non-existent file' {
+                { Get-FileVersion -Path 'C:\NonExistent\File.exe' -ErrorAction Stop } |
+                    Should -Throw
+            }
+        }
+
+        Context 'When passing a directory path' {
+            It 'Should throw the correct error' {
+                { Get-FileVersion -Path $env:SystemRoot -ErrorAction Stop } |
+                    Should -Throw
+            }
+        }
+    }
+
+    Context 'When running on non-Windows platforms' -Skip:($IsWindows -or $PSVersionTable.PSVersion.Major -lt 6) {
+        Context 'When getting version information from a shell executable' -Skip:(-not (Test-Path -Path '/bin/bash')) {
+            BeforeAll {
+                $script:bashPath = '/bin/bash'
+            }
+
+            It 'Should handle Unix executables appropriately' {
+                # Unix executables typically don't have version info like Windows executables
+                # This test verifies the command can be called without error
+                $result = Get-FileVersion -Path $script:bashPath -ErrorAction 'Stop'
+
+                # Result may be null or empty on Unix systems
+                $result | Should -BeOfType [System.Diagnostics.FileVersionInfo]
+            }
+        }
+    }
+}