admin/PowerShell-PowerShell
1
0
Fork 0
mirror of https://github.com/PowerShell/PowerShell synced 2026-06-08 12:12:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve CommandInvocationIntrinsics API documentation and style (#14369)

Browse Source
This commit is contained in:
Robert Holt
2021-09-03 16:05:30 -07:00
committed by GitHub
parent 66b5d50170
commit 17986d88c1
1 changed files with 42 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/System.Management.Automation/engine/MshCmdlet.cs
+42 -23
View File
@@ -674,40 +674,46 @@ namespace System.Management.Automation
}
/// <summary>
/// Executes a piece of text as a script synchronously.
/// Executes a piece of text as a script synchronously in the caller's session state.
/// The given text will be executed in a child scope rather than dot-sourced.
/// </summary>
/// <param name="script">The script text to evaluate.</param>
/// <returns>A collection of MshCobjects generated by the script.</returns>
/// <returns>A collection of MshCobjects generated by the script. Never null, but may be empty.</returns>
/// <exception cref="ParseException">Thrown if there was a parsing error in the script.</exception>
/// <exception cref="RuntimeException">Represents a script-level exception.</exception>
/// <exception cref="FlowControlException"></exception>
public Collection<PSObject> InvokeScript(string script)
{
return InvokeScript(script, true, PipelineResultTypes.None, null);
return InvokeScript(script, useNewScope: true, PipelineResultTypes.None, input: null);
}
/// <summary>
/// Executes a piece of text as a script synchronously.
/// Executes a piece of text as a script synchronously in the caller's session state.
/// The given text will be executed in a child scope rather than dot-sourced.
/// </summary>
/// <param name="script">The script text to evaluate.</param>
/// <param name="args">The arguments to the script.</param>
/// <returns>A collection of MshCobjects generated by the script.</returns>
/// <param name="args">The arguments to the script, available as $args.</param>
/// <returns>A collection of MshCobjects generated by the script. Never null, but may be empty.</returns>
/// <exception cref="ParseException">Thrown if there was a parsing error in the script.</exception>
/// <exception cref="RuntimeException">Represents a script-level exception.</exception>
/// <exception cref="FlowControlException"></exception>
public Collection<PSObject> InvokeScript(string script, params object[] args)
{
return InvokeScript(script, true, PipelineResultTypes.None, null, args);
return InvokeScript(script, useNewScope: true, PipelineResultTypes.None, input: null, args);
}
/// <summary>
/// Executes a given scriptblock synchonously in the given session state.
/// The scriptblock will be executed in the calling scope (dot-sourced) rather than in a new child scope.
/// </summary>
/// <param name="sessionState"></param>
/// <param name="scriptBlock"></param>
/// <param name="args"></param>
/// <returns></returns>
/// <param name="sessionState">The session state in which to execute the scriptblock.</param>
/// <param name="scriptBlock">The scriptblock to execute.</param>
/// <param name="args">The arguments to the scriptblock, available as $args.</param>
/// <returns>A collection of the PSObjects emitted by the executing scriptblock. Never null, but may be empty.</returns>
public Collection<PSObject> InvokeScript(
SessionState sessionState, ScriptBlock scriptBlock, params object[] args)
SessionState sessionState,
ScriptBlock scriptBlock,
params object[] args)
{
if (scriptBlock == null)
{
@@ -739,13 +745,18 @@ namespace System.Management.Automation
/// <summary>
/// Invoke a scriptblock in the current runspace, controlling if it gets a new scope.
/// </summary>
/// <param name="useLocalScope">If true, a new scope will be created.</param>
/// <param name="useLocalScope">If true, executes the scriptblock in a new child scope, otherwise the scriptblock is dot-sourced into the calling scope.</param>
/// <param name="scriptBlock">The scriptblock to execute.</param>
/// <param name="input">Optionall input to the command.</param>
/// <param name="args">Arguments to pass to the scriptblock.</param>
/// <returns>The result of the evaluation.</returns>
/// <returns>
/// A collection of the PSObjects generated by executing the script. Never null, but may be empty.
/// </returns>
public Collection<PSObject> InvokeScript(
bool useLocalScope, ScriptBlock scriptBlock, IList input, params object[] args)
bool useLocalScope,
ScriptBlock scriptBlock,
IList input,
params object[] args)
{
if (scriptBlock == null)
{
@@ -771,21 +782,25 @@ namespace System.Management.Automation
/// </summary>
/// <param name="script">The script to evaluate.</param>
/// <param name="useNewScope">If true, evaluate the script in its own scope.
/// If false, the script will be evaluated in the current scope i.e. it will be "dotted"</param>
/// If false, the script will be evaluated in the current scope i.e. it will be dot-sourced.</param>
/// <param name="writeToPipeline">If set to Output, all output will be streamed
/// to the output pipe of the calling cmdlet. If set to None, the result will be returned
/// to the caller as a collection of PSObjects. No other flags are supported at this time and
/// will result in an exception if used.</param>
/// <param name="input">The list of objects to use as input to the script.</param>
/// <param name="args">The array of arguments to the command.</param>
/// <returns>A collection of MshCobjects generated by the script. This will be
/// empty if output was redirected.</returns>
/// <param name="args">The array of arguments to the command, available as $args.</param>
/// <returns>A collection of PSObjects generated by the script. This will be
/// empty if output was redirected. Never null.</returns>
/// <exception cref="ParseException">Thrown if there was a parsing error in the script.</exception>
/// <exception cref="RuntimeException">Represents a script-level exception.</exception>
/// <exception cref="NotImplementedException">Thrown if any redirect other than output is attempted.</exception>
/// <exception cref="FlowControlException"></exception>
public Collection<PSObject> InvokeScript(string script, bool useNewScope,
PipelineResultTypes writeToPipeline, IList input, params object[] args)
public Collection<PSObject> InvokeScript(
string script,
bool useNewScope,
PipelineResultTypes writeToPipeline,
IList input,
params object[] args)
{
if (script == null)
throw new ArgumentNullException(nameof(script));
@@ -796,8 +811,12 @@ namespace System.Management.Automation
return InvokeScript(sb, useNewScope, writeToPipeline, input, args);
}
private Collection<PSObject> InvokeScript(ScriptBlock sb, bool useNewScope,
PipelineResultTypes writeToPipeline, IList input, params object[] args)
private Collection<PSObject> InvokeScript(
ScriptBlock sb,
bool useNewScope,
PipelineResultTypes writeToPipeline,
IList input,
params object[] args)
{
if (_cmdlet != null)
_cmdlet.ThrowIfStopping();