Add note about breaking change

MicrosoftDocs · Mar 20, 2024 · b6008b9 · b6008b9
1 parent 7482d24
commit b6008b9
Show file tree

Hide file tree

Showing 5 changed files with 128 additions and 10 deletions.
diff --git a/reference/5.1/Microsoft.PowerShell.Management/Test-Path.md b/reference/5.1/Microsoft.PowerShell.Management/Test-Path.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Management
-ms.date: 01/19/2024
+ms.date: 03/20/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Test-Path
@@ -218,6 +218,22 @@ At line:1 char:11
     + FullyQualifiedErrorId : ParameterArgumentValidationErrorEmptyStringNotAllowed,Microsoft.PowerShell.Commands.TestPathCommand
 ```
 
+### Example 9: Test a path that may have an invalid drive
+
+When you test a path that includes a drive specification, testing the validity of the path fails if
+the drive doesn't exist. You can prefix the drive with the provider name to work around this
+problem.
+
+```powershell
+Test-Path -IsValid Z:\abc.txt
+Test-Path -IsValid FileSystem::Z:\abc.txt
+```
+
+```Output
+False
+True
+```
+
 ## PARAMETERS
 
 ### -Credential
@@ -296,7 +312,9 @@ Accept wildcard characters: True
 ### -IsValid
 
 Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the
-path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not.
+path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. If the
+path being tested includes a drive specification, the cmdlet returns false when the drive does not
+exist. This is caused because PowerShell doesn't know which drive provider to test.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter

diff --git a/reference/7.2/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.2/Microsoft.PowerShell.Management/Test-Path.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Management
-ms.date: 01/19/2024
+ms.date: 03/20/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Test-Path
@@ -211,6 +211,22 @@ False
 False
 ```
 
+### Example 9: Test a path that may have an invalid drive
+
+When you test a path that includes a drive specification, testing the validity of the path fails if
+the drive doesn't exist. You can prefix the drive with the provider name to work around this
+problem.
+
+```powershell
+Test-Path -IsValid Z:\abc.txt
+Test-Path -IsValid FileSystem::Z:\abc.txt
+```
+
+```Output
+False
+True
+```
+
 ## PARAMETERS
 
 ### -Credential
@@ -289,7 +305,16 @@ Accept wildcard characters: True
 ### -IsValid
 
 Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the
-path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not.
+path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. If the
+path being tested includes a drive specification, the cmdlet returns false when the drive does not
+exist. This is caused because PowerShell doesn't know which drive provider to test.
+
+> [!NOTE]
+> A breaking change in the Path APIs was introduced in .NET 2.1. Those methods no longer check for
+> invalid path characters. This change caused a regression in PowerShell where the **IsValid** check
+> no longer tests for invalid characters. The regression will be addressed in a future release. For
+> more information,
+> see [Breaking changes in .NET Core 2.1](/dotnet/core/compatibility/2.1#path-apis-dont-throw-an-exception-for-invalid-characters).
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter

diff --git a/reference/7.3/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.3/Microsoft.PowerShell.Management/Test-Path.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Management
-ms.date: 01/19/2024
+ms.date: 03/20/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Test-Path
@@ -211,6 +211,22 @@ False
 False
 ```
 
+### Example 9: Test a path that may have an invalid drive
+
+When you test a path that includes a drive specification, testing the validity of the path fails if
+the drive doesn't exist. You can prefix the drive with the provider name to work around this
+problem.
+
+```powershell
+Test-Path -IsValid Z:\abc.txt
+Test-Path -IsValid FileSystem::Z:\abc.txt
+```
+
+```Output
+False
+True
+```
+
 ## PARAMETERS
 
 ### -Credential
@@ -289,7 +305,16 @@ Accept wildcard characters: True
 ### -IsValid
 
 Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the
-path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not.
+path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. If the
+path being tested includes a drive specification, the cmdlet returns false when the drive does not
+exist. This is caused because PowerShell doesn't know which drive provider to test.
+
+> [!NOTE]
+> A breaking change in the Path APIs was introduced in .NET 2.1. Those methods no longer check for
+> invalid path characters. This change caused a regression in PowerShell where the **IsValid** check
+> no longer tests for invalid characters. The regression will be addressed in a future release. For
+> more information,
+> see [Breaking changes in .NET Core 2.1](/dotnet/core/compatibility/2.1#path-apis-dont-throw-an-exception-for-invalid-characters).
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter

diff --git a/reference/7.4/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.4/Microsoft.PowerShell.Management/Test-Path.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Management
-ms.date: 01/19/2024
+ms.date: 03/20/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Test-Path
@@ -211,6 +211,22 @@ False
 False
 ```
 
+### Example 9: Test a path that may have an invalid drive
+
+When you test a path that includes a drive specification, testing the validity of the path fails if
+the drive doesn't exist. You can prefix the drive with the provider name to work around this
+problem.
+
+```powershell
+Test-Path -IsValid Z:\abc.txt
+Test-Path -IsValid FileSystem::Z:\abc.txt
+```
+
+```Output
+False
+True
+```
+
 ## PARAMETERS
 
 ### -Credential
@@ -289,7 +305,16 @@ Accept wildcard characters: True
 ### -IsValid
 
 Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the
-path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not.
+path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. If the
+path being tested includes a drive specification, the cmdlet returns false when the drive does not
+exist. This is caused because PowerShell doesn't know which drive provider to test.
+
+> [!NOTE]
+> A breaking change in the Path APIs was introduced in .NET 2.1. Those methods no longer check for
+> invalid path characters. This change caused a regression in PowerShell where the **IsValid** check
+> no longer tests for invalid characters. The regression will be addressed in a future release. For
+> more information,
+> see [Breaking changes in .NET Core 2.1](/dotnet/core/compatibility/2.1#path-apis-dont-throw-an-exception-for-invalid-characters).
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter

diff --git a/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md b/reference/7.5/Microsoft.PowerShell.Management/Test-Path.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Management
-ms.date: 01/19/2024
+ms.date: 03/20/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/test-path?view=powershell-7.5&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Test-Path
@@ -213,6 +213,22 @@ False
 False
 ```
 
+### Example 9: Test a path that may have an invalid drive
+
+When you test a path that includes a drive specification, testing the validity of the path fails if
+the drive doesn't exist. You can prefix the drive with the provider name to work around this
+problem.
+
+```powershell
+Test-Path -IsValid Z:\abc.txt
+Test-Path -IsValid FileSystem::Z:\abc.txt
+```
+
+```Output
+False
+True
+```
+
 ## PARAMETERS
 
 ### -Credential
@@ -291,7 +307,16 @@ Accept wildcard characters: True
 ### -IsValid
 
 Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the
-path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not.
+path exist. This cmdlet returns `$true` if the path syntax is valid and `$false` if it's not. If the
+path being tested includes a drive specification, the cmdlet returns false when the drive does not
+exist. This is caused because PowerShell doesn't know which drive provider to test.
+
+> [!NOTE]
+> A breaking change in the Path APIs was introduced in .NET 2.1. Those methods no longer check for
+> invalid path characters. This change caused a regression in PowerShell where the **IsValid** check
+> no longer tests for invalid characters. The regression will be addressed in a future release. For
+> more information,
+> see [Breaking changes in .NET Core 2.1](/dotnet/core/compatibility/2.1#path-apis-dont-throw-an-exception-for-invalid-characters).
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter