From 9efe4a15a2687a31627748f5b2ff144b8067d67e Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Mon, 9 May 2022 14:24:48 -0500 Subject: [PATCH 1/2] (GH-8796) Clarify force param This commit clarifies the force parameter in PowerShell 7+, where it is no longer required but remains good practice to ensure backwards compatibility with older versions. --- .../ConvertTo-SecureString.md | 16 ++++++++++------ .../ConvertTo-SecureString.md | 16 ++++++++++------ .../ConvertTo-SecureString.md | 16 ++++++++++------ .../ConvertTo-SecureString.md | 16 ++++++++++------ 4 files changed, 40 insertions(+), 24 deletions(-) diff --git a/reference/7.0/Microsoft.PowerShell.Security/ConvertTo-SecureString.md b/reference/7.0/Microsoft.PowerShell.Security/ConvertTo-SecureString.md index 18a506fb3c65..eae402a94f09 100644 --- a/reference/7.0/Microsoft.PowerShell.Security/ConvertTo-SecureString.md +++ b/reference/7.0/Microsoft.PowerShell.Security/ConvertTo-SecureString.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Security -ms.date: 10/22/2020 +ms.date: 05/09/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.security/convertto-securestring?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertTo-SecureString @@ -119,8 +119,11 @@ The results are saved in the `$Secure2` variable. ### Example 3: Convert a plain text string to a secure string This command converts the plain text string `P@ssW0rD!` into a secure string and stores the result -in the `$Secure_String_Pwd` variable. To use the **AsPlainText** parameter, the **Force** parameter -must also be included in the command. +in the `$Secure_String_Pwd` variable. + +Starting in PowerShell 7, the **Force** parameter is not required when using the **AsPlainText** +parameter. However, including the **Force** parameter ensures the statement is compatible with +earlier versions. ```powershell $Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force @@ -137,7 +140,7 @@ $Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force Specifies a plain text string to convert to a secure string. The secure string cmdlets help protect confidential text. The text is encrypted for privacy and is deleted from computer memory after it is used. If you use this parameter to provide plain text as input, the system cannot protect that input -in this manner. To use this parameter, you must also specify the **Force** parameter. +in this manner. ```yaml Type: System.Management.Automation.SwitchParameter @@ -153,8 +156,9 @@ Accept wildcard characters: False ### -Force -Confirms that you understand the implications of using the **AsPlainText** parameter and still want -to use it. +Before PowerShell 7, this parameter was mandatory when using the **AsPlainText** parameter. It +remains to enable you to use this cmdlet on earlier versions of PowerShell without having to update +your code. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.1/Microsoft.PowerShell.Security/ConvertTo-SecureString.md b/reference/7.1/Microsoft.PowerShell.Security/ConvertTo-SecureString.md index 6bc670e50bfb..22c37c86e687 100644 --- a/reference/7.1/Microsoft.PowerShell.Security/ConvertTo-SecureString.md +++ b/reference/7.1/Microsoft.PowerShell.Security/ConvertTo-SecureString.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Security -ms.date: 10/22/2020 +ms.date: 05/09/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.security/convertto-securestring?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertTo-SecureString @@ -119,8 +119,11 @@ The results are saved in the `$Secure2` variable. ### Example 3: Convert a plain text string to a secure string This command converts the plain text string `P@ssW0rD!` into a secure string and stores the result -in the `$Secure_String_Pwd` variable. To use the **AsPlainText** parameter, the **Force** parameter -must also be included in the command. +in the `$Secure_String_Pwd` variable. + +Starting in PowerShell 7, the **Force** parameter is not required when using the **AsPlainText** +parameter. However, including the **Force** parameter ensures the statement is compatible with +earlier versions. ```powershell $Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force @@ -137,7 +140,7 @@ $Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force Specifies a plain text string to convert to a secure string. The secure string cmdlets help protect confidential text. The text is encrypted for privacy and is deleted from computer memory after it is used. If you use this parameter to provide plain text as input, the system cannot protect that input -in this manner. To use this parameter, you must also specify the **Force** parameter. +in this manner. ```yaml Type: System.Management.Automation.SwitchParameter @@ -153,8 +156,9 @@ Accept wildcard characters: False ### -Force -Confirms that you understand the implications of using the **AsPlainText** parameter and still want -to use it. +Before PowerShell 7, this parameter was mandatory when using the **AsPlainText** parameter. It +remains to enable you to use this cmdlet on earlier versions of PowerShell without having to update +your code. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.2/Microsoft.PowerShell.Security/ConvertTo-SecureString.md b/reference/7.2/Microsoft.PowerShell.Security/ConvertTo-SecureString.md index 3e38c2acd22c..23d8798de267 100644 --- a/reference/7.2/Microsoft.PowerShell.Security/ConvertTo-SecureString.md +++ b/reference/7.2/Microsoft.PowerShell.Security/ConvertTo-SecureString.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Security -ms.date: 10/22/2020 +ms.date: 05/09/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.security/convertto-securestring?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertTo-SecureString @@ -119,8 +119,11 @@ The results are saved in the `$Secure2` variable. ### Example 3: Convert a plain text string to a secure string This command converts the plain text string `P@ssW0rD!` into a secure string and stores the result -in the `$Secure_String_Pwd` variable. To use the **AsPlainText** parameter, the **Force** parameter -must also be included in the command. +in the `$Secure_String_Pwd` variable. + +Starting in PowerShell 7, the **Force** parameter is not required when using the **AsPlainText** +parameter. However, including the **Force** parameter ensures the statement is compatible with +earlier versions. ```powershell $Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force @@ -137,7 +140,7 @@ $Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force Specifies a plain text string to convert to a secure string. The secure string cmdlets help protect confidential text. The text is encrypted for privacy and is deleted from computer memory after it is used. If you use this parameter to provide plain text as input, the system cannot protect that input -in this manner. To use this parameter, you must also specify the **Force** parameter. +in this manner. ```yaml Type: System.Management.Automation.SwitchParameter @@ -153,8 +156,9 @@ Accept wildcard characters: False ### -Force -Confirms that you understand the implications of using the **AsPlainText** parameter and still want -to use it. +Before PowerShell 7, this parameter was mandatory when using the **AsPlainText** parameter. It +remains to enable you to use this cmdlet on earlier versions of PowerShell without having to update +your code. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.3/Microsoft.PowerShell.Security/ConvertTo-SecureString.md b/reference/7.3/Microsoft.PowerShell.Security/ConvertTo-SecureString.md index 77558f7f65ad..0c73d69783ca 100644 --- a/reference/7.3/Microsoft.PowerShell.Security/ConvertTo-SecureString.md +++ b/reference/7.3/Microsoft.PowerShell.Security/ConvertTo-SecureString.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Security -ms.date: 10/22/2020 +ms.date: 05/09/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.security/convertto-securestring?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertTo-SecureString @@ -119,8 +119,11 @@ The results are saved in the `$Secure2` variable. ### Example 3: Convert a plain text string to a secure string This command converts the plain text string `P@ssW0rD!` into a secure string and stores the result -in the `$Secure_String_Pwd` variable. To use the **AsPlainText** parameter, the **Force** parameter -must also be included in the command. +in the `$Secure_String_Pwd` variable. + +Starting in PowerShell 7, the **Force** parameter is not required when using the **AsPlainText** +parameter. However, including the **Force** parameter ensures the statement is compatible with +earlier versions. ```powershell $Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force @@ -137,7 +140,7 @@ $Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force Specifies a plain text string to convert to a secure string. The secure string cmdlets help protect confidential text. The text is encrypted for privacy and is deleted from computer memory after it is used. If you use this parameter to provide plain text as input, the system cannot protect that input -in this manner. To use this parameter, you must also specify the **Force** parameter. +in this manner. ```yaml Type: System.Management.Automation.SwitchParameter @@ -153,8 +156,9 @@ Accept wildcard characters: False ### -Force -Confirms that you understand the implications of using the **AsPlainText** parameter and still want -to use it. +Before PowerShell 7, this parameter was mandatory when using the **AsPlainText** parameter. It +remains to enable you to use this cmdlet on earlier versions of PowerShell without having to update +your code. ```yaml Type: System.Management.Automation.SwitchParameter From f945a651464bc8c9ca817c2c08284da950c819b8 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 10 May 2022 08:36:38 -0500 Subject: [PATCH 2/2] Apply suggestions from code review --- .../Microsoft.PowerShell.Security/ConvertTo-SecureString.md | 6 +++--- .../Microsoft.PowerShell.Security/ConvertTo-SecureString.md | 6 +++--- .../Microsoft.PowerShell.Security/ConvertTo-SecureString.md | 6 +++--- .../Microsoft.PowerShell.Security/ConvertTo-SecureString.md | 6 +++--- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/reference/7.0/Microsoft.PowerShell.Security/ConvertTo-SecureString.md b/reference/7.0/Microsoft.PowerShell.Security/ConvertTo-SecureString.md index eae402a94f09..a9244a7eb973 100644 --- a/reference/7.0/Microsoft.PowerShell.Security/ConvertTo-SecureString.md +++ b/reference/7.0/Microsoft.PowerShell.Security/ConvertTo-SecureString.md @@ -156,9 +156,9 @@ Accept wildcard characters: False ### -Force -Before PowerShell 7, this parameter was mandatory when using the **AsPlainText** parameter. It -remains to enable you to use this cmdlet on earlier versions of PowerShell without having to update -your code. +Beginning in PowerShell 7, The **Force** parameter is no longer required when using the +**AsPlainText** parameter. While the parameter is not used, it was not removed to provide +compatibility with earlier versions of PowerShell. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.1/Microsoft.PowerShell.Security/ConvertTo-SecureString.md b/reference/7.1/Microsoft.PowerShell.Security/ConvertTo-SecureString.md index 22c37c86e687..b0ea61eeea5b 100644 --- a/reference/7.1/Microsoft.PowerShell.Security/ConvertTo-SecureString.md +++ b/reference/7.1/Microsoft.PowerShell.Security/ConvertTo-SecureString.md @@ -156,9 +156,9 @@ Accept wildcard characters: False ### -Force -Before PowerShell 7, this parameter was mandatory when using the **AsPlainText** parameter. It -remains to enable you to use this cmdlet on earlier versions of PowerShell without having to update -your code. +Beginning in PowerShell 7, The **Force** parameter is no longer required when using the +**AsPlainText** parameter. While the parameter is not used, it was not removed to provide +compatibility with earlier versions of PowerShell. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.2/Microsoft.PowerShell.Security/ConvertTo-SecureString.md b/reference/7.2/Microsoft.PowerShell.Security/ConvertTo-SecureString.md index 23d8798de267..b48f19566b45 100644 --- a/reference/7.2/Microsoft.PowerShell.Security/ConvertTo-SecureString.md +++ b/reference/7.2/Microsoft.PowerShell.Security/ConvertTo-SecureString.md @@ -156,9 +156,9 @@ Accept wildcard characters: False ### -Force -Before PowerShell 7, this parameter was mandatory when using the **AsPlainText** parameter. It -remains to enable you to use this cmdlet on earlier versions of PowerShell without having to update -your code. +Beginning in PowerShell 7, The **Force** parameter is no longer required when using the +**AsPlainText** parameter. While the parameter is not used, it was not removed to provide +compatibility with earlier versions of PowerShell. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.3/Microsoft.PowerShell.Security/ConvertTo-SecureString.md b/reference/7.3/Microsoft.PowerShell.Security/ConvertTo-SecureString.md index 0c73d69783ca..d3ba30178000 100644 --- a/reference/7.3/Microsoft.PowerShell.Security/ConvertTo-SecureString.md +++ b/reference/7.3/Microsoft.PowerShell.Security/ConvertTo-SecureString.md @@ -156,9 +156,9 @@ Accept wildcard characters: False ### -Force -Before PowerShell 7, this parameter was mandatory when using the **AsPlainText** parameter. It -remains to enable you to use this cmdlet on earlier versions of PowerShell without having to update -your code. +Beginning in PowerShell 7, The **Force** parameter is no longer required when using the +**AsPlainText** parameter. While the parameter is not used, it was not removed to provide +compatibility with earlier versions of PowerShell. ```yaml Type: System.Management.Automation.SwitchParameter