Merge pull request #11645 from MicrosoftDocs/main

1/7/2025 PM Publish

Author: Taojunshen

reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md

@@ -1,7 +1,7 @@
 ---
 description: Provides information about how PowerShell background jobs run a command or expression in the background without interacting with the current session.
 Locale: en-US
-ms.date: 08/29/2022
+ms.date: 01/07/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_jobs?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Jobs
@@ -242,7 +242,7 @@ results would be incomplete. You can use the `Receive-Job` cmdlet repeatedly to
 get all of the results. Use the **State** property to determine when the job is
 complete.
 
-You can also use the **Wait** parameter of the `Receive-Job` cmdlet. When use
+You can also use the **Wait** parameter of the `Receive-Job` cmdlet. When you
 use this parameter, the cmdlet doesn't return the command prompt until the job
 is completed and all results are available.
 

reference/5.1/Microsoft.PowerShell.Core/About/about_Jobs.md

@@ -1,7 +1,7 @@
 ---
 description: Explains how to sign scripts so that they comply with the PowerShell execution policies.
 Locale: en-US
-ms.date: 10/23/2023
+ms.date: 01/07/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Signing
@@ -33,33 +33,39 @@ PowerShell checks the Authenticode signature of the following type types:
 - `.xaml` XAML script files
 
 For more information about PowerShell execution policies, see
-[about_Execution_Policies][01].
+[about_Execution_Policies][03].
 
-## To permit signed scripts to run
+## Permit the execution of signed scripts
 
 When you start PowerShell on a computer for the first time, the **Restricted**
 execution policy, which is the default, is likely to be in effect.
 
-The **Restricted** policy doesn't permit any scripts to run.
+The **Restricted** policy prevents all scripts from running.
 
 To find the effective execution policy on your computer, type:
 
 ```powershell
 Get-ExecutionPolicy
 ```
 
-To run unsigned scripts that you write on your local computer and signed
-scripts from other users, start PowerShell with the **Run as Administrator**
-option and then use the following command to change the execution policy on the
-computer to **RemoteSigned**:
+The **RemoteSigned** policy allows you to run signed scripts or unsigned
+scripts that you create locally. To configure this policy, start PowerShell
+with the **Run as Administrator** option and then use the following command to
+change the execution policy.
 
 ```powershell
 Set-ExecutionPolicy RemoteSigned
 ```
 
 For more information, see the help topic for the `Set-ExecutionPolicy` cmdlet.
 
-## Running unsigned scripts using the RemoteSigned execution policy
+To run a signed script, the script must have a digital signature from a trusted
+publisher. The code signing certificate must be issued by a certification
+must be issued by a certification authority that is trusted on the computer.
+Self-signed certificates must be installed in the **Trusted Root Certificates**
+store on the computer.
+
+## Run unsigned scripts using the RemoteSigned policy
 
 If your PowerShell execution policy is **RemoteSigned**, PowerShell won't run
 unsigned scripts that are downloaded from the internet, including unsigned
@@ -85,7 +91,7 @@ procedure.
 1. Right-click the script file, and then click **Properties**.
 1. Click **Unblock**.
 
-If a script that was downloaded from the internet is digitally signed, but you
+If a script that you downloaded from the internet is digitally signed, but you
 haven't yet chosen to trust its publisher, PowerShell displays the following
 message:
 
@@ -110,10 +116,8 @@ You can sign the scripts that you write and the scripts that you get from other
 sources. Before you sign any script, examine each command to verify that it's
 safe to run.
 
-For best practices about code signing, see [Code-Signing Best Practices][02].
-
 For more information about how to sign a script file, see
-[Set-AuthenticodeSignature][03].
+[Set-AuthenticodeSignature][06].
 
 The `New-SelfSignedCertificate` cmdlet, introduced in the PKI module in
 PowerShell 3.0, creates a self-signed certificate that's appropriate for
@@ -136,10 +140,11 @@ certificate. Two types of certificates are suitable for signing a script file:
   on your computer. However, a script signed by a self-signed certificate will
   not run on other computers.
 
-Typically, you would use a self-signed certificate only to sign scripts that
-you write for your own use and to sign scripts that you get from other sources
-that you have verified to be safe. It isn't appropriate for scripts that will
-be shared, even within an enterprise.
+Self-signed certificate should only be used to sign scripts for testing
+purposes.
+
+It isn't appropriate for scripts that will be shared, even within an
+enterprise.
 
 If you create a self-signed certificate, be sure to enable strong private key
 protection on your certificate. This prevents malicious programs from signing
@@ -148,7 +153,7 @@ topic.
 
 ## Create a self-signed certificate
 
-To create a self-signed certificate, use the [New-SelfSignedCertificate][04]
+To create a self-signed certificate, use the [New-SelfSignedCertificate][08]
 cmdlet in the PKI module. This module is introduced in PowerShell 3.0. For more
 information, see the help topic for the `New-SelfSignedCertificate` cmdlet.
 
