Cmdlet.ShouldProcess Cmdlet.ShouldProcess Cmdlet.ShouldProcess Method

Definition

Overloads

ShouldProcess(String, String, String, ShouldProcessReason) ShouldProcess(String, String, String, ShouldProcessReason) ShouldProcess(String, String, String, ShouldProcessReason)

Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.

This variant allows the caller to specify the complete text describing the operation, rather than just the name and action.

ShouldProcess(String, String, String) ShouldProcess(String, String, String) ShouldProcess(String, String, String)

Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.

This variant allows the caller to specify the complete text describing the operation, rather than just the name and action.

ShouldProcess(String, String) ShouldProcess(String, String) ShouldProcess(String, String)

Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.

This variant allows the caller to specify text for both the target resource and the action.

ShouldProcess(String) ShouldProcess(String) ShouldProcess(String)

Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.

ShouldProcess(String, String, String, ShouldProcessReason) ShouldProcess(String, String, String, ShouldProcessReason) ShouldProcess(String, String, String, ShouldProcessReason)

Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.

This variant allows the caller to specify the complete text describing the operation, rather than just the name and action.

public bool ShouldProcess (string verboseDescription, string verboseWarning, string caption, out System.Management.Automation.ShouldProcessReason shouldProcessReason);
member this.ShouldProcess : string * string * string *  -> bool
Public Function ShouldProcess (verboseDescription As String, verboseWarning As String, caption As String, ByRef shouldProcessReason As ShouldProcessReason) As Boolean
Parameters
verboseDescription
String String String

Textual description of the action to be performed. This is what will be displayed to the user for ActionPreference.Continue.

verboseWarning
String String String

Textual query of whether the action should be performed, usually in the form of a question. This is what will be displayed to the user for ActionPreference.Inquire.

caption
String String String

Caption of the window which may be displayed if the user is prompted whether or not to perform the action. caption may be displayed by some hosts, but not all.

shouldProcessReason
ShouldProcessReason ShouldProcessReason ShouldProcessReason

Indicates the reason(s) why ShouldProcess returned what it returned. Only the reasons enumerated in ShouldProcessReason are returned.

Returns

If ShouldProcess returns true, the operation should be performed. If ShouldProcess returns false, the operation should not be performed, and the Cmdlet should move on to the next target resource.

Exceptions

The pipeline has already been terminated, or was terminated during the execution of this method. The Cmdlet should generally just allow PipelineStoppedException to percolate up to the caller of ProcessRecord etc.

Not permitted at this time or from this thread. ShouldProcess may only be called during a call to this Cmdlet's implementation of ProcessRecord, BeginProcessing or EndProcessing, and only from that thread.

Examples

