MegaBites-AI/Windows-powershell
0372
1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Diagnostics.CodeAnalysis;5using System.Globalization;6using System.Management.Automation.Host;7using System.Management.Automation.Tracing;8 9using Microsoft.PowerShell;10using Microsoft.PowerShell.Commands;11 12namespace System.Management.Automation.Runspaces13{14 /// <summary>15 /// Defines a factory class for creating Runspace objects.16 /// </summary>17 public static class RunspaceFactory18 {19 /// <summary>20 /// Static constructor.21 /// </summary>22 static RunspaceFactory()23 {24 // Set ETW activity Id25 Guid activityId = EtwActivity.GetActivityId();26 27 if (activityId == Guid.Empty)28 {29 EtwActivity.SetActivityId(EtwActivity.CreateActivityId());30 }31 }32 33 #region Runspace Factory34 35 /// <summary>36 /// Creates a runspace using host of type <see cref="DefaultHost"/>.37 /// </summary>38 /// <returns>39 /// A runspace object.40 /// </returns>41 public static Runspace CreateRunspace()42 {43 PSHost host = new DefaultHost(CultureInfo.CurrentCulture, CultureInfo.CurrentUICulture);44 45 return CreateRunspace(host);46 }47 48 /// <summary>49 /// Creates a runspace using specified host. This runspace is created using the50 /// configuration information from EntryAssembly.51 /// </summary>52 /// <param name="host">53 /// The explicit PSHost implementation.54 /// </param>55 /// <returns>56 /// A runspace object57 /// </returns>58 /// <exception cref="ArgumentNullException">59 /// Thrown when host is null.60 /// </exception>61 public static Runspace CreateRunspace(PSHost host)62 {63 if (host == null)64 {65 throw PSTraceSource.NewArgumentNullException(nameof(host));66 }67 68 return new LocalRunspace(host, InitialSessionState.CreateDefault());69 }70 71 /// <summary>72 /// Creates a runspace using <see cref="DefaultHost"/>73 /// </summary>74 /// <param name="initialSessionState">75 /// InitialSessionState information for the runspace.76 /// </param>77 /// <returns>78 /// A runspace object79 /// </returns>80 /// <exception cref="ArgumentNullException">81 /// Thrown when initialSessionState is null82 /// </exception>83 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspace")]84 public static Runspace CreateRunspace(InitialSessionState initialSessionState)85 {86 if (initialSessionState == null)87 {88 throw PSTraceSource.NewArgumentNullException(nameof(initialSessionState));89 }90 91 PSHost host = new DefaultHost(CultureInfo.CurrentCulture, CultureInfo.CurrentUICulture);92 93 return CreateRunspace(host, initialSessionState);94 }95 96 /// <summary>97 /// Creates a runspace using specified PSHost and InitialSessionState.98 /// </summary>99 /// <param name="host">100 /// Host implementation for runspace.101 /// </param>102 /// <param name="initialSessionState">103 /// InitialSessionState information for the runspace.104 /// </param>105 /// <returns>106 /// A runspace object107 /// </returns>108 /// <exception cref="ArgumentNullException">109 /// Thrown when host is null110 /// </exception>111 /// <exception cref="ArgumentNullException">112 /// Thrown when initialSessionState is null113 /// </exception>114 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspace")]115 public static Runspace CreateRunspace(PSHost host, InitialSessionState initialSessionState)116 {117 if (host == null)118 {119 throw PSTraceSource.NewArgumentNullException(nameof(host));120 }121 122 if (initialSessionState == null)123 {124 throw PSTraceSource.NewArgumentNullException(nameof(initialSessionState));125 }126 127 return new LocalRunspace(host, initialSessionState);128 }129 130 /// <summary>131 /// Creates a runspace using specified PSHost and InitialSessionState.132 /// </summary>133 /// <param name="host">134 /// Host implementation for runspace.135 /// </param>136 /// <param name="initialSessionState">137 /// InitialSessionState information for the runspace.138 /// </param>139 /// <returns>140 /// A runspace object141 /// </returns>142 /// <exception cref="ArgumentNullException">143 /// Thrown when host is null144 /// </exception>145 /// <exception cref="ArgumentNullException">146 /// Thrown when initialSessionState is null147 /// </exception>148 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspace")]149 internal static Runspace CreateRunspaceFromSessionStateNoClone(PSHost host, InitialSessionState initialSessionState)150 {151 if (host == null)152 {153 throw PSTraceSource.NewArgumentNullException(nameof(host));154 }155 156 if (initialSessionState == null)157 {158 throw PSTraceSource.NewArgumentNullException(nameof(initialSessionState));159 }160 161 return new LocalRunspace(host, initialSessionState, true);162 }163 164 #endregion165 166 #region RunspacePool Factory167 168 /// <summary>169 /// Creates a RunspacePool with MaxRunspaces 1 and MinRunspaces 1.170 /// </summary>171 public static RunspacePool CreateRunspacePool()172 {173 return CreateRunspacePool(1, 1);174 }175 176 /// <summary>177 /// Creates a RunspacePool178 /// <paramref name="maxRunspaces"/>179 /// limits the number of Runspaces that can exist in this180 /// pool. The minimum pool size is set to <paramref name="minPoolSoze"/>.181 /// </summary>182 /// <param name="minRunspaces">183 /// The minimum number of Runspaces that exist in this184 /// pool. Should be greater than or equal to 1.185 /// </param>186 /// <param name="maxRunspaces">187 /// The maximum number of Runspaces that can exist in this188 /// pool. Should be greater than or equal to 1.189 /// </param>190 /// <exception cref="ArgumentException">191 /// Maximum runspaces is less than 1.192 /// Minimum runspaces is less than 1.193 /// </exception>194 public static RunspacePool CreateRunspacePool(int minRunspaces, int maxRunspaces)195 {196 return CreateRunspacePool(minRunspaces, maxRunspaces,197 new DefaultHost198 (199 CultureInfo.CurrentCulture,200 CultureInfo.CurrentUICulture201 ));202 }203 204 /// <summary>205 /// Creates a RunspacePool using the supplied <paramref name="initialSessionState"/>.206 /// The minimum runspaces size is set to 1. The maximum runspaces size is207 /// set to 1.208 /// </summary>209 /// <param name="initialSessionState">210 /// initialSessionState to use when creating a new211 /// Runspace in the pool.212 /// </param>213 /// <exception cref="ArgumentNullException">214 /// InitialSessionState is null.215 /// </exception>216 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspace")]217 public static RunspacePool CreateRunspacePool(InitialSessionState initialSessionState)218 {219 return CreateRunspacePool(1, 1, initialSessionState,220 new DefaultHost221 (222 CultureInfo.CurrentCulture,223 CultureInfo.CurrentUICulture224 ));225 }226 227 /// <summary>228 /// Creates a RunspacePool using the supplied <paramref name="host"/>,229 /// <paramref name="minRunspaces"/> and <paramref name="maxRunspaces"/>230 /// </summary>231 /// <param name="minRunspaces">232 /// The minimum number of Runspaces that can exist in this pool.233 /// Should be greater than or equal to 1.234 /// </param>235 /// <param name="maxRunspaces">236 /// The maximum number of Runspaces that can exist in this pool.237 /// Should be greater than or equal to 1.238 /// </param>239 /// <param name="host">240 /// The explicit PSHost implementation.241 /// </param>242 /// <exception cref="ArgumentNullException">243 /// <paramref name="host"/> is null.244 /// </exception>245 /// <returns>246 /// A local runspacepool instance.247 /// </returns>248 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspaces")]249 public static RunspacePool CreateRunspacePool(int minRunspaces, int maxRunspaces, PSHost host)250 {251 return new RunspacePool(minRunspaces, maxRunspaces, host);252 }253 254 /// <summary>255 /// Creates a RunspacePool using the supplied <paramref name="initialSessionState"/>,256 /// <paramref name="minRunspaces"/> and <paramref name="maxRunspaces"/>257 /// </summary>258 /// <param name="minRunspaces">259 /// The minimum number of Runspaces that can exist in this pool.260 /// Should be greater than or equal to 1.261 /// </param>262 /// <param name="maxRunspaces">263 /// The maximum number of Runspaces that can exist in this pool.264 /// Should be greater than or equal to 1.265 /// </param>266 /// <param name="initialSessionState">267 /// initialSessionState to use when creating a new Runspace in the268 /// pool.269 /// </param>270 /// <exception cref="ArgumentNullException">271 /// InitialSessionState is null.272 /// </exception>273 /// <param name="host">274 /// The explicit PSHost implementation.275 /// </param>276 /// <exception cref="ArgumentNullException">277 /// <paramref name="initialSessionState"/> is null.278 /// <paramref name="host"/> is null.279 /// </exception>280 /// <exception cref="ArgumentException">281 /// Maximum runspaces is less than 1.282 /// Minimum runspaces is less than 1.283 /// </exception>284 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspace")]285 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspaces")]286 public static RunspacePool CreateRunspacePool(int minRunspaces, int maxRunspaces,287 InitialSessionState initialSessionState, PSHost host)288 {289 return new RunspacePool(minRunspaces,290 maxRunspaces, initialSessionState, host);291 }292 293 #endregion294 295 #region RunspacePool - remote Factory296 297 /// <summary>298 /// Creates a RunspacePool299 /// on the specified remote computer.300 /// <paramref name="maxRunspaces"/>301 /// limits the number of Runspaces that can exist in this302 /// pool. The minimum pool size is set to303 /// <paramref name="minPoolSoze"/>.304 /// </summary>305 /// <param name="minRunspaces">306 /// The minimum number of Runspace that should exist in this307 /// pool. Should be greater than 1.308 /// </param>309 /// <param name="maxRunspaces">310 /// The maximum number of Runspaces that can exist in this311 /// pool. Should be greater than or equal to 1.312 /// </param>313 /// <param name="connectionInfo">RunspaceConnectionInfo object describing314 /// the remote computer on which this runspace pool needs to be315 /// created</param>316 /// <exception cref="ArgumentException">317 /// Maximum Pool size is less than 1.318 /// Minimum Pool size is less than 1.319 /// </exception>320 /// <exception cref="ArgumentNullException">321 /// connectionInfo is null</exception>322 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspaces")]323 public static RunspacePool CreateRunspacePool(int minRunspaces,324 int maxRunspaces, RunspaceConnectionInfo connectionInfo)325 {326 return CreateRunspacePool(minRunspaces, maxRunspaces, connectionInfo, null);327 }328 329 /// <summary>330 /// Creates a RunspacePool331 /// on the specified remote runspace computer.332 /// <paramref name="maxRunspaces"/>333 /// limits the number of Runspaces that can exist in this334 /// pool. The minimum pool size is set to335 /// <paramref name="minPoolSoze"/>.336 /// </summary>337 /// <param name="minRunspaces">338 /// The minimum number of Runspace that should exist in this339 /// pool. Should be greater than 1.340 /// </param>341 /// <param name="maxRunspaces">342 /// The maximum number of Runspaces that can exist in this343 /// pool. Should be greater than or equal to 1.344 /// </param>345 /// <param name="host">Host associated with this346 /// runspace pool</param>347 /// <param name="connectionInfo">RunspaceConnectionInfo object describing348 /// the remote computer on which this runspace pool needs to be349 /// created</param>350 /// <exception cref="ArgumentException">351 /// Maximum Pool size is less than 1.352 /// Minimum Pool size is less than 1.353 /// </exception>354 /// <exception cref="ArgumentNullException">355 /// connectionInfo is null</exception>356 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspaces")]357 public static RunspacePool CreateRunspacePool(int minRunspaces,358 int maxRunspaces, RunspaceConnectionInfo connectionInfo, PSHost host)359 {360 return CreateRunspacePool(minRunspaces, maxRunspaces, connectionInfo, host, null);361 }362 363 /// <summary>364 /// Creates a RunspacePool365 /// on the specified remote runspace computer.366 /// <paramref name="maxRunspaces"/>367 /// limits the number of Runspaces that can exist in this368 /// pool. The minimum pool size is set to369 /// <paramref name="minPoolSoze"/>.370 /// </summary>371 /// <param name="minRunspaces">372 /// The minimum number of Runspace that should exist in this373 /// pool. Should be greater than 1.374 /// </param>375 /// <param name="maxRunspaces">376 /// The maximum number of Runspaces that can exist in this377 /// pool. Should be greater than or equal to 1.378 /// </param>379 /// <param name="typeTable">380 /// The TypeTable to use while deserializing/serializing remote objects.381 /// TypeTable has the following information used by serializer:382 /// 1. SerializationMethod383 /// 2. SerializationDepth384 /// 3. SpecificSerializationProperties385 /// TypeTable has the following information used by deserializer:386 /// 1. TargetTypeForDeserialization387 /// 2. TypeConverter388 ///389 /// If <paramref name="typeTable"/> is null no custom serialization/deserialization390 /// can be done. Default PowerShell behavior will be used in this case.391 /// </param>392 /// <param name="host">Host associated with this393 /// runspace pool</param>394 /// <param name="connectionInfo">RunspaceConnectionInfo object describing395 /// the remote computer on which this runspace pool needs to be396 /// created</param>397 /// <exception cref="ArgumentException">398 /// Maximum Pool size is less than 1.399 /// Minimum Pool size is less than 1.400 /// </exception>401 /// <exception cref="ArgumentNullException">402 /// connectionInfo is null</exception>403 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspaces")]404 public static RunspacePool CreateRunspacePool(int minRunspaces,405 int maxRunspaces, RunspaceConnectionInfo connectionInfo, PSHost host, TypeTable typeTable)406 {407 return CreateRunspacePool(minRunspaces, maxRunspaces, connectionInfo, host, typeTable, null);408 }409 410 /// <summary>411 /// Creates a RunspacePool412 /// on the specified remote runspace computer.413 /// <paramref name="maxRunspaces"/>414 /// limits the number of Runspaces that can exist in this415 /// pool. The minimum pool size is set to416 /// <paramref name="minPoolSoze"/>.417 /// </summary>418 /// <param name="minRunspaces">419 /// The minimum number of Runspace that should exist in this420 /// pool. Should be greater than 1.421 /// </param>422 /// <param name="maxRunspaces">423 /// The maximum number of Runspaces that can exist in this424 /// pool. Should be greater than or equal to 1.425 /// </param>426 /// <param name="typeTable">427 /// The TypeTable to use while deserializing/serializing remote objects.428 /// TypeTable has the following information used by serializer:429 /// 1. SerializationMethod430 /// 2. SerializationDepth431 /// 3. SpecificSerializationProperties432 /// TypeTable has the following information used by deserializer:433 /// 1. TargetTypeForDeserialization434 /// 2. TypeConverter435 ///436 /// If <paramref name="typeTable"/> is null no custom serialization/deserialization437 /// can be done. Default PowerShell behavior will be used in this case.438 /// </param>439 /// <param name="host">Host associated with this440 /// runspace pool</param>441 /// <param name="applicationArguments">442 /// Application arguments the server can see in <see cref="System.Management.Automation.Remoting.PSSenderInfo.ApplicationArguments"/>443 /// </param>444 /// <param name="connectionInfo">RunspaceConnectionInfo object describing445 /// the remote computer on which this runspace pool needs to be446 /// created</param>447 /// <exception cref="ArgumentException">448 /// Maximum Pool size is less than 1.449 /// Minimum Pool size is less than 1.450 /// </exception>451 /// <exception cref="ArgumentNullException">452 /// connectionInfo is null</exception>453 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Runspaces")]454 public static RunspacePool CreateRunspacePool(int minRunspaces,455 int maxRunspaces, RunspaceConnectionInfo connectionInfo, PSHost host, TypeTable typeTable, PSPrimitiveDictionary applicationArguments)456 {457 if (connectionInfo is not WSManConnectionInfo &&458 connectionInfo is not NewProcessConnectionInfo &&459 connectionInfo is not NamedPipeConnectionInfo &&460 connectionInfo is not VMConnectionInfo &&461 connectionInfo is not ContainerConnectionInfo)462 {463 throw new NotSupportedException();464 }465 466 if (connectionInfo is WSManConnectionInfo)467 {468 RemotingCommandUtil.CheckHostRemotingPrerequisites();469 }470 471 return new RunspacePool(minRunspaces, maxRunspaces, typeTable, host, applicationArguments, connectionInfo);472 }473 474 #endregion RunspacePool - remote Factory475 476 #region Runspace - Remote Factory477 478 /// <summary>479 /// Creates a remote Runspace.480 /// </summary>481 /// <param name="connectionInfo">It defines connection path to a remote runspace that needs to be created.</param>482 /// <param name="host">The explicit PSHost implementation.</param>483 /// <param name="typeTable">484 /// The TypeTable to use while deserializing/serializing remote objects.485 /// TypeTable has the following information used by serializer:486 /// 1. SerializationMethod487 /// 2. SerializationDepth488 /// 3. SpecificSerializationProperties489 ///490 /// TypeTable has the following information used by deserializer:491 /// 1. TargetTypeForDeserialization492 /// 2. TypeConverter493 /// </param>494 /// <returns>A remote Runspace.</returns>495 public static Runspace CreateRunspace(RunspaceConnectionInfo connectionInfo, PSHost host, TypeTable typeTable)496 {497 return CreateRunspace(connectionInfo, host, typeTable, null, null);498 }499 500 /// <summary>501 /// Creates a remote Runspace.502 /// </summary>503 /// <param name="connectionInfo">It defines connection path to a remote runspace that needs to be created.</param>504 /// <param name="host">The explicit PSHost implementation.</param>505 /// <param name="typeTable">506 /// The TypeTable to use while deserializing/serializing remote objects.507 /// TypeTable has the following information used by serializer:508 /// 1. SerializationMethod509 /// 2. SerializationDepth510 /// 3. SpecificSerializationProperties511 ///512 /// TypeTable has the following information used by deserializer:513 /// 1. TargetTypeForDeserialization514 /// 2. TypeConverter515 /// </param>516 /// <param name="applicationArguments">517 /// Application arguments the server can see in <see cref="System.Management.Automation.Remoting.PSSenderInfo.ApplicationArguments"/>518 /// </param>519 /// <returns>A remote Runspace.</returns>520 public static Runspace CreateRunspace(RunspaceConnectionInfo connectionInfo, PSHost host, TypeTable typeTable, PSPrimitiveDictionary applicationArguments)521 {522 return CreateRunspace(connectionInfo, host, typeTable, applicationArguments, null);523 }524 525 /// <summary>526 /// Creates a remote Runspace.527 /// </summary>528 /// <param name="connectionInfo">It defines connection path to a remote runspace that needs to be created.</param>529 /// <param name="host">The explicit PSHost implementation.</param>530 /// <param name="typeTable">531 /// The TypeTable to use while deserializing/serializing remote objects.532 /// TypeTable has the following information used by serializer:533 /// 1. SerializationMethod534 /// 2. SerializationDepth535 /// 3. SpecificSerializationProperties536 ///537 /// TypeTable has the following information used by deserializer:538 /// 1. TargetTypeForDeserialization539 /// 2. TypeConverter540 /// </param>541 /// <param name="applicationArguments">542 /// Application arguments the server can see in <see cref="System.Management.Automation.Remoting.PSSenderInfo.ApplicationArguments"/>543 /// </param>544 /// <param name="name">Name for remote runspace.</param>545 /// <returns>A remote Runspace.</returns>546 public static Runspace CreateRunspace(RunspaceConnectionInfo connectionInfo, PSHost host, TypeTable typeTable, PSPrimitiveDictionary applicationArguments, string name)547 {548 if (connectionInfo is WSManConnectionInfo)549 {550 RemotingCommandUtil.CheckHostRemotingPrerequisites();551 }552 553 return new RemoteRunspace(typeTable, connectionInfo, host, applicationArguments, name);554 }555 556 /// <summary>557 /// Creates a remote Runspace.558 /// </summary>559 /// <param name="host">The explicit PSHost implementation.</param>560 /// <param name="connectionInfo">It defines connection path to a remote runspace that needs to be created.</param>561 /// <returns>A remote Runspace.</returns>562 public static Runspace CreateRunspace(PSHost host, RunspaceConnectionInfo connectionInfo)563 {564 return CreateRunspace(connectionInfo, host, null);565 }566 567 /// <summary>568 /// Creates a remote Runspace.569 /// </summary>570 /// <param name="connectionInfo">It defines connection path to a remote runspace that needs to be created.</param>571 /// <returns>A remote Runspace.</returns>572 public static Runspace CreateRunspace(RunspaceConnectionInfo connectionInfo)573 {574 return CreateRunspace(null, connectionInfo);575 }576 577 #endregion Runspace - Remote Factory578 579 #region V3 Extensions580 581 /// <summary>582 /// Creates an out-of-process remote Runspace.583 /// </summary>584 /// <param name="typeTable">585 /// The TypeTable to use while deserializing/serializing remote objects.586 /// TypeTable has the following information used by serializer:587 /// 1. SerializationMethod588 /// 2. SerializationDepth589 /// 3. SpecificSerializationProperties590 ///591 /// TypeTable has the following information used by deserializer:592 /// 1. TargetTypeForDeserialization593 /// 2. TypeConverter594 /// </param>595 /// <returns>An out-of-process remote Runspace.</returns>596 public static Runspace CreateOutOfProcessRunspace(TypeTable typeTable)597 {598 NewProcessConnectionInfo connectionInfo = new NewProcessConnectionInfo(null);599 600 return CreateRunspace(connectionInfo, null, typeTable);601 }602 603 /// <summary>604 /// Creates an out-of-process remote Runspace.605 /// </summary>606 /// <param name="typeTable">607 /// The TypeTable to use while deserializing/serializing remote objects.608 /// TypeTable has the following information used by serializer:609 /// 1. SerializationMethod610 /// 2. SerializationDepth611 /// 3. SpecificSerializationProperties612 ///613 /// TypeTable has the following information used by deserializer:614 /// 1. TargetTypeForDeserialization615 /// 2. TypeConverter616 /// </param>617 /// <param name="processInstance">It represents a PowerShell process that is used for an out-of-process remote Runspace</param>618 /// <returns>An out-of-process remote Runspace.</returns>619 public static Runspace CreateOutOfProcessRunspace(TypeTable typeTable, PowerShellProcessInstance processInstance)620 {621 NewProcessConnectionInfo connectionInfo = new NewProcessConnectionInfo(null) { Process = processInstance };622 623 return CreateRunspace(connectionInfo, null, typeTable);624 }625 626 #endregion V3 Extensions627 }628}629