@@ -169,7 +174,7 @@ Certificate Creation tool `MakeCert.exe`. This tool is included in the
 Microsoft .NET SDK (versions 1.1 and later) and in the Microsoft Windows SDK.
 
 For more information about the syntax and the parameter descriptions of the
-`MakeCert.exe` tool, see [Certificate Creation Tool (MakeCert.exe)][05].
+`MakeCert.exe` tool, see [Certificate Creation Tool (MakeCert.exe)][01].
 
 To use the `MakeCert.exe` tool to create a certificate, run the following
 commands in an SDK Command Prompt window.
@@ -201,7 +206,7 @@ a certificate file in the file system directory.
 At the PowerShell prompt, type:
 
 ```powershell
-Get-ChildItem cert:\CurrentUser\my -codesigning
+Get-ChildItem cert:\CurrentUser\my -CodeSigning
 ```
 
 This command uses the PowerShell Certificate provider to view information
@@ -229,10 +234,9 @@ you are using the **AllSigned** execution policy, you must sign the
 `Add-Signature.ps1` script before you run it.
 
 > [!IMPORTANT]
-> The script must be saved using ASCII or UTF8NoBOM encoding. You can sign a
-> script file that uses a different encoding, but the script fails to run or
-> the module containing the script fails to import. The script will also fail
-> if the file contains Unicode (UTF8) characters.
+> Before PowerShell 7.2, the script must be saved using ASCII or UTF8NoBOM
+> encoding. PowerShell 7.2 and higher supports signed scripts for any encoding
+> format.
 
 To use this script, copy the following text into a text file, and name it
 `Add-Signature.ps1`.
@@ -321,19 +325,19 @@ stamp server ensures that users can use your script for many years to come.
 
 ## See also
 
-- [about_Execution_Policies][01]
-- [about_Profiles][06]
-- [Set-AuthenticodeSignature][03]
-- [Get-ExecutionPolicy][07]
-- [Set-ExecutionPolicy][08]
-- [Introduction to Code Signing][09]
-
-[01]: about_Execution_Policies.md
-[02]: /previous-versions/windows/hardware/design/dn653556(v=vs.85)
-[03]: xref:Microsoft.PowerShell.Security.Set-AuthenticodeSignature
-[04]: xref:pki.New-SelfSignedCertificate
-[05]: /previous-versions/dotnet/netframework-2.0/bfsktky3(v=vs.80)
-[06]: about_Profiles.md
-[07]: xref:Microsoft.PowerShell.Security.Get-ExecutionPolicy
-[08]: xref:Microsoft.PowerShell.Security.Set-ExecutionPolicy
-[09]: /previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms537361(v=vs.85)
+- [about_Execution_Policies][03]
+- [about_Profiles][04]
+- [Set-AuthenticodeSignature][06]
+- [Get-ExecutionPolicy][05]
+- [Set-ExecutionPolicy][07]
+- [Introduction to Code Signing][02]
+
+<!-- link references -->
+[01]: /previous-versions/dotnet/netframework-2.0/bfsktky3(v=vs.80)
+[02]: /previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms537361(v=vs.85)
+[03]: about_Execution_Policies.md
+[04]: about_Profiles.md
+[05]: xref:Microsoft.PowerShell.Security.Get-ExecutionPolicy
+[06]: xref:Microsoft.PowerShell.Security.Set-AuthenticodeSignature
+[07]: xref:Microsoft.PowerShell.Security.Set-ExecutionPolicy
+[08]: xref:pki.New-SelfSignedCertificate

reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md

@@ -1,22 +1,23 @@
 ---
 description: Describes how to use the `try`, `catch`, and `finally` blocks to handle terminating errors.
 Locale: en-US
-ms.date: 11/12/2021
+ms.date: 01/07/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_try_catch_finally?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Try_Catch_Finally
 ---
 # about_Try_Catch_Finally
 
 ## Short description
+
 Describes how to use the `try`, `catch`, and `finally` blocks to handle
 terminating errors.
 
 ## Long description
 
 Use `try`, `catch`, and `finally` blocks to respond to or handle terminating
 errors in scripts. The `Trap` statement can also be used to handle terminating
-errors in scripts. For more information, see [about_Trap](about_Trap.md).
+errors in scripts. For more information, see [about_Trap][05].
 
 A terminating error stops a statement from running. If PowerShell does not
 handle a terminating error in some way, PowerShell also stops running the
@@ -71,9 +72,9 @@ Error types appear in brackets. The outermost brackets indicate the element is
 optional.
 
 The `catch` keyword is followed by an optional list of error type
-specifications and a statement list. If a terminating error occurs in the
-`try` block, PowerShell searches for an appropriate `catch` block. If
-one is found, the statements in the `catch` block are executed.
+specifications and a statement list. If a terminating error occurs in the `try`
+block, PowerShell searches for an appropriate `catch` block. If one is found,
+the statements in the `catch` block are executed.
 
 The `catch` block can specify one or more error types. An error type is a
 Microsoft .NET Framework exception or an exception that is derived from a .NET
