MegaBites-AI/Windows-powershell
0372
1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4#nullable enable5 6using System.Management.Automation.Host;7 8namespace System.Management.Automation9{10 /// <summary>11 /// This interface defines the set of functionality that must be implemented to directly12 /// execute an instance of a Cmdlet.13 /// </summary>14 /// <remarks>15 /// When a cmdlet is instantiated and run directly, all calls to the stream APIs will be proxied16 /// through to an instance of this class. For example, when a cmdlet calls WriteObject, the17 /// WriteObject implementation on the instance of the class implementing this interface will be18 /// called. PowerShell implementation provides a default implementation of this class for use with19 /// standalone cmdlets as well as the implementation provided for running in the engine itself.20 ///21 /// If you do want to run Cmdlet instances standalone and capture their output with more22 /// fidelity than is provided for with the default implementation, then you should create your own23 /// implementation of this class and pass it to cmdlets before calling the Cmdlet Invoke() or24 /// Execute() methods.25 /// </remarks>26 public interface ICommandRuntime27 {28 /// <summary>29 /// Returns an instance of the PSHost implementation for this environment.30 /// </summary>31 PSHost? Host { get; }32 #region Write33 /// <summary>34 /// Display debug information.35 /// </summary>36 /// <param name="text">Debug output.</param>37 /// <remarks>38 /// This API is called by the cmdlet to display debug information on the inner workings39 /// of the Cmdlet. An implementation of this interface should display this information in40 /// an appropriately distinctive manner (e.g. through a different color or in a separate41 /// status window. In simple implementations, just ignoring the text and returning is sufficient.42 /// </remarks>43 void WriteDebug(string text);44 45 /// <summary>46 /// Internal variant: Writes the specified error to the error pipe.47 /// </summary>48 /// <remarks>49 /// Do not call WriteError(e.ErrorRecord).50 /// The ErrorRecord contained in the ErrorRecord property of51 /// an exception which implements IContainsErrorRecord52 /// should not be passed directly to WriteError, since it contains53 /// a <see cref="System.Management.Automation.ParentContainsErrorRecordException"/>54 /// rather than the real exception.55 /// </remarks>56 /// <param name="errorRecord">Error.</param>57 void WriteError(ErrorRecord errorRecord);58 59 /// <summary>60 /// Called to write objects to the output pipe.61 /// </summary>62 /// <param name="sendToPipeline">63 /// The object that needs to be written. This will be written as64 /// a single object, even if it is an enumeration.65 /// </param>66 /// <remarks>67 /// When the cmdlet wants to write a single object out, it will call this68 /// API. It is up to the implementation to decide what to do with these objects.69 /// </remarks>70 void WriteObject(object? sendToPipeline);71 72 /// <summary>73 /// Called to write one or more objects to the output pipe.74 /// If the object is a collection and the enumerateCollection flag75 /// is true, the objects in the collection76 /// will be written individually.77 /// </summary>78 /// <param name="sendToPipeline">79 /// The object that needs to be written to the pipeline.80 /// </param>81 /// <param name="enumerateCollection">82 /// true if the collection should be enumerated83 /// </param>84 /// <remarks>85 /// When the cmdlet wants to write multiple objects out, it will call this86 /// API. It is up to the implementation to decide what to do with these objects.87 /// </remarks>88 void WriteObject(object? sendToPipeline, bool enumerateCollection);89 90 /// <summary>91 /// Called by the cmdlet to display progress information.92 /// </summary>93 /// <param name="progressRecord">Progress information.</param>94 /// <remarks>95 /// Use WriteProgress to display progress information about96 /// the activity of your Task, when the operation of your Task97 /// could potentially take a long time.98 ///99 /// By default, progress output will100 /// be displayed, although this can be configured with the101 /// ProgressPreference shell variable.102 ///103 /// The implementation of the API should display these progress records104 /// in a fashion appropriate for the application. For example, a GUI application105 /// would implement this as a progress bar of some sort.106 /// </remarks>107 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteDebug(string)"/>108 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteWarning(string)"/>109 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteVerbose(string)"/>110 void WriteProgress(ProgressRecord progressRecord);111 112 /// <summary>113 /// Displays progress output if enabled.114 /// </summary>115 /// <param name="sourceId">116 /// Identifies which command is reporting progress117 /// </param>118 /// <param name="progressRecord">119 /// Progress status to be displayed120 /// </param>121 /// <remarks>122 /// The implementation of the API should display these progress records123 /// in a fashion appropriate for the application. For example, a GUI application124 /// would implement this as a progress bar of some sort.125 /// </remarks>126 void WriteProgress(Int64 sourceId, ProgressRecord progressRecord);127 128 /// <summary>129 /// Called when the cmdlet want to display verbose information.130 /// </summary>131 /// <param name="text">Verbose output.</param>132 /// <remarks>133 /// Cmdlets use WriteVerbose to display more detailed information about134 /// the activity of the Cmdlet. By default, verbose output will135 /// not be displayed, although this can be configured with the136 /// VerbosePreference shell variable137 /// or the -Verbose and -Debug command-line options.138 ///139 /// The implementation of this API should display this addition information140 /// in an appropriate manner e.g. in a different color in a console application141 /// or in a separate window in a GUI application.142 /// </remarks>143 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteDebug(string)"/>144 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteWarning(string)"/>145 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteProgress(ProgressRecord)"/>146 void WriteVerbose(string text);147 148 /// <summary>149 /// Called by the cmdlet to display warning information.150 /// </summary>151 /// <param name="text">Warning output.</param>152 /// <remarks>153 /// Use WriteWarning to display warnings about154 /// the activity of your Cmdlet. By default, warning output will155 /// be displayed, although this can be configured with the156 /// WarningPreference shell variable157 /// or the -Verbose and -Debug command-line options.158 ///159 /// The implementation of this API should display this addition information160 /// in an appropriate manner e.g. in a different color in a console application161 /// or in a separate window in a GUI application.162 /// </remarks>163 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteDebug(string)"/>164 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteVerbose(string)"/>165 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteProgress(ProgressRecord)"/>166 void WriteWarning(string text);167 168 /// <summary>169 /// Write text into pipeline execution log.170 /// </summary>171 /// <param name="text">Text to be written to log.</param>172 /// <remarks>173 /// Use WriteCommandDetail to write important information about cmdlet execution to174 /// pipeline execution log.175 ///176 /// If LogPipelineExecutionDetail is turned on, this information will be written177 /// to PowerShell log under log category "Pipeline execution detail"178 /// </remarks>179 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteDebug(string)"/>180 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteVerbose(string)"/>181 /// <seealso cref="System.Management.Automation.ICommandRuntime.WriteProgress(ProgressRecord)"/>182 void WriteCommandDetail(string text);183 184 #endregion Write185 186 #region Should187 /// <summary>188 /// Called by the cmdlet to confirm the operation with the user. Cmdlets which make changes189 /// (e.g. delete files, stop services etc.) should call ShouldProcess190 /// to give the user the opportunity to confirm that the operation191 /// should actually be performed.192 /// </summary>193 /// <param name="target">194 /// Name of the target resource being acted upon. This will195 /// potentially be displayed to the user.196 /// </param>197 /// <returns>198 /// If ShouldProcess returns true, the operation should be performed.199 /// If ShouldProcess returns false, the operation should not be200 /// performed, and the Cmdlet should move on to the next target resource.201 ///202 /// An implementation should prompt the user in an appropriate manner203 /// and return true or false. An alternative trivial implementation204 /// would be to just return true all the time.205 /// </returns>206 /// <remarks>207 /// A Cmdlet should declare208 /// [Cmdlet( SupportsShouldProcess = true )]209 /// if-and-only-if it calls ShouldProcess before making changes.210 ///211 /// ShouldProcess may only be called during a call to this Cmdlet's212 /// implementation of ProcessRecord, BeginProcessing or EndProcessing,213 /// and only from that thread.214 ///215 /// ShouldProcess will take into account command-line settings216 /// and preference variables in determining what it should return217 /// and whether it should prompt the user.218 /// </remarks>219 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string)"/>220 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string,string)"/>221 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string,string, out ShouldProcessReason)"/>222 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string)"/>223 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string,ref bool,ref bool)"/>224 bool ShouldProcess(string? target);225 226 /// <summary>227 /// Called by a cmdlet to confirm the operation with the user. Cmdlets which make changes228 /// (e.g. delete files, stop services etc.) should call ShouldProcess229 /// to give the user the opportunity to confirm that the operation230 /// should actually be performed.231 ///232 /// This variant allows the caller to specify text for both the233 /// target resource and the action.234 /// </summary>235 /// <param name="target">236 /// Name of the target resource being acted upon. This will237 /// potentially be displayed to the user.238 /// </param>239 /// <param name="action">240 /// Name of the action which is being performed. This will241 /// potentially be displayed to the user. (default is Cmdlet name)242 /// </param>243 /// <returns>244 /// If ShouldProcess returns true, the operation should be performed.245 /// If ShouldProcess returns false, the operation should not be246 /// performed, and the Cmdlet should move on to the next target resource.247 ///248 /// An implementation should prompt the user in an appropriate manner249 /// and return true or false. An alternative trivial implementation250 /// would be to just return true all the time.251 /// </returns>252 /// <remarks>253 /// A Cmdlet should declare254 /// [Cmdlet( SupportsShouldProcess = true )]255 /// if-and-only-if it calls ShouldProcess before making changes.256 ///257 /// ShouldProcess may only be called during a call to this Cmdlet's258 /// implementation of ProcessRecord, BeginProcessing or EndProcessing,259 /// and only from that thread.260 ///261 /// ShouldProcess will take into account command-line settings262 /// and preference variables in determining what it should return263 /// and whether it should prompt the user.264 /// </remarks>265 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string)"/>266 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string,string)"/>267 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string,string, out ShouldProcessReason)"/>268 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string)"/>269 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string,ref bool,ref bool)"/>270 bool ShouldProcess(string? target, string? action);271 272 /// <summary>273 /// Called by a cmdlet to confirm the operation with the user. Cmdlets which make changes274 /// (e.g. delete files, stop services etc.) should call ShouldProcess275 /// to give the user the opportunity to confirm that the operation276 /// should actually be performed.277 ///278 /// This variant allows the caller to specify the complete text279 /// describing the operation, rather than just the name and action.280 /// </summary>281 /// <param name="verboseDescription">282 /// Textual description of the action to be performed.283 /// This is what will be displayed to the user for284 /// ActionPreference.Continue.285 /// </param>286 /// <param name="verboseWarning">287 /// Textual query of whether the action should be performed,288 /// usually in the form of a question.289 /// This is what will be displayed to the user for290 /// ActionPreference.Inquire.291 /// </param>292 /// <param name="caption">293 /// Caption of the window which may be displayed294 /// if the user is prompted whether or not to perform the action.295 /// <paramref name="caption"/> may be displayed by some hosts, but not all.296 /// </param>297 /// <returns>298 /// If ShouldProcess returns true, the operation should be performed.299 /// If ShouldProcess returns false, the operation should not be300 /// performed, and the Cmdlet should move on to the next target resource.301 /// </returns>302 /// <remarks>303 /// A Cmdlet should declare304 /// [Cmdlet( SupportsShouldProcess = true )]305 /// if-and-only-if it calls ShouldProcess before making changes.306 ///307 /// ShouldProcess may only be called during a call to this Cmdlet's308 /// implementation of ProcessRecord, BeginProcessing or EndProcessing,309 /// and only from that thread.310 ///311 /// ShouldProcess will take into account command-line settings312 /// and preference variables in determining what it should return313 /// and whether it should prompt the user.314 ///315 /// An implementation should prompt the user in an appropriate manner316 /// and return true or false. An alternative trivial implementation317 /// would be to just return true all the time.318 /// </remarks>319 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string)"/>320 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string)"/>321 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string,string, out ShouldProcessReason)"/>322 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string)"/>323 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string,ref bool,ref bool)"/>324 bool ShouldProcess(string? verboseDescription, string? verboseWarning, string? caption);325 326 /// <summary>327 /// Called by a cmdlet to confirm the operation with the user. Cmdlets which make changes328 /// (e.g. delete files, stop services etc.) should call ShouldProcess329 /// to give the user the opportunity to confirm that the operation330 /// should actually be performed.331 ///332 /// This variant allows the caller to specify the complete text333 /// describing the operation, rather than just the name and action.334 /// </summary>335 /// <param name="verboseDescription">336 /// Textual description of the action to be performed.337 /// This is what will be displayed to the user for338 /// ActionPreference.Continue.339 /// </param>340 /// <param name="verboseWarning">341 /// Textual query of whether the action should be performed,342 /// usually in the form of a question.343 /// This is what will be displayed to the user for344 /// ActionPreference.Inquire.345 /// </param>346 /// <param name="caption">347 /// Caption of the window which may be displayed348 /// if the user is prompted whether or not to perform the action.349 /// <paramref name="caption"/> may be displayed by some hosts, but not all.350 /// </param>351 /// <param name="shouldProcessReason">352 /// Indicates the reason(s) why ShouldProcess returned what it returned.353 /// Only the reasons enumerated in354 /// <see cref="System.Management.Automation.ShouldProcessReason"/>355 /// are returned.356 /// </param>357 /// <returns>358 /// If ShouldProcess returns true, the operation should be performed.359 /// If ShouldProcess returns false, the operation should not be360 /// performed, and the Cmdlet should move on to the next target resource.361 /// </returns>362 /// <remarks>363 /// A Cmdlet should declare364 /// [Cmdlet( SupportsShouldProcess = true )]365 /// if-and-only-if it calls ShouldProcess before making changes.366 ///367 /// ShouldProcess may only be called during a call to this Cmdlet's368 /// implementation of ProcessRecord, BeginProcessing or EndProcessing,369 /// and only from that thread.370 ///371 /// ShouldProcess will take into account command-line settings372 /// and preference variables in determining what it should return373 /// and whether it should prompt the user.374 ///375 /// An implementation should prompt the user in an appropriate manner376 /// and return true or false. An alternative trivial implementation377 /// would be to just return true all the time.378 /// </remarks>379 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string)"/>380 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string)"/>381 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string,string)"/>382 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string)"/>383 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string,ref bool,ref bool)"/>384 bool ShouldProcess(string? verboseDescription, string? verboseWarning, string? caption, out ShouldProcessReason shouldProcessReason);385 386 /// <summary>387 /// Called by a cmdlet to confirm an operation or grouping of operations with the user.388 /// This differs from ShouldProcess in that it is not affected by389 /// preference settings or command-line parameters,390 /// it always does the query.391 /// This variant only offers Yes/No, not YesToAll/NoToAll.392 /// </summary>393 /// <param name="query">394 /// Textual query of whether the action should be performed,395 /// usually in the form of a question.396 /// </param>397 /// <param name="caption">398 /// Caption of the window which may be displayed399 /// when the user is prompted whether or not to perform the action.400 /// It may be displayed by some hosts, but not all.401 /// </param>402 /// <returns>403 /// If ShouldContinue returns true, the operation should be performed.404 /// If ShouldContinue returns false, the operation should not be405 /// performed, and the Cmdlet should move on to the next target resource.406 /// </returns>407 /// <remarks>408 /// Cmdlets using ShouldContinue should also offer a "bool Force"409 /// parameter which bypasses the calls to ShouldContinue410 /// and ShouldProcess.411 /// If this is not done, it will be difficult to use the Cmdlet412 /// from scripts and non-interactive hosts.413 ///414 /// Cmdlets using ShouldContinue must still verify operations415 /// which will make changes using ShouldProcess.416 /// This will assure that settings such as -WhatIf work properly.417 /// You may call ShouldContinue either before or after ShouldProcess.418 ///419 /// ShouldContinue may only be called during a call to this Cmdlet's420 /// implementation of ProcessRecord, BeginProcessing or EndProcessing,421 /// and only from that thread.422 ///423 /// Cmdlets may have different "classes" of confirmations. For example,424 /// "del" confirms whether files in a particular directory should be425 /// deleted, whether read-only files should be deleted, etc.426 /// Cmdlets can use ShouldContinue to store YesToAll/NoToAll members427 /// for each such "class" to keep track of whether the user has428 /// confirmed "delete all read-only files" etc.429 /// ShouldProcess offers YesToAll/NoToAll automatically,430 /// but answering YesToAll or NoToAll applies to all subsequent calls431 /// to ShouldProcess for the Cmdlet instance.432 ///433 /// An implementation should prompt the user in an appropriate manner434 /// and return true or false. An alternative trivial implementation435 /// would be to just return true all the time.436 /// </remarks>437 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string,ref bool,ref bool)"/>438 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string)"/>439 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string)"/>440 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string,string)"/>441 bool ShouldContinue(string? query, string? caption);442 443 /// <summary>444 /// Called to confirm an operation or grouping of operations with the user.445 /// This differs from ShouldProcess in that it is not affected by446 /// preference settings or command-line parameters,447 /// it always does the query.448 /// This variant offers Yes, No, YesToAll and NoToAll.449 /// </summary>450 /// <param name="query">451 /// Textual query of whether the action should be performed,452 /// usually in the form of a question.453 /// </param>454 /// <param name="caption">455 /// Caption of the window which may be displayed456 /// when the user is prompted whether or not to perform the action.457 /// It may be displayed by some hosts, but not all.458 /// </param>459 /// <param name="yesToAll">460 /// true if-and-only-if user selects YesToAll. If this is already true,461 /// ShouldContinue will bypass the prompt and return true.462 /// </param>463 /// <param name="noToAll">464 /// true if-and-only-if user selects NoToAll. If this is already true,465 /// ShouldContinue will bypass the prompt and return false.466 /// </param>467 /// <returns>468 /// If ShouldContinue returns true, the operation should be performed.469 /// If ShouldContinue returns false, the operation should not be470 /// performed, and the Cmdlet should move on to the next target resource.471 /// </returns>472 /// <remarks>473 /// Cmdlets using ShouldContinue should also offer a "bool Force"474 /// parameter which bypasses the calls to ShouldContinue475 /// and ShouldProcess.476 /// If this is not done, it will be difficult to use the Cmdlet477 /// from scripts and non-interactive hosts.478 ///479 /// Cmdlets using ShouldContinue must still verify operations480 /// which will make changes using ShouldProcess.481 /// This will assure that settings such as -WhatIf work properly.482 /// You may call ShouldContinue either before or after ShouldProcess.483 ///484 /// ShouldContinue may only be called during a call to this Cmdlet's485 /// implementation of ProcessRecord, BeginProcessing or EndProcessing,486 /// and only from that thread.487 ///488 /// Cmdlets may have different "classes" of confirmations. For example,489 /// "del" confirms whether files in a particular directory should be490 /// deleted, whether read-only files should be deleted, etc.491 /// Cmdlets can use ShouldContinue to store YesToAll/NoToAll members492 /// for each such "class" to keep track of whether the user has493 /// confirmed "delete all read-only files" etc.494 /// ShouldProcess offers YesToAll/NoToAll automatically,495 /// but answering YesToAll or NoToAll applies to all subsequent calls496 /// to ShouldProcess for the Cmdlet instance.497 ///498 /// An implementation should prompt the user in an appropriate manner499 /// and return true or false. An alternative trivial implementation500 /// would be to just return true all the time.501 /// </remarks>502 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldContinue(string,string)"/>503 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string)"/>504 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string)"/>505 /// <seealso cref="System.Management.Automation.ICommandRuntime.ShouldProcess(string,string,string)"/>506 bool ShouldContinue(string? query, string? caption, ref bool yesToAll, ref bool noToAll);507 508 #endregion Should509 510 #region Transaction Support511 /// <summary>512 /// Returns true if a transaction is available and active.513 /// </summary>514 bool TransactionAvailable();515 516 /// <summary>517 /// Gets an object that surfaces the current PowerShell transaction.518 /// When this object is disposed, PowerShell resets the active transaction.519 /// </summary>520 PSTransactionContext? CurrentPSTransaction { get; }521 #endregion Transaction Support522 523 #region Misc524 #region ThrowTerminatingError525 /// <summary>526 /// This interface will be called to route fatal errors from a cmdlet.527 /// </summary>528 /// <param name="errorRecord">529 /// The error which caused the command to be terminated530 /// </param>531 /// <remarks>532 /// <see cref="System.Management.Automation.Cmdlet.ThrowTerminatingError"/>533 /// terminates the command, where534 /// <see cref="System.Management.Automation.ICommandRuntime.WriteError"/>535 /// allows the command to continue.536 ///537 /// The cmdlet can also terminate the command by simply throwing538 /// any exception. When the cmdlet's implementation of539 /// <see cref="System.Management.Automation.Cmdlet.ProcessRecord"/>,540 /// <see cref="System.Management.Automation.Cmdlet.BeginProcessing"/> or541 /// <see cref="System.Management.Automation.Cmdlet.EndProcessing"/>542 /// throws an exception, the Engine will always catch the exception543 /// and report it as a terminating error.544 /// However, it is preferred for the cmdlet to call545 /// <see cref="System.Management.Automation.Cmdlet.ThrowTerminatingError"/>,546 /// so that the additional information in547 /// <see cref="System.Management.Automation.ErrorRecord"/>548 /// is available.549 ///550 /// It is up to the implementation of this routine to determine what551 /// if any information is to be added. It should encapsulate the552 /// error record into an exception and then throw that exception.553 /// </remarks>554 [System.Diagnostics.CodeAnalysis.DoesNotReturn]555 void ThrowTerminatingError(ErrorRecord errorRecord);556 #endregion ThrowTerminatingError557 #endregion misc558 559 }560 561 /// <summary>562 /// This interface defines the set of functionality that must be implemented to directly563 /// execute an instance of a Cmdlet. ICommandRuntime2 extends the ICommandRuntime interface564 /// by adding support for the informational data stream.565 /// </summary>566 public interface ICommandRuntime2 : ICommandRuntime567 {568 /// <summary>569 /// Write an informational record to the command runtime.570 /// </summary>571 /// <param name="informationRecord">The informational record that should be transmitted to the host or user.</param>572 void WriteInformation(InformationRecord informationRecord);573 574 /// <summary>575 /// Confirm an operation or grouping of operations with the user.576 /// This differs from ShouldProcess in that it is not affected by577 /// preference settings or command-line parameters,578 /// it always does the query.579 /// This variant offers Yes, No, YesToAll and NoToAll.580 /// </summary>581 /// <param name="query">582 /// Textual query of whether the action should be performed,583 /// usually in the form of a question.584 /// </param>585 /// <param name="caption">586 /// Caption of the window which may be displayed587 /// when the user is prompted whether or not to perform the action.588 /// It may be displayed by some hosts, but not all.589 /// </param>590 /// <param name="hasSecurityImpact">591 /// true if the operation being confirmed has a security impact. If specified,592 /// the default option selected in the selection menu is 'No'.593 /// </param>594 /// <param name="yesToAll">595 /// true if-and-only-if user selects YesToAll. If this is already true,596 /// ShouldContinue will bypass the prompt and return true.597 /// </param>598 /// <param name="noToAll">599 /// true if-and-only-if user selects NoToAll. If this is already true,600 /// ShouldContinue will bypass the prompt and return false.601 /// </param>602 /// <exception cref="System.Management.Automation.PipelineStoppedException">603 /// The pipeline has already been terminated, or was terminated604 /// during the execution of this method.605 /// The Cmdlet should generally just allow PipelineStoppedException606 /// to percolate up to the caller of ProcessRecord etc.607 /// </exception>608 /// <exception cref="System.InvalidOperationException">609 /// Not permitted at this time or from this thread.610 /// ShouldContinue may only be called during a call to this Cmdlet's611 /// implementation of ProcessRecord, BeginProcessing or EndProcessing,612 /// and only from that thread.613 /// </exception>614 /// <returns>615 /// If ShouldContinue returns true, the operation should be performed.616 /// If ShouldContinue returns false, the operation should not be617 /// performed, and the Cmdlet should move on to the next target resource.618 /// </returns>619 [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1045:DoNotPassTypesByReference")]620 bool ShouldContinue(string? query, string? caption, bool hasSecurityImpact, ref bool yesToAll, ref bool noToAll);621 }622}623