diff --git a/reference/docs-conceptual/developer/cmdlet/confirmation-messages.md b/reference/docs-conceptual/developer/cmdlet/confirmation-messages.md index a38b232d94ed..2bad5ded28eb 100644 --- a/reference/docs-conceptual/developer/cmdlet/confirmation-messages.md +++ b/reference/docs-conceptual/developer/cmdlet/confirmation-messages.md @@ -6,22 +6,20 @@ title: Confirmation Messages # Confirmation Messages Here are different confirmation messages that can be displayed depending on the variants of the -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -and -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) -methods that are called. +[System.Management.Automation.Cmdlet.ShouldProcess][04] and +[System.Management.Automation.Cmdlet.ShouldContinue][03] methods that are called. > [!IMPORTANT] > For sample code that shows how to request confirmations, see -> [How to Request Confirmations](./how-to-request-confirmations.md). +> [Requesting Confirmation from Cmdlets][01]. ## Specifying the Resource You can specify the resource that is about to be changed by calling the -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -method. In this case, you supply the resource by using the `target` parameter of the method, and the -operation is added by Windows PowerShell. In the following message, the text "MyResource" is the -resource acted on and the operation is the name of the command that makes the call. +[System.Management.Automation.Cmdlet.ShouldProcess][04] method. In this case, you supply the +resource by using the `target` parameter of the method, and the operation is added by Windows +PowerShell. In the following message, the text "MyResource" is the resource acted on and the +operation is the name of the command that makes the call. ```Output Confirm @@ -31,9 +29,8 @@ Performing operation "Test-RequestConfirmationTemplate1" on Target "MyResource". ``` If the user selects **Yes** or **Yes to All** to the confirmation request (as shown in the following -example), a call to the -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) -method is made, which causes a second confirmation message to be displayed. +example), a call to the [System.Management.Automation.Cmdlet.ShouldContinue][03] method is made, +which causes a second confirmation message to be displayed. ```Output Confirm @@ -49,11 +46,10 @@ Continue with this operation? ## Specifying the Operation and Resource You can specify the resource that is about to be changed and the operation that the command is about -to perform by calling the -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -method. In this case, you supply the resource by using the `target` parameter and the operation by -using the `target` parameter. In the following message, the text "MyResource" is the resource acted -on and "MyAction" is the operation to be performed. +to perform by calling the [System.Management.Automation.Cmdlet.ShouldProcess][04] method. In this +case, you supply the resource by using the `target` parameter and the operation by using the +`target` parameter. In the following message, the text "MyResource" is the resource acted on and +"MyAction" is the operation to be performed. ```Output Confirm @@ -63,8 +59,8 @@ Performing operation "MyAction" on Target "MyResource". ``` If the user selects **Yes** or **Yes to All** to the previous message, a call to the -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) -method is made, which causes a second confirmation message to be displayed. +[System.Management.Automation.Cmdlet.ShouldContinue][03] method is made, which causes a second +confirmation message to be displayed. ```Output Confirm @@ -79,4 +75,10 @@ Continue with this operation? ## See Also -[Writing a Windows PowerShell Cmdlet](./writing-a-windows-powershell-cmdlet.md) +[Writing a Windows PowerShell Cmdlet][02] + + +[01]: ./requesting-confirmation-from-cmdlets.md +[02]: ./writing-a-windows-powershell-cmdlet.md +[03]: xref:System.Management.Automation.Cmdlet.ShouldContinue%2A +[04]: xref:System.Management.Automation.Cmdlet.ShouldProcess%2A diff --git a/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-that-modifies-the-system.md b/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-that-modifies-the-system.md index ac92aa5c3368..e6acdf5a7324 100644 --- a/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-that-modifies-the-system.md +++ b/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-that-modifies-the-system.md @@ -12,17 +12,17 @@ not to make the change. To support confirmation a cmdlet must do two things. - Declare that the cmdlet supports confirmation when you specify the - [System.Management.Automation.CmdletAttribute](/dotnet/api/System.Management.Automation.CmdletAttribute) + [System.Management.Automation.CmdletAttribute][15] attribute by setting the SupportsShouldProcess keyword to `true`. - Call - [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) + [System.Management.Automation.Cmdlet.ShouldProcess][13] during the execution of the cmdlet (as shown in the following example). By supporting confirmation, a cmdlet exposes the `Confirm` and `WhatIf` parameters that are provided by Windows PowerShell, and also meets the development guidelines for cmdlets (For more information about cmdlet development guidelines, see -[Cmdlet Development Guidelines](./cmdlet-development-guidelines.md).). +[Cmdlet Development Guidelines][04].). ## Changing the System @@ -33,8 +33,8 @@ In contrast, operations that read data or establish transient connections do not and generally do not require confirmation. Confirmation is also not needed for actions whose effect is limited to inside the Windows PowerShell runtime, such as `Set-Variable`. Cmdlets that might or might not make a persistent change should declare `SupportsShouldProcess` and call -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -only if they are about to make a persistent change. +[System.Management.Automation.Cmdlet.ShouldProcess][13] only if they are about to make a persistent +change. > [!NOTE] > ShouldProcess confirmation applies only to cmdlets. If a command or script modifies the running @@ -44,19 +44,16 @@ only if they are about to make a persistent change. ## The StopProc Cmdlet This topic describes a Stop-Proc cmdlet that attempts to stop processes that are retrieved using the -Get-Proc cmdlet (described in -[Creating Your First Cmdlet](./creating-a-cmdlet-without-parameters.md)). +Get-Proc cmdlet (described in [Creating Your First Cmdlet][06]). ## Defining the Cmdlet The first step in cmdlet creation is always naming the cmdlet and declaring the .NET class that implements the cmdlet. Because you are writing a cmdlet to change the system, it should be named accordingly. This cmdlet stops system processes, so the verb name chosen here is "Stop", defined by -the -[System.Management.Automation.VerbsLifecycle](/dotnet/api/System.Management.Automation.VerbsLifecycle) -class, with the noun "Proc" to indicate that the cmdlet stops processes. For more information about -approved cmdlet verbs, see -[Cmdlet Verb Names](./approved-verbs-for-windows-powershell-commands.md). +the [System.Management.Automation.VerbsLifecycle][17] class, with the noun "Proc" to indicate that +the cmdlet stops processes. For more information about approved cmdlet verbs, see [Cmdlet Verb +Names][03]. The following is the class definition for this Stop-Proc cmdlet. @@ -66,39 +63,32 @@ The following is the class definition for this Stop-Proc cmdlet. public class StopProcCommand : Cmdlet ``` -Be aware that in the -[System.Management.Automation.CmdletAttribute](/dotnet/api/System.Management.Automation.CmdletAttribute) -declaration, the `SupportsShouldProcess` attribute keyword is set to `true` to enable the cmdlet to -make calls to -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -and -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue). -Without this keyword set, the `Confirm` and `WhatIf` parameters will not be available to the user. +Be aware that in the [System.Management.Automation.CmdletAttribute][15] declaration, the +`SupportsShouldProcess` attribute keyword is set to `true` to enable the cmdlet to make calls to +[System.Management.Automation.Cmdlet.ShouldProcess][13] and +[System.Management.Automation.Cmdlet.ShouldContinue][12]. Without this keyword set, the `Confirm` +and `WhatIf` parameters will not be available to the user. ### Extremely Destructive Actions Some operations are extremely destructive, such as reformatting an active hard disk partition. In these cases, the cmdlet should set `ConfirmImpact` = `ConfirmImpact.High` when declaring the -[System.Management.Automation.CmdletAttribute](/dotnet/api/System.Management.Automation.CmdletAttribute) -attribute. This setting forces the cmdlet to request user confirmation even when the user has not -specified the `Confirm` parameter. However, cmdlet developers should avoid overusing `ConfirmImpact` -for operations that are just potentially destructive, such as deleting a user account. Remember that -if `ConfirmImpact` is set to -[System.Management.Automation.ConfirmImpact](/dotnet/api/System.Management.Automation.ConfirmImpact) -**High**. +[System.Management.Automation.CmdletAttribute][15] attribute. This setting forces the cmdlet to +request user confirmation even when the user has not specified the `Confirm` parameter. However, +cmdlet developers should avoid overusing `ConfirmImpact` for operations that are just potentially +destructive, such as deleting a user account. Remember that if `ConfirmImpact` is set to +[System.Management.Automation.ConfirmImpact][16] **High**. Similarly, some operations are unlikely to be destructive, although they do in theory modify the running state of a system outside Windows PowerShell. Such cmdlets can set `ConfirmImpact` to -[System.Management.Automation.ConfirmImpact.Low](/dotnet/api/system.management.automation.confirmimpact). -This will bypass confirmation requests where the user has asked to confirm only medium-impact and -high-impact operations. +[System.Management.Automation.ConfirmImpact.Low][16]. This will bypass confirmation requests where +the user has asked to confirm only medium-impact and high-impact operations. ## Defining Parameters for System Modification This section describes how to define the cmdlet parameters, including those that are needed to -support system modification. See -[Adding Parameters that Process CommandLine Input](./adding-parameters-that-process-command-line-input.md) -if you need general information about defining parameters. +support system modification. See [Adding Parameters that Process CommandLine Input][03] if you need +general information about defining parameters. The Stop-Proc cmdlet defines three parameters: `Name`, `Force`, and `PassThru`. @@ -107,13 +97,11 @@ the `Name` parameter in this sample is mandatory, as the cmdlet will fail if it named process to stop. The `Force` parameter allows the user to override calls to -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue). -In fact, any cmdlet that calls -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) -should have a `Force` parameter so that when `Force` is specified, the cmdlet skips the call to -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) -and proceeds with the operation. Be aware that this does not affect calls to -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess). +[System.Management.Automation.Cmdlet.ShouldContinue][12]. In fact, any cmdlet that calls +[System.Management.Automation.Cmdlet.ShouldContinue][12] should have a `Force` parameter so that +when `Force` is specified, the cmdlet skips the call to +[System.Management.Automation.Cmdlet.ShouldContinue][12] and proceeds with the operation. Be aware +that this does not affect calls to [System.Management.Automation.Cmdlet.ShouldProcess][13]. The `PassThru` parameter allows the user to indicate whether the cmdlet passes an output object through the pipeline, in this case, after a process is stopped. Be aware that this parameter is tied @@ -165,10 +153,10 @@ private bool passThru; ## Overriding an Input Processing Method The cmdlet must override an input processing method. The following code illustrates the -[System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord) -override used in the sample Stop-Proc cmdlet. For each requested process name, this method ensures -that the process is not a special process, tries to stop the process, and then sends an output -object if the `PassThru` parameter is specified. +[System.Management.Automation.Cmdlet.ProcessRecord][11] override used in the sample Stop-Proc +cmdlet. For each requested process name, this method ensures that the process is not a special +process, tries to stop the process, and then sends an output object if the `PassThru` parameter is +specified. ```csharp protected override void ProcessRecord() @@ -273,27 +261,23 @@ protected override void ProcessRecord() ## Calling the ShouldProcess Method The input processing method of your cmdlet should call the -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -method to confirm execution of an operation before a change (for example, deleting files) is made to -the running state of the system. This allows the Windows PowerShell runtime to supply the correct -"WhatIf" and "Confirm" behavior within the shell. +[System.Management.Automation.Cmdlet.ShouldProcess][13] method to confirm execution of an operation +before a change (for example, deleting files) is made to the running state of the system. This +allows the Windows PowerShell runtime to supply the correct "WhatIf" and "Confirm" behavior within +the shell. > [!NOTE] > If a cmdlet states that it supports should process and fails to make the -> [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -> call, the user might modify the system unexpectedly. +> [System.Management.Automation.Cmdlet.ShouldProcess][13] call, the user might modify the system +> unexpectedly. -The call to -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -sends the name of the resource to be changed to the user, with the Windows PowerShell runtime taking -into account any command-line settings or preference variables in determining what should be -displayed to the user. +The call to [System.Management.Automation.Cmdlet.ShouldProcess][13] sends the name of the resource +to be changed to the user, with the Windows PowerShell runtime taking into account any command-line +settings or preference variables in determining what should be displayed to the user. -The following example shows the call to -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -from the override of the -[System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord) -method in the sample Stop-Proc cmdlet. +The following example shows the call to [System.Management.Automation.Cmdlet.ShouldProcess][13] from +the override of the [System.Management.Automation.Cmdlet.ProcessRecord][11] method in the sample +Stop-Proc cmdlet. ```csharp if (!ShouldProcess(string.Format("{0} ({1})", processName, @@ -305,21 +289,17 @@ if (!ShouldProcess(string.Format("{0} ({1})", processName, ## Calling the ShouldContinue Method -The call to the -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) -method sends a secondary message to the user. This call is made after the call to -[System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) -returns `true` and if the `Force` parameter was not set to `true`. The user can then provide -feedback to say whether the operation should be continued. Your cmdlet calls -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) -as an additional check for potentially dangerous system modifications or when you want to provide +The call to the [System.Management.Automation.Cmdlet.ShouldContinue][12] method sends a secondary +message to the user. This call is made after the call to +[System.Management.Automation.Cmdlet.ShouldProcess][13] returns `true` and if the `Force` parameter +was not set to `true`. The user can then provide feedback to say whether the operation should be +continued. Your cmdlet calls [System.Management.Automation.Cmdlet.ShouldContinue][12] as an +additional check for potentially dangerous system modifications or when you want to provide yes-to-all and no-to-all options to the user. -The following example shows the call to -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) -from the override of the -[System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord) -method in the sample Stop-Proc cmdlet. +The following example shows the call to [System.Management.Automation.Cmdlet.ShouldContinue][12] +from the override of the [System.Management.Automation.Cmdlet.ProcessRecord][11] method in the +sample Stop-Proc cmdlet. ```csharp if (criticalProcess &&!force) @@ -346,37 +326,33 @@ if (criticalProcess &&!force) The input processing method of a cmdlet that makes system modifications must provide a way of stopping the processing of input. In the case of this Stop-Proc cmdlet, a call is made from the -[System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord) -method to the [System.Diagnostics.Process.Kill*](/dotnet/api/System.Diagnostics.Process.Kill) -method. Because the `PassThru` parameter is set to `true`, -[System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord) -also calls -[System.Management.Automation.Cmdlet.WriteObject](/dotnet/api/System.Management.Automation.Cmdlet.WriteObject) -to send the process object to the pipeline. +[System.Management.Automation.Cmdlet.ProcessRecord][11] method to the +[System.Diagnostics.Process.Kill*][10] method. Because the `PassThru` parameter is set to `true`, +[System.Management.Automation.Cmdlet.ProcessRecord][11] also calls +[System.Management.Automation.Cmdlet.WriteObject][14] to send the process object to the pipeline. ## Code Sample -For the complete C# sample code, see [StopProcessSample01 Sample](./stopprocesssample01-sample.md). +For the complete C# sample code, see [StopProcessSample01 Sample][07]. ## Defining Object Types and Formatting Windows PowerShell passes information between cmdlets using .NET objects. Consequently, a cmdlet may need to define its own type, or the cmdlet may need to extend an existing type provided by another cmdlet. For more information about defining new types or extending existing types, see -[Extending Object Types and Formatting](/previous-versions//ms714665(v=vs.85)). +[Extending Object Types and Formatting][09]. ## Building the Cmdlet After implementing a cmdlet, it must be registered with Windows PowerShell through a Windows PowerShell snap-in. For more information about registering cmdlets, see -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions//ms714644(v=vs.85)). +[How to Register Cmdlets, Providers, and Host Applications][08]. ## Testing the Cmdlet When your cmdlet has been registered with Windows PowerShell, you can test it by running it on the command line. Here are several tests that test the Stop-Proc cmdlet. For more information about -using cmdlets from the command line, see the -[Getting Started with Windows PowerShell](/powershell/scripting/getting-started/getting-started-with-windows-powershell). +using cmdlets from the command line, see the [Running commands in the shell][01]. - Start Windows PowerShell and use the Stop-Proc cmdlet to stop processing as shown below. Because the cmdlet specifies the `Name` parameter as mandatory, the cmdlet queries for the parameter. @@ -446,12 +422,27 @@ using cmdlets from the command line, see the ## See Also -[Adding Parameters that Process Command-Line Input](./adding-parameters-that-process-command-line-input.md) - -[Extending Object Types and Formatting](/previous-versions//ms714665(v=vs.85)) - -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions//ms714644(v=vs.85)) - -[Windows PowerShell SDK](../windows-powershell-reference.md) - -[Cmdlet Samples](./cmdlet-samples.md) +- [Adding Parameters that Process Command-Line Input][03] +- [Extending Object Types and Formatting][09] +- [How to Register Cmdlets, Providers, and Host Applications][08] +- [Windows PowerShell SDK][02] +- [Cmdlet Samples][05] + + +[01]: ../../learn/shell/running-commands.md +[02]: ../windows-powershell-reference.md +[03]: ./adding-parameters-that-process-command-line-input.md +[04]: ./cmdlet-development-guidelines.md +[05]: ./cmdlet-samples.md +[06]: ./creating-a-cmdlet-without-parameters.md +[07]: ./stopprocesssample01-sample.md +[08]: /previous-versions/ms714644(v=vs.85) +[09]: /previous-versions/ms714665(v=vs.85) +[10]: xref:System.Diagnostics.Process.Kill%2A +[11]: xref:System.Management.Automation.Cmdlet.ProcessRecord%2A +[12]: xref:System.Management.Automation.Cmdlet.ShouldContinue%2A +[13]: xref:System.Management.Automation.Cmdlet.ShouldProcess%2A +[14]: xref:System.Management.Automation.Cmdlet.WriteObject%2A +[15]: xref:System.Management.Automation.CmdletAttribute +[16]: xref:System.Management.Automation.ConfirmImpact +[17]: xref:System.Management.Automation.VerbsLifecycle diff --git a/reference/docs-conceptual/developer/cmdlet/examples-of-cmdlet-code.md b/reference/docs-conceptual/developer/cmdlet/examples-of-cmdlet-code.md index 4c94ae7ea373..23b46a557f31 100644 --- a/reference/docs-conceptual/developer/cmdlet/examples-of-cmdlet-code.md +++ b/reference/docs-conceptual/developer/cmdlet/examples-of-cmdlet-code.md @@ -8,43 +8,54 @@ title: Examples of Cmdlet Code This section contains examples of cmdlet code that you can use to start writing your own cmdlets. > [!IMPORTANT] -> If you want step-by-step instructions for writing cmdlets, see [Tutorials for Writing Cmdlets](./tutorials-for-writing-cmdlets.md). +> If you want step-by-step instructions for writing cmdlets, see [Tutorials for Writing Cmdlets][12]. ## In This Section -[How to Write a Simple Cmdlet](./how-to-write-a-simple-cmdlet.md) -This example shows the basic structure of cmdlet code. - -[How to Declare Cmdlet Parameters](./how-to-declare-cmdlet-parameters.md) -This example shows how to declare the different types of parameters. - -[How to Declare Parameter Sets](./how-to-declare-parameter-sets.md) -This example shows how to declare sets of parameters that can change the action a cmdlet performs. - -[How to Validate Parameter Input](./how-to-validate-parameter-input.md) -These examples show how to validate parameter input. - -[How to Declare Dynamic Parameters](./how-to-declare-dynamic-parameters.md) -This example shows how to declare a parameter that is added at runtime. - -[How to Invoke Scripts Within a Cmdlet](./how-to-invoke-scripts-within-a-cmdlet.md) -This example shows how to invoke a script that is supplied to a cmdlet. - -[How To Override Input Processing Methods](./how-to-override-input-processing-methods.md) -These examples show the basic structure used to override the BeginProcessing, ProcessRecord, and EndProcessing methods. - -[How to Support ShouldProcess Calls](./how-to-request-confirmations.md) -This example shows how the [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) and [System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) methods should be called from within a cmdlet. - -[How to Support Transactions](./how-to-support-transactions.md) -This example shows how to indicate that the cmdlet supports transactions and how to implement the action that is taken when the cmdlet is used within a transaction. - -[How to Support Jobs](./how-to-support-jobs.md) -This example shows how to support jobs when you write cmdlets. - -[How to Invoke a Cmdlet From Within a Cmdlet](./how-to-invoke-a-cmdlet-from-within-a-cmdlet.md) -This example shows how to invoke a cmdlet from within another cmdlet, which allows you to add the functionality of the invoked cmdlet to the cmdlet you are developing. +- [How to Write a Simple Cmdlet][11] - This example shows the basic structure of cmdlet code. +- [How to Declare Cmdlet Parameters][01] - This example shows how to declare the different types of + parameters. +- [How to Declare Parameter Sets][03] - This example shows how to declare sets of parameters that + can change the action a cmdlet performs. +- [How to Validate Parameter Input][10] - These examples show how to validate parameter input. +- [How to Declare Dynamic Parameters][02] - This example shows how to declare a parameter that is + added at runtime. +- [How to Invoke Scripts Within a Cmdlet][05] - This example shows how to invoke a script that is + supplied to a cmdlet. +- [How To Override Input Processing Methods][06] - These examples show the basic structure used to + override the BeginProcessing, ProcessRecord, and EndProcessing methods. +- [How to Support ShouldProcess Calls][07] - This example shows how the + [System.Management.Automation.Cmdlet.ShouldProcess][15] and + [System.Management.Automation.Cmdlet.ShouldContinue][14] methods should be called from within a + cmdlet. +- [How to Support Transactions][09] - This example shows how to indicate that the cmdlet supports + transactions and how to implement the action that is taken when the cmdlet is used within a + transaction. +- [How to Support Transactions][09] - This example shows how to indicate that the cmdlet supports + transactions and how to implement the action that is taken when the cmdlet is used within a + transaction. +- [How to Support Jobs][08] - This example shows how to support jobs when you write cmdlets. +- [How to Invoke a Cmdlet From Within a Cmdlet][04] - This example shows how to invoke a cmdlet from + within another cmdlet, which allows you to add the functionality of the invoked cmdlet to the + cmdlet you are developing. ## See Also -[Writing a Windows PowerShell Cmdlet](./writing-a-windows-powershell-cmdlet.md) +[Writing a Windows PowerShell Cmdlet][13] + + +[01]: ./how-to-declare-cmdlet-parameters.md +[02]: ./how-to-declare-dynamic-parameters.md +[03]: ./how-to-declare-parameter-sets.md +[04]: ./how-to-invoke-a-cmdlet-from-within-a-cmdlet.md +[05]: ./how-to-invoke-scripts-within-a-cmdlet.md +[06]: ./how-to-override-input-processing-methods.md +[07]: ./requesting-confirmation-from-cmdlets.md +[08]: ./how-to-support-jobs.md +[09]: ./how-to-support-transactions.md +[10]: ./how-to-validate-parameter-input.md +[11]: ./how-to-write-a-simple-cmdlet.md +[12]: ./tutorials-for-writing-cmdlets.md +[13]: ./writing-a-windows-powershell-cmdlet.md +[14]: /dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue +[15]: /dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess diff --git a/reference/docs-conceptual/developer/cmdlet/requesting-confirmation-from-cmdlets.md b/reference/docs-conceptual/developer/cmdlet/requesting-confirmation-from-cmdlets.md index 31bce374b525..7b18229ba4f9 100644 --- a/reference/docs-conceptual/developer/cmdlet/requesting-confirmation-from-cmdlets.md +++ b/reference/docs-conceptual/developer/cmdlet/requesting-confirmation-from-cmdlets.md @@ -5,13 +5,25 @@ title: Requesting Confirmation from Cmdlets --- # Requesting Confirmation from Cmdlets -Cmdlets should request confirmation when they are about to make a change to the system that is outside of the Windows PowerShell environment. For example, if a cmdlet is about to add a user account or stop a process, the cmdlet should require confirmation from the user before it proceeds. In contrast, if a cmdlet is about to change a Windows PowerShell variable, the cmdlet does not need to require confirmation. +Cmdlets should request confirmation when they make a change to the system that's outside of the +Windows PowerShell environment. For example, if a cmdlet is about to add a user account or stop a +process, the cmdlet should require confirmation from the user before it proceeds. In contrast, if a +cmdlet is about to change a Windows PowerShell variable, the cmdlet doesn't need to require +confirmation. -In order to make a confirmation request, the cmdlet must indicate that it supports confirmation requests, and it must call the [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) and [System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) (optional) methods to display a confirmation request message. +In order to make a confirmation request, the cmdlet must indicate that it supports confirmation +requests, and it must call the [System.Management.Automation.Cmdlet.ShouldProcess][03] and +[System.Management.Automation.Cmdlet.ShouldContinue][02] (optional) methods to display a +confirmation request message. ## Supporting Confirmation Requests -To support confirmation requests, the cmdlet must set the `SupportsShouldProcess` parameter of the Cmdlet attribute to `true`. This enables the `Confirm` and `WhatIf` cmdlet parameters that are provided by Windows PowerShell. The `Confirm` parameter allows the user to control whether the confirmation request is displayed. The `WhatIf` parameter allows the user to determine whether the cmdlet should display a message or perform its action. Do not manually add the `Confirm` and `WhatIf` parameters to a cmdlet. +To support confirmation requests, the cmdlet must set the `SupportsShouldProcess` parameter of the +Cmdlet attribute to `true`. This enables the `Confirm` and `WhatIf` cmdlet parameters that are +provided by Windows PowerShell. The `Confirm` parameter allows the user to control whether the +confirmation request is displayed. The `WhatIf` parameter allows the user to determine whether the +cmdlet should display a message or perform its action. Don't manually add the `Confirm` and +`WhatIf` parameters to a cmdlet. The following example shows a Cmdlet attribute declaration that supports confirmation requests. @@ -22,17 +34,30 @@ The following example shows a Cmdlet attribute declaration that supports confirm ## Calling the Confirmation request methods -In the cmdlet code, call the [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) method before the operation that changes the system is performed. Design the cmdlet so that if the call returns a value of `false`, the operation is not performed, and the cmdlet processes the next operation. +In the cmdlet code, call the [System.Management.Automation.Cmdlet.ShouldProcess][03] method before +the operation that changes the system is performed. Design the cmdlet so that if the call returns a +value of `false`, the operation isn't performed, and the cmdlet processes the next operation. ## Calling the ShouldContinue Method -Most cmdlets request confirmation using only the [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) method. However, some cases might require additional confirmation. For these cases, supplement the [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) call with a call to the [System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) method. This allows the cmdlet or provider to more finely control the scope of the **Yes to all** response to the confirmation prompt. +Most cmdlets request confirmation using only the +[System.Management.Automation.Cmdlet.ShouldProcess][03] method. However, some cases might require +additional confirmation. For these cases, supplement the +[System.Management.Automation.Cmdlet.ShouldProcess][03] call with a call to the +[System.Management.Automation.Cmdlet.ShouldContinue][02] method. This allows the cmdlet or provider +to more finely control the scope of the **Yes to all** response to the confirmation prompt. -If a cmdlet calls the [System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) method, the cmdlet must also provide a `Force` switch parameter. If the user specifies `Force` when the user invokes the cmdlet, the cmdlet should still call [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess), but it should bypass the call to [System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue). +If a cmdlet calls the [System.Management.Automation.Cmdlet.ShouldContinue][02] method, the cmdlet +must also provide a `Force` switch parameter. If the user specifies `Force` when the user invokes +the cmdlet, the cmdlet should still call [System.Management.Automation.Cmdlet.ShouldProcess][03], +but it should bypass the call to [System.Management.Automation.Cmdlet.ShouldContinue][02]. -[System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue) will throw an exception when it is called from a non-interactive environment where the user cannot be prompted. Adding a `Force` parameter ensures that the command can still be performed when it is invoked in a non-interactive environment. +[System.Management.Automation.Cmdlet.ShouldContinue][02] will throw an exception when it's called +from a non-interactive environment where the user can't be prompted. Adding a `Force` parameter +ensures that the command can still be performed when it's invoked in a non-interactive environment. -The following example shows how to call [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) and [System.Management.Automation.Cmdlet.ShouldContinue](/dotnet/api/System.Management.Automation.Cmdlet.ShouldContinue). +The following example shows how to call [System.Management.Automation.Cmdlet.ShouldProcess][03] and +[System.Management.Automation.Cmdlet.ShouldContinue][02]. ```csharp if (ShouldProcess (...) ) @@ -44,34 +69,60 @@ if (ShouldProcess (...) ) } ``` -The behavior of a [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) call can vary depending on the environment in which the cmdlet is invoked. Using the previous guidelines will help ensure that the cmdlet behaves consistently with other cmdlets, regardless of the host environment. - -For an example of calling the [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) method, see [How to Request Confirmations](./how-to-request-confirmations.md). +The behavior of a [System.Management.Automation.Cmdlet.ShouldProcess][03] call can vary depending on +the environment in which the cmdlet is invoked. Using the previous guidelines will help ensure that +the cmdlet behaves consistently with other cmdlets, regardless of the host environment. ## Specify the Impact Level -When you create the cmdlet, specify the impact level (the severity) of the change. To do this, set the value of the `ConfirmImpact` parameter of the Cmdlet attribute to High, Medium, or Low. You can specify a value for `ConfirmImpact` only when you also specify the `SupportsShouldProcess` parameter for the cmdlet. +When you create the cmdlet, specify the impact level (the severity) of the change. To do this, set +the value of the `ConfirmImpact` parameter of the Cmdlet attribute to High, Medium, or Low. You can +specify a value for `ConfirmImpact` only when you also specify the `SupportsShouldProcess` parameter +for the cmdlet. -For most cmdlets, you do not have to explicitly specify `ConfirmImpact`. Instead, use the default setting of the parameter, which is Medium. If you set `ConfirmImpact` to High, the operation will be confirmed by default. Reserve this setting for highly disruptive actions, such as reformatting a hard-disk volume. +For most cmdlets, you don't have to explicitly specify `ConfirmImpact`. Instead, use the default +setting of the parameter, which is Medium. If you set `ConfirmImpact` to High, the operation will be +confirmed by default. Reserve this setting for highly disruptive actions, such as reformatting a +hard-disk volume. ## Calling Non-Confirmation Methods -If the cmdlet or provider must send a message but not request confirmation, it can call the following three methods. Avoid using the [System.Management.Automation.Cmdlet.WriteObject](/dotnet/api/System.Management.Automation.Cmdlet.WriteObject) method to send messages of these types because [System.Management.Automation.Cmdlet.WriteObject](/dotnet/api/System.Management.Automation.Cmdlet.WriteObject) output is intermingled with the normal output of your cmdlet or provider, which makes script writing difficult. +If the cmdlet or provider must send a message but not request confirmation, it can call the +following three methods. Avoid using the [System.Management.Automation.Cmdlet.WriteObject][05] +method to send messages of these types because [System.Management.Automation.Cmdlet.WriteObject][05] +output is intermingled with the normal output of your cmdlet or provider, which makes script writing +difficult. -- To caution the user and continue with the operation, the cmdlet or provider can call the [System.Management.Automation.Cmdlet.WriteWarning](/dotnet/api/System.Management.Automation.Cmdlet.WriteWarning) method. +- To caution the user and continue with the operation, the cmdlet or provider can call the + [System.Management.Automation.Cmdlet.WriteWarning][07] method. -- To provide additional information that the user can retrieve using the `Verbose` parameter, the cmdlet or provider can call the [System.Management.Automation.Cmdlet.WriteVerbose](/dotnet/api/System.Management.Automation.Cmdlet.WriteVerbose) method. +- To provide additional information that the user can retrieve using the `Verbose` parameter, the + cmdlet or provider can call the [System.Management.Automation.Cmdlet.WriteVerbose][06] method. -- To provide debugging-level detail for other developers or for product support, the cmdlet or provider can call the [System.Management.Automation.Cmdlet.WriteDebug](/dotnet/api/System.Management.Automation.Cmdlet.WriteDebug) method. The user can retrieve this information using the `Debug` parameter. +- To provide debugging-level detail for other developers or for product support, the cmdlet or + provider can call the [System.Management.Automation.Cmdlet.WriteDebug][04] method. The user can + retrieve this information using the `Debug` parameter. -Cmdlets and providers first call the following methods to request confirmation before they attempt to perform an operation that changes a system outside of Windows PowerShell: +Cmdlets and providers first call the following methods to request confirmation before they attempt +to perform an operation that changes a system outside of Windows PowerShell: -- [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) +- [System.Management.Automation.Cmdlet.ShouldProcess][03] -- [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) +- [System.Management.Automation.Provider.CmdletProvider.ShouldProcess][08] -They do so by calling the [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) method, which prompts the user to confirm the operation based on how the user invoked the command. +They do so by calling the [System.Management.Automation.Cmdlet.ShouldProcess][03] method, which +prompts the user to confirm the operation based on how the user invoked the command. ## See Also -[Writing a Windows PowerShell Cmdlet](./writing-a-windows-powershell-cmdlet.md) +[Writing a Windows PowerShell Cmdlet][01] + + +[01]: ./writing-a-windows-powershell-cmdlet.md +[02]: xref:System.Management.Automation.Cmdlet.ShouldContinue%2A +[03]: xref:System.Management.Automation.Cmdlet.ShouldProcess%2A +[04]: xref:System.Management.Automation.Cmdlet.WriteDebug%2A +[05]: xref:System.Management.Automation.Cmdlet.WriteObject%2A +[06]: xref:System.Management.Automation.Cmdlet.WriteVerbose%2A +[07]: xref:System.Management.Automation.Cmdlet.WriteWarning%2A +[08]: xref:System.Management.Automation.Provider.CmdletProvider.ShouldProcess%2A diff --git a/reference/docs-conceptual/developer/cmdlet/requesting-confirmation.md b/reference/docs-conceptual/developer/cmdlet/requesting-confirmation.md index 8496d017956b..6548f9782d52 100644 --- a/reference/docs-conceptual/developer/cmdlet/requesting-confirmation.md +++ b/reference/docs-conceptual/developer/cmdlet/requesting-confirmation.md @@ -5,19 +5,28 @@ title: Requesting Confirmation --- # Requesting Confirmation -This section discusses confirmation messages that can be displayed before a cmdlet, function, or provider performs an action. +This section discusses confirmation messages that can be displayed before a cmdlet, function, or +provider performs an action. ## In This Section -[Requesting Confirmation Process for Commands](./requesting-confirmation-from-cmdlets.md) -Discusses the process that cmdlets, functions, and providers must follow to request a confirmation before they make a change to the system. +[Requesting Confirmation Process for Commands][02] Discusses the process that cmdlets, functions, +and providers must follow to request a confirmation before they make a change to the system. -[Users Requesting Confirmation](./users-requesting-confirmation.md) -Discusses how users can make a cmdlet, function, or provider request confirmation when the [System.Management.Automation.Cmdlet.ShouldProcess](/dotnet/api/System.Management.Automation.Cmdlet.ShouldProcess) method is called. +[Users Requesting Confirmation][03] Discusses how users can make a cmdlet, function, or provider +request confirmation when the [System.Management.Automation.Cmdlet.ShouldProcess][05] method is +called. -[Confirmation Messages](./confirmation-messages.md) -Provides samples of the different confirmation messages that can be displayed. +[Confirmation Messages][01] Provides samples of the different confirmation messages that can be +displayed. ## See Also -[Writing a Windows PowerShell Cmdlet](./writing-a-windows-powershell-cmdlet.md) +[Writing a Windows PowerShell Cmdlet][04] + + +[01]: ./confirmation-messages.md +[02]: ./requesting-confirmation-from-cmdlets.md +[03]: ./users-requesting-confirmation.md +[04]: ./writing-a-windows-powershell-cmdlet.md +[05]: xref:System.Management.Automation.Cmdlet.ShouldProcess%2A diff --git a/reference/docs-conceptual/developer/toc.yml b/reference/docs-conceptual/developer/toc.yml index 63cf1f47a99b..ae250fc2cca5 100644 --- a/reference/docs-conceptual/developer/toc.yml +++ b/reference/docs-conceptual/developer/toc.yml @@ -178,8 +178,6 @@ items: href: cmdlet/how-to-invoke-scripts-within-a-cmdlet.md - name: How to Override Input Processing Methods href: cmdlet/how-to-override-input-processing-methods.md - - name: How to Request Confirmations - href: cmdlet/how-to-request-confirmations.md - name: How to Support Transactions href: cmdlet/how-to-support-transactions.md - name: How to Support Jobs diff --git a/reference/docs-conceptual/discover-powershell.md b/reference/docs-conceptual/discover-powershell.md index d1d84a4811ed..cabce9bf06b6 100644 --- a/reference/docs-conceptual/discover-powershell.md +++ b/reference/docs-conceptual/discover-powershell.md @@ -45,7 +45,7 @@ command you're looking for. When looking for a cmdlet to use, you can filter on When you first pick up PowerShell, it might feel intimidating as there seems to be so much to learn. PowerShell is designed to help you learn a little at a time, as you need it. -PowerShell includes cmdlets that help you discover PowerShell. Using these three cmdlets, you can +PowerShell includes cmdlets that help you discover PowerShell. Using these four cmdlets, you can discover what commands are available, what they do, and what types they operate on. - `Get-Verb`. Running this command returns a list of verbs that most commands adhere to. The diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index 9b4f19e79486..87b6e21ae2e7 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -207,7 +207,7 @@ items: - name: Using Experimental Features href: learn/experimental-features.md - name: Compatibility aliases - href: learn/compatibility-aliases.md + href: learn/shell/using-aliases.md - name: Additional resources href: learn/more-powershell-learning.md - name: Glossary @@ -278,9 +278,9 @@ items: - name: Using Application Control href: security/app-control/application-control.md - name: How WDAC works with PowerShell - href: security/app-control/how-wdac-works.md + href: security/app-control/how-app-control-works.md - name: How to use WDAC to secure PowerShell - href: security/app-control/how-to-use-wdac.md + href: security/app-control/how-to-use-app-control.md - name: Preventing script injection attacks href: security/preventing-script-injection.md - name: PowerShell remoting