@@ -117,7 +118,7 @@ block.
 PowerShell does not recognize "NonsenseString" as a cmdlet or other item.
 Running this script returns the following result:
 
-```powershell
+```Output
 An error occurred.
 ```
 
@@ -132,16 +133,13 @@ two `catch` blocks:
 
 ```powershell
 try {
-   $wc = new-object System.Net.WebClient
-   $wc.DownloadFile("http://www.contoso.com/MyDoc.doc","c:\temp\MyDoc.doc")
-}
-catch [System.Net.WebException],[System.IO.IOException] {
+    $wc = New-Object System.Net.WebClient
+    $wc.DownloadFile("http://www.contoso.com/MyDoc.doc","c:\temp\MyDoc.doc")
+} catch [System.Net.WebException],[System.IO.IOException] {
     "Unable to download MyDoc.doc from http://www.contoso.com."
-}
-catch {
+} catch {
     "An error occurred that could not be resolved."
 }
-
 ```
 
 The first `catch` block handles errors of the **System.Net.WebException** and
@@ -155,8 +153,9 @@ from the specified class. The following example contains a `catch` block that
 catches a "Command Not Found" error:
 
 ```powershell
-catch [System.Management.Automation.CommandNotFoundException]
-{"Inherited Exception" }
+catch [System.Management.Automation.CommandNotFoundException] {
+    "Inherited Exception"
+}
 ```
 
 The specified error type, **CommandNotFoundException**, inherits from the
@@ -181,23 +180,23 @@ block for the derived class before the `catch` block for the general class.
 ## Using Traps in a Try Catch
 
 When a terminating error occurs in a `try` block with a `Trap` defined within
-the `try` block, even if there is a matching `catch` block, the `Trap` statement
-takes control.
+the `try` block, even if there is a matching `catch` block, the `Trap`
+statement takes control.
 
 If a `Trap` exists at a higher block than the `try`, and there is no matching
 `catch` block within the current scope, the `Trap` will take control, even if
 any parent scope has a matching `catch` block.
 
 ## Accessing exception information
 
-Within a `catch` block, the current error can be accessed using `$_`, which
-is also known as `$PSItem`. The object is of type **ErrorRecord**.
+Within a `catch` block, the current error can be accessed using `$_`, which is
+also known as `$PSItem`. The object is of type **ErrorRecord**.
 
 ```powershell
 try { NonsenseString }
 catch {
-  Write-Host "An error occurred:"
-  Write-Host $_
+    Write-Host "An error occurred:"
+    Write-Host $_
 }
 ```
 
@@ -210,21 +209,21 @@ script file, or operable program. Check the spelling of the name, or if a path
 was included, verify that the path is correct and try again.
 ```
 
-There are additional properties that can be accessed, such as **ScriptStackTrace**,
-**Exception**, and **ErrorDetails**.  For example, if we change the script to the
-following:
+There are additional properties that can be accessed, such as
+**ScriptStackTrace**, **Exception**, and **ErrorDetails**. For example, if we
+change the script to the following:
 
 ```powershell
 try { NonsenseString }
 catch {
-  Write-Host "An error occurred:"
-  Write-Host $_.ScriptStackTrace
+    Write-Host "An error occurred:"
+    Write-Host $_.ScriptStackTrace
 }
 ```
 
 The result will be similar to:
 
-```
+```Output
 An Error occurred:
 at <ScriptBlock>, <No file>: line 2
 ```
@@ -240,10 +239,37 @@ A `finally` block runs even if you use <kbd>CTRL</kbd>+<kbd>C</kbd> to stop the
 script. A `finally` block also runs if an Exit keyword stops the script from
 within a `catch` block.
 
+In the following example, the `try` block attempts to download a file to the
+`c:\temp` folder. The `catch` blocks handle errors that occur during the
+download. The `finally` block disposes of the `WebClient` object and removes
+the temporary file if it exists.
+
+```powershell
+try {
+    $wc = New-Object System.Net.WebClient
+    $tempFile = "c:\temp\MyDoc.doc"
+    $wc.DownloadFile("http://www.contoso.com/MyDoc.doc",$tempFile)
+} catch [System.Net.WebException],[System.IO.IOException] {
+    "Unable to download MyDoc.doc from http://www.contoso.com."
+} catch {
+    "An error occurred that could not be resolved."
+} finally {
+    $wc.Dispose()
+    if (Test-Path $tempPath) { Remove-item $tempFile }
+}
+```
+
 ## See also
 
-- [about_Break](about_Break.md)
-- [about_Continue](about_Continue.md)
-- [about_Scopes](about_Scopes.md)
-- [about_Throw](about_Throw.md)
-- [about_Trap](about_Trap.md)
+- [about_Break][01]
+- [about_Continue][02]
+- [about_Scopes][03]
+- [about_Throw][04]
+- [about_Trap][05]
+
+<!-- link references -->
+[01]: about_Break.md
+[02]: about_Continue.md
+[03]: about_Scopes.md
+[04]: about_Throw.md
+[05]: about_Trap.md