From 7b0cbc450e5fb769bb5a1c9508b3f945131026d7 Mon Sep 17 00:00:00 2001
From: Dan Hughes <2237515+dan-hughes@users.noreply.github.com>
Date: Mon, 26 May 2025 21:33:11 +0100
Subject: [PATCH 1/4] Add parameter

---
 source/Public/Format-Path.ps1           | 21 ++++++++++++++++++++-
 tests/Unit/Public/Format-Path.Tests.ps1 | 17 +++++++++++++++++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/source/Public/Format-Path.ps1 b/source/Public/Format-Path.ps1
index 3580216..edbc05d 100644
--- a/source/Public/Format-Path.ps1
+++ b/source/Public/Format-Path.ps1
@@ -27,6 +27,11 @@
         When specified, removes any trailing directory separator (backslash) from
         paths, including drive letters.
 
+    .PARAMETER ExpandEnvironmentVariable
+        Replaces the name of each environment variable embedded in the specified string
+        with the string equivalent of the value of the variable.
+        Each environment variable must be quoted with the percent sign character (%).
+
     .EXAMPLE
         Format-Path -Path 'C:/MyFolder/'
 
@@ -65,6 +70,11 @@
 
         Returns '/var/log' on Linux/macOS or '\var\log' on Windows.
         Unix-style absolute paths are normalized to use the system's directory separator.
+
+    .EXAMPLE
+        Format-Path -Path '%WinDir%\SubFolder' -ExpandEnvironmentVariable
+
+        Returns the path with the environment variable expanded, e.g., 'C:\Windows\SubFolder'
 #>
 function Format-Path
 {
@@ -82,7 +92,11 @@ function Format-Path
 
         [Parameter()]
         [System.Management.Automation.SwitchParameter]
-        $NoTrailingDirectorySeparator
+        $NoTrailingDirectorySeparator,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $ExpandEnvironmentVariable
     )
 
     if ($Path -match '^(?:[a-zA-Z]:|\\\\)')
@@ -116,6 +130,11 @@ function Format-Path
         }
     }
 
+    if ($ExpandEnvironmentVariable)
+    {
+        $normalizedPath = [System.Environment]::ExpandEnvironmentVariables($normalizedPath)
+    }
+
     Write-Debug -Message ($script:localizedData.Format_Path_NormalizedPath -f $Path, $normalizedPath)
 
     return $normalizedPath
diff --git a/tests/Unit/Public/Format-Path.Tests.ps1 b/tests/Unit/Public/Format-Path.Tests.ps1
index 66b7f3f..44aef70 100644
--- a/tests/Unit/Public/Format-Path.Tests.ps1
+++ b/tests/Unit/Public/Format-Path.Tests.ps1
@@ -165,4 +165,21 @@ Describe 'Format-Path' {
             }
         }
     }
+
+    Context 'When using ExpandEnvironmentVariable parameter' {
+        It 'Should expand environment variables in the path' {
+            $env:TestPath = 'C:\TestFolder'
+            Format-Path -Path '%TestPath%' -ExpandEnvironmentVariable | Should -Be 'C:\TestFolder'
+        }
+
+        It 'Should handle paths with multiple environment variables' {
+            $env:BasePath = 'C:\Base'
+            $env:SubPath = 'SubFolder'
+            Format-Path -Path '%BasePath%\%SubPath%' -ExpandEnvironmentVariable | Should -Be 'C:\Base\SubFolder'
+        }
+
+        It 'Should not modify paths without environment variables' {
+            Format-Path -Path 'C:\NoEnvVar' -ExpandEnvironmentVariable | Should -Be 'C:\NoEnvVar'
+        }
+    }
 }

From 27240549853e60498d0ae83625457a0d8aa63efc Mon Sep 17 00:00:00 2001
From: Dan Hughes <2237515+dan-hughes@users.noreply.github.com>
Date: Mon, 26 May 2025 21:33:18 +0100
Subject: [PATCH 2/4] Update changelog

---
 CHANGELOG.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 02e731a..fe48a4d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `Format-Path`
+  - Added parameter `ExpandEnvironmentVariable` fixes [#147](https://github.com/dsccommunity/DscResource.Common/issues/147).
+
 ## [0.22.0] - 2025-04-25
 
 ### Removed

From 04fa6ab69ce76f9b213ddb944884d14a8f988229 Mon Sep 17 00:00:00 2001
From: Dan Hughes <2237515+dan-hughes@users.noreply.github.com>
Date: Mon, 26 May 2025 21:42:45 +0100
Subject: [PATCH 3/4] Fix tests

---
 tests/Unit/Public/Format-Path.Tests.ps1 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/Unit/Public/Format-Path.Tests.ps1 b/tests/Unit/Public/Format-Path.Tests.ps1
index 44aef70..aa91964 100644
--- a/tests/Unit/Public/Format-Path.Tests.ps1
+++ b/tests/Unit/Public/Format-Path.Tests.ps1
@@ -172,7 +172,7 @@ Describe 'Format-Path' {
             Format-Path -Path '%TestPath%' -ExpandEnvironmentVariable | Should -Be 'C:\TestFolder'
         }
 
-        It 'Should handle paths with multiple environment variables' {
+        It 'Should handle paths with multiple environment variables' -Skip:($IsLinux -or $IsMacOS) {
             $env:BasePath = 'C:\Base'
             $env:SubPath = 'SubFolder'
             Format-Path -Path '%BasePath%\%SubPath%' -ExpandEnvironmentVariable | Should -Be 'C:\Base\SubFolder'

From 120067289f8c4f876ece26252a999ba95f356fa2 Mon Sep 17 00:00:00 2001
From: Dan Hughes <2237515+dan-hughes@users.noreply.github.com>
Date: Fri, 30 May 2025 10:47:56 +0100
Subject: [PATCH 4/4] Re-order formatting

---
 source/Public/Format-Path.ps1 | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/source/Public/Format-Path.ps1 b/source/Public/Format-Path.ps1
index edbc05d..c5d8c5d 100644
--- a/source/Public/Format-Path.ps1
+++ b/source/Public/Format-Path.ps1
@@ -99,14 +99,22 @@ function Format-Path
         $ExpandEnvironmentVariable
     )
 
-    if ($Path -match '^(?:[a-zA-Z]:|\\\\)')
+    # Use local variable so it always exists.
+    $normalizedPath = $Path
+
+    if ($ExpandEnvironmentVariable)
+    {
+        $normalizedPath = [System.Environment]::ExpandEnvironmentVariables($normalizedPath)
+    }
+
+    if ($normalizedPath -match '^(?:[a-zA-Z]:|\\\\)')
     {
         # Path starts with a Windows drive letter, normalize to backslashes.
-        $normalizedPath = $Path -replace '/', '\'
+        $normalizedPath = $normalizedPath -replace '/', '\'
     }
     else
     {
-        $normalizedPath = $Path -replace '[\\|/]', [System.IO.Path]::DirectorySeparatorChar
+        $normalizedPath = $normalizedPath -replace '[\\|/]', [System.IO.Path]::DirectorySeparatorChar
     }
 
     # Remove trailing backslash if parameter is specified and path is not just a drive root.
@@ -130,11 +138,6 @@ function Format-Path
         }
     }
 
-    if ($ExpandEnvironmentVariable)
-    {
-        $normalizedPath = [System.Environment]::ExpandEnvironmentVariables($normalizedPath)
-    }
-
     Write-Debug -Message ($script:localizedData.Format_Path_NormalizedPath -f $Path, $normalizedPath)
 
     return $normalizedPath