namespace Microsoft.Samples.MSH.Cmdlet { [Cmdlet(VerbsCommon.Remove,"myobjecttype3")] public class RemoveMyObjectType3 : Cmdlet { [Parameter( Mandatory = true )] public string Filename { get { return filename; } set { filename = value; } } private string filename; public override void ProcessRecord() { ShouldProcessReason shouldProcessReason; if (ShouldProcess( String.Format("Deleting file {0}",filename), String.Format("Are you sure you want to delete file {0}?", filename), "Delete file", out shouldProcessReason)) { // delete the object } } } } namespace Microsoft.Samples.MSH.Cmdlet { [Cmdlet(VerbsCommon.Remove,"myobjecttype3")] public class RemoveMyObjectType3 : Cmdlet { [Parameter( Mandatory = true )] public string Filename { get { return filename; } set { filename = value; } } private string filename; public override void ProcessRecord() { ShouldProcessReason shouldProcessReason; if (ShouldProcess( String.Format("Deleting file {0}",filename), String.Format("Are you sure you want to delete file {0}?", filename), "Delete file", out shouldProcessReason)) { // delete the object } } } }

Remarks

If the pipeline is terminated due to ActionPreference.Stop or ActionPreference.Inquire, this method will throw PipelineStoppedException, but the command failure will ultimately be ActionPreferenceStopException,

See Also

ShouldProcess(String, String, String) ShouldProcess(String, String, String) ShouldProcess(String, String, String)

Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.

This variant allows the caller to specify the complete text describing the operation, rather than just the name and action.

public bool ShouldProcess (string verboseDescription, string verboseWarning, string caption);
member this.ShouldProcess : string * string * string -> bool
Public Function ShouldProcess (verboseDescription As String, verboseWarning As String, caption As String) As Boolean
Parameters
verboseDescription
String String String

Textual description of the action to be performed. This is what will be displayed to the user for ActionPreference.Continue.

verboseWarning
String String String

Textual query of whether the action should be performed, usually in the form of a question. This is what will be displayed to the user for ActionPreference.Inquire.

caption
String String String

Caption of the window which may be displayed if the user is prompted whether or not to perform the action. caption may be displayed by some hosts, but not all.

Returns

If ShouldProcess returns true, the operation should be performed. If ShouldProcess returns false, the operation should not be performed, and the Cmdlet should move on to the next target resource.

Exceptions

The pipeline has already been terminated, or was terminated during the execution of this method. The Cmdlet should generally just allow PipelineStoppedException to percolate up to the caller of ProcessRecord etc.

Not permitted at this time or from this thread. ShouldProcess may only be called during a call to this Cmdlet's implementation of ProcessRecord, BeginProcessing or EndProcessing, and only from that thread.

Examples

namespace Microsoft.Samples.MSH.Cmdlet { [Cmdlet(VerbsCommon.Remove,"myobjecttype3")] public class RemoveMyObjectType3 : Cmdlet { [Parameter( Mandatory = true )] public string Filename { get { return filename; } set { filename = value; } } private string filename; public override void ProcessRecord() { if (ShouldProcess( String.Format("Deleting file {0}",filename), String.Format("Are you sure you want to delete file {0}?", filename), "Delete file")) { // delete the object } } } } namespace Microsoft.Samples.MSH.Cmdlet { [Cmdlet(VerbsCommon.Remove,"myobjecttype3")] public class RemoveMyObjectType3 : Cmdlet { [Parameter( Mandatory = true )] public string Filename { get { return filename; } set { filename = value; } } private string filename; public override void ProcessRecord() { if (ShouldProcess( String.Format("Deleting file {0}",filename), String.Format("Are you sure you want to delete file {0}?", filename), "Delete file")) { // delete the object } } } }

Remarks

If the pipeline is terminated due to ActionPreference.Stop or ActionPreference.Inquire, this method will throw PipelineStoppedException, but the command failure will ultimately be ActionPreferenceStopException,

See Also

ShouldProcess(String, String) ShouldProcess(String, String) ShouldProcess(String, String)

Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.

This variant allows the caller to specify text for both the target resource and the action.

public bool ShouldProcess (string target, string action);
member this.ShouldProcess : string * string -> bool
Public Function ShouldProcess (target As String, action As String) As Boolean
Parameters
target
String String String

Name of the target resource being acted upon. This will potentially be displayed to the user.

action
String String String

Name of the action which is being performed. This will potentially be displayed to the user. (default is Cmdlet name)

Returns

If ShouldProcess returns true, the operation should be performed. If ShouldProcess returns false, the operation should not be performed, and the Cmdlet should move on to the next target resource.

Exceptions

The pipeline has already been terminated, or was terminated during the execution of this method. The Cmdlet should generally just allow PipelineStoppedException to percolate up to the caller of ProcessRecord etc.

Not permitted at this time or from this thread. ShouldProcess may only be called during a call to this Cmdlet's implementation of ProcessRecord, BeginProcessing or EndProcessing, and only from that thread.

Examples

namespace Microsoft.Samples.MSH.Cmdlet { [Cmdlet(VerbsCommon.Remove,"myobjecttype2")] public class RemoveMyObjectType2 : Cmdlet { [Parameter( Mandatory = true )] public string Filename { get { return filename; } set { filename = value; } } private string filename; public override void ProcessRecord() { if (ShouldProcess(filename, "delete")) { // delete the object } } } } namespace Microsoft.Samples.MSH.Cmdlet { [Cmdlet(VerbsCommon.Remove,"myobjecttype2")] public class RemoveMyObjectType2 : Cmdlet { [Parameter( Mandatory = true )] public string Filename { get { return filename; } set { filename = value; } } private string filename; public override void ProcessRecord() { if (ShouldProcess(filename, "delete")) { // delete the object } } } }

Remarks

If the pipeline is terminated due to ActionPreference.Stop or ActionPreference.Inquire, this method will throw PipelineStoppedException, but the command failure will ultimately be ActionPreferenceStopException,

See Also

ShouldProcess(String) ShouldProcess(String) ShouldProcess(String)

Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.

public bool ShouldProcess (string target);
member this.ShouldProcess : string -> bool
Public Function ShouldProcess (target As String) As Boolean
Parameters
target
String String String

Name of the target resource being acted upon. This will potentially be displayed to the user.

Returns

If ShouldProcess returns true, the operation should be performed. If ShouldProcess returns false, the operation should not be performed, and the Cmdlet should move on to the next target resource.

Exceptions

The pipeline has already been terminated, or was terminated during the execution of this method. The Cmdlet should generally just allow PipelineStoppedException to percolate up to the caller of ProcessRecord etc.

Not permitted at this time or from this thread. ShouldProcess may only be called during a call to this Cmdlet's implementation of ProcessRecord, BeginProcessing or EndProcessing, and only from that thread.

Examples

namespace Microsoft.Samples.MSH.Cmdlet { [Cmdlet(VerbsCommon.Remove,"myobjecttype1")] public class RemoveMyObjectType1 : Cmdlet { [Parameter( Mandatory = true )] public string Filename { get { return filename; } set { filename = value; } } private string filename; public override void ProcessRecord() { if (ShouldProcess(filename)) { // delete the object } } } } namespace Microsoft.Samples.MSH.Cmdlet { [Cmdlet(VerbsCommon.Remove,"myobjecttype1")] public class RemoveMyObjectType1 : Cmdlet { [Parameter( Mandatory = true )] public string Filename { get { return filename; } set { filename = value; } } private string filename; public override void ProcessRecord() { if (ShouldProcess(filename)) { // delete the object } } } }

Remarks

If the pipeline is terminated due to ActionPreference.Stop or ActionPreference.Inquire, ShouldProcess(String) will throw PipelineStoppedException, but the command failure will ultimately be ActionPreferenceStopException,

See Also

Applies to