MegaBites-AI/Windows-powershell
0308
1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4#region Using directives5 6using System;7using System.Collections.Generic;8using System.Diagnostics.CodeAnalysis;9using System.Management.Automation;10 11#endregion12 13namespace Microsoft.Management.Infrastructure.CimCmdlets14{15 /// <summary>16 /// Returns zero, one or more CIM (dynamic) instances with the properties17 /// specified in the Property parameter, KeysOnly parameter or the Select clause18 /// of the Query parameter.19 /// </summary>20 [Alias("gcim")]21 [Cmdlet(VerbsCommon.Get, "CimInstance", DefaultParameterSetName = CimBaseCommand.ClassNameComputerSet, HelpUri = "https://go.microsoft.com/fwlink/?LinkId=227961")]22 [OutputType(typeof(CimInstance))]23 public class GetCimInstanceCommand : CimBaseCommand24 {25 #region constructor26 27 /// <summary>28 /// Initializes a new instance of the <see cref="GetCimInstanceCommand"/> class.29 /// Constructor.30 /// </summary>31 public GetCimInstanceCommand()32 : base(parameters, parameterSets)33 {34 DebugHelper.WriteLogEx();35 }36 37 #endregion38 39 #region parameters40 41 /// <summary>42 /// <para>43 /// The following is the definition of the input parameter "CimSession".44 /// Identifies the CimSession which is to be used to retrieve the instances.45 /// </para>46 /// </summary>47 [Parameter(48 Mandatory = true,49 ValueFromPipeline = true,50 ParameterSetName = CimBaseCommand.CimInstanceSessionSet)]51 [Parameter(52 Mandatory = true,53 ValueFromPipeline = true,54 ParameterSetName = CimBaseCommand.QuerySessionSet)]55 [Parameter(56 Mandatory = true,57 ValueFromPipeline = true,58 ParameterSetName = CimBaseCommand.ClassNameSessionSet)]59 [Parameter(60 Mandatory = true,61 ValueFromPipeline = true,62 ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]63 [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]64 public CimSession[] CimSession65 {66 get67 {68 return cimSession;69 }70 71 set72 {73 cimSession = value;74 base.SetParameter(value, nameCimSession);75 }76 }77 78 private CimSession[] cimSession;79 80 /// <summary>81 /// <para>82 /// The following is the definition of the input parameter "ClassName".83 /// Define the class name for which the instances are retrieved.84 /// </para>85 /// </summary>86 [Parameter(Mandatory = true,87 Position = 0,88 ValueFromPipelineByPropertyName = true,89 ParameterSetName = CimBaseCommand.ClassNameSessionSet)]90 [Parameter(Mandatory = true,91 Position = 0,92 ValueFromPipelineByPropertyName = true,93 ParameterSetName = CimBaseCommand.ClassNameComputerSet)]94 public string ClassName95 {96 get97 {98 return className;99 }100 101 set102 {103 this.className = value;104 base.SetParameter(value, nameClassName);105 }106 }107 108 private string className;109 110 /// <summary>111 /// <para>112 /// The following is the definition of the input parameter "ResourceUri".113 /// Define the Resource Uri for which the instances are retrieved.114 /// </para>115 /// </summary>116 [Parameter(Mandatory = true,117 ValueFromPipelineByPropertyName = true,118 ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]119 [Parameter(Mandatory = true,120 ValueFromPipelineByPropertyName = true,121 ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]122 [Parameter(123 ParameterSetName = CimBaseCommand.CimInstanceComputerSet)]124 [Parameter(125 ParameterSetName = CimBaseCommand.CimInstanceSessionSet)]126 [Parameter(127 ValueFromPipelineByPropertyName = true,128 ParameterSetName = CimBaseCommand.QueryComputerSet)]129 [Parameter(130 ValueFromPipelineByPropertyName = true,131 ParameterSetName = CimBaseCommand.QuerySessionSet)]132 public Uri ResourceUri133 {134 get135 {136 return resourceUri;137 }138 139 set140 {141 this.resourceUri = value;142 base.SetParameter(value, nameResourceUri);143 }144 }145 146 private Uri resourceUri;147 148 /// <summary>149 /// <para>The following is the definition of the input parameter "ComputerName".150 /// Provides the name of the computer from which to retrieve the instances. The151 /// ComputerName is used to create a temporary CimSession with default parameter152 /// values, which is then used to retrieve the instances.153 /// </para>154 /// <para>155 /// If no ComputerName is specified the default value is "localhost"156 /// </para>157 /// </summary>158 [Alias(AliasCN, AliasServerName)]159 [Parameter(160 ValueFromPipelineByPropertyName = true,161 ParameterSetName = CimBaseCommand.ClassNameComputerSet)]162 [Parameter(163 ValueFromPipelineByPropertyName = true,164 ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]165 [Parameter(166 ValueFromPipelineByPropertyName = true,167 ParameterSetName = CimBaseCommand.QueryComputerSet)]168 [Parameter(169 ParameterSetName = CimBaseCommand.CimInstanceComputerSet)]170 [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]171 public string[] ComputerName172 {173 get174 {175 return computerName;176 }177 178 set179 {180 computerName = value;181 base.SetParameter(value, nameComputerName);182 }183 }184 185 private string[] computerName;186 187 /// <summary>188 /// <para>189 /// The following is the definition of the input parameter "KeyOnly".190 /// Indicates that only key properties of the retrieved instances should be191 /// returned to the client.192 /// </para>193 /// </summary>194 [Parameter(ParameterSetName = CimBaseCommand.ClassNameComputerSet)]195 [Parameter(ParameterSetName = CimBaseCommand.ClassNameSessionSet)]196 [Parameter(ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]197 [Parameter(ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]198 public SwitchParameter KeyOnly199 {200 get201 {202 return keyOnly;203 }204 205 set206 {207 keyOnly = value;208 base.SetParameter(value, nameKeyOnly);209 }210 }211 212 private SwitchParameter keyOnly;213 214 /// <summary>215 /// <para>216 /// The following is the definition of the input parameter "Namespace".217 /// Identifies the Namespace in which the class, indicated by ClassName, is218 /// registered.219 /// </para>220 /// <para>221 /// Default namespace is 'root\cimv2' if this property is not specified.222 /// </para>223 /// </summary>224 [Parameter(ValueFromPipelineByPropertyName = true,225 ParameterSetName = CimBaseCommand.ClassNameComputerSet)]226 [Parameter(ValueFromPipelineByPropertyName = true,227 ParameterSetName = CimBaseCommand.ClassNameSessionSet)]228 [Parameter(ValueFromPipelineByPropertyName = true,229 ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]230 [Parameter(ValueFromPipelineByPropertyName = true,231 ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]232 [Parameter(ValueFromPipelineByPropertyName = true,233 ParameterSetName = CimBaseCommand.QueryComputerSet)]234 [Parameter(ValueFromPipelineByPropertyName = true,235 ParameterSetName = CimBaseCommand.QuerySessionSet)]236 public string Namespace237 {238 get239 {240 return nameSpace;241 }242 243 set244 {245 nameSpace = value;246 base.SetParameter(value, nameNamespace);247 }248 }249 250 private string nameSpace;251 252 /// <summary>253 /// <para>254 /// The following is the definition of the input parameter "OperationTimeoutSec".255 /// Specifies the operation timeout after which the client operation should be256 /// canceled. The default is the CimSession operation timeout. If this parameter257 /// is specified, then this value takes precedence over the CimSession258 /// OperationTimeout.259 /// </para>260 /// </summary>261 [Alias(AliasOT)]262 [Parameter]263 public uint OperationTimeoutSec { get; set; }264 265 /// <summary>266 /// <para>The following is the definition of the input parameter "InputObject".267 /// Provides the <see cref="CimInstance"/> that containing the [Key] properties,268 /// based on the key properties to retrieve the <see cref="CimInstance"/>.269 /// </para>270 /// <para>271 /// User can call New-CimInstance to create the CimInstance with key only272 /// properties, for example:273 /// New-CimInstance -ClassName C -Namespace root\cimv2274 /// -Property @{CreationClassName="CIM_VirtualComputerSystem";Name="VM3358"}275 /// -Keys {"CreationClassName", "Name"} -Local276 /// </para>277 /// </summary>278 [Parameter(279 Mandatory = true,280 Position = 0,281 ValueFromPipeline = true,282 ParameterSetName = CimBaseCommand.CimInstanceComputerSet)]283 [Parameter(284 Mandatory = true,285 Position = 0,286 ValueFromPipeline = true,287 ParameterSetName = CimBaseCommand.CimInstanceSessionSet)]288 [Alias(CimBaseCommand.AliasCimInstance)]289 public CimInstance InputObject290 {291 get292 {293 return CimInstance;294 }295 296 set297 {298 CimInstance = value;299 base.SetParameter(value, nameCimInstance);300 }301 }302 303 /// <summary>304 /// Property for internal usage purpose.305 /// </summary>306 internal CimInstance CimInstance { get; private set; }307 308 /// <summary>309 /// The following is the definition of the input parameter "Query".310 /// Specifies the query string for what instances, and what properties of those311 /// instances, should be retrieve.312 /// </summary>313 [Parameter(Mandatory = true,314 ValueFromPipelineByPropertyName = true,315 ParameterSetName = CimBaseCommand.QueryComputerSet)]316 [Parameter(Mandatory = true,317 ValueFromPipelineByPropertyName = true,318 ParameterSetName = CimBaseCommand.QuerySessionSet)]319 public string Query320 {321 get322 {323 return query;324 }325 326 set327 {328 query = value;329 base.SetParameter(value, nameQuery);330 }331 }332 333 private string query;334 335 /// <summary>336 /// <para>337 /// The following is the definition of the input parameter "QueryDialect".338 /// Specifies the dialect used by the query Engine that interprets the Query339 /// string.340 /// </para>341 /// </summary>342 [Parameter(ValueFromPipelineByPropertyName = true,343 ParameterSetName = CimBaseCommand.QueryComputerSet)]344 [Parameter(ValueFromPipelineByPropertyName = true,345 ParameterSetName = CimBaseCommand.QuerySessionSet)]346 [Parameter(ValueFromPipelineByPropertyName = true,347 ParameterSetName = CimBaseCommand.ClassNameSessionSet)]348 [Parameter(ValueFromPipelineByPropertyName = true,349 ParameterSetName = CimBaseCommand.ClassNameComputerSet)]350 351 public string QueryDialect352 {353 get354 {355 return queryDialect;356 }357 358 set359 {360 queryDialect = value;361 base.SetParameter(value, nameQueryDialect);362 }363 }364 365 private string queryDialect;366 367 /// <summary>368 /// <para>369 /// The following is the definition of the input parameter "Shallow".370 /// If the switch is set to True, only instance of the class identified by371 /// Namespace + ClassName will be returned. If the switch is not set, instances372 /// of the above class and of all of its descendents will be returned (the373 /// enumeration will cascade the class inheritance hierarchy).374 /// </para>375 /// </summary>376 [Parameter(ParameterSetName = CimBaseCommand.ClassNameComputerSet)]377 [Parameter(ParameterSetName = CimBaseCommand.ClassNameSessionSet)]378 [Parameter(ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]379 [Parameter(ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]380 [Parameter(ParameterSetName = CimBaseCommand.QueryComputerSet)]381 [Parameter(ParameterSetName = CimBaseCommand.QuerySessionSet)]382 public SwitchParameter Shallow383 {384 get385 {386 return shallow;387 }388 389 set390 {391 shallow = value;392 base.SetParameter(value, nameShallow);393 }394 }395 396 private SwitchParameter shallow;397 398 /// <summary>399 /// <para>400 /// The following is the definition of the input parameter "Filter".401 /// Specifies the where clause of the query.402 /// </para>403 /// </summary>404 [Parameter(ValueFromPipelineByPropertyName = true,405 ParameterSetName = CimBaseCommand.ClassNameSessionSet)]406 [Parameter(ValueFromPipelineByPropertyName = true,407 ParameterSetName = CimBaseCommand.ClassNameComputerSet)]408 [Parameter(ValueFromPipelineByPropertyName = true,409 ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]410 [Parameter(ValueFromPipelineByPropertyName = true,411 ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]412 public string Filter413 {414 get415 {416 return filter;417 }418 419 set420 {421 filter = value;422 base.SetParameter(value, nameFilter);423 }424 }425 426 private string filter;427 428 /// <summary>429 /// <para>430 /// The following is the definition of the input parameter "Property".431 /// Specifies the selected properties of result instances.432 /// </para>433 /// </summary>434 [Parameter(ValueFromPipelineByPropertyName = true,435 ParameterSetName = CimBaseCommand.ClassNameSessionSet)]436 [Parameter(ValueFromPipelineByPropertyName = true,437 ParameterSetName = CimBaseCommand.ClassNameComputerSet)]438 [Parameter(ValueFromPipelineByPropertyName = true,439 ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]440 [Parameter(ValueFromPipelineByPropertyName = true,441 ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]442 [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]443 [Alias("SelectProperties")]444 public string[] Property445 {446 get447 {448 return SelectProperties;449 }450 451 set452 {453 SelectProperties = value;454 base.SetParameter(value, nameSelectProperties);455 }456 }457 /// <summary>458 /// Property for internal usage.459 /// </summary>460 internal string[] SelectProperties { get; private set; }461 462 #endregion463 464 #region cmdlet methods465 466 /// <summary>467 /// BeginProcessing method.468 /// </summary>469 protected override void BeginProcessing()470 {471 this.CmdletOperation = new CmdletOperationBase(this);472 this.AtBeginProcess = false;473 }474 475 /// <summary>476 /// ProcessRecord method.477 /// </summary>478 protected override void ProcessRecord()479 {480 base.CheckParameterSet();481 this.CheckArgument();482 CimGetInstance cimGetInstance = this.GetOperationAgent() ?? CreateOperationAgent();483 484 cimGetInstance.GetCimInstance(this);485 cimGetInstance.ProcessActions(this.CmdletOperation);486 }487 488 /// <summary>489 /// EndProcessing method.490 /// </summary>491 protected override void EndProcessing()492 {493 CimGetInstance cimGetInstance = this.GetOperationAgent();494 cimGetInstance?.ProcessRemainActions(this.CmdletOperation);495 }496 497 #endregion498 499 #region helper methods500 501 /// <summary>502 /// <para>503 /// Get <see cref="CimGetInstance"/> object, which is504 /// used to delegate all Get-CimInstance operations, such505 /// as enumerate instances, get instance, query instance.506 /// </para>507 /// </summary>508 private CimGetInstance GetOperationAgent()509 {510 return this.AsyncOperation as CimGetInstance;511 }512 513 /// <summary>514 /// <para>515 /// Create <see cref="CimGetInstance"/> object, which is516 /// used to delegate all Get-CimInstance operations, such517 /// as enumerate instances, get instance, query instance.518 /// </para>519 /// </summary>520 /// <returns></returns>521 private CimGetInstance CreateOperationAgent()522 {523 CimGetInstance cimGetInstance = new();524 this.AsyncOperation = cimGetInstance;525 return cimGetInstance;526 }527 528 /// <summary>529 /// Check argument value.530 /// </summary>531 private void CheckArgument()532 {533 switch (this.ParameterSetName)534 {535 case CimBaseCommand.ClassNameComputerSet:536 case CimBaseCommand.ClassNameSessionSet:537 // validate the classname & property538 this.className = ValidationHelper.ValidateArgumentIsValidName(nameClassName, this.className);539 this.SelectProperties = ValidationHelper.ValidateArgumentIsValidName(nameSelectProperties, this.SelectProperties);540 break;541 default:542 break;543 }544 }545 #endregion546 547 #region private members548 549 #region const string of parameter names550 internal const string nameCimInstance = "InputObject";551 internal const string nameCimSession = "CimSession";552 internal const string nameClassName = "ClassName";553 internal const string nameResourceUri = "ResourceUri";554 internal const string nameComputerName = "ComputerName";555 internal const string nameFilter = "Filter";556 internal const string nameKeyOnly = "KeyOnly";557 internal const string nameNamespace = "Namespace";558 internal const string nameOperationTimeoutSec = "OperationTimeoutSec";559 internal const string nameQuery = "Query";560 internal const string nameQueryDialect = "QueryDialect";561 internal const string nameSelectProperties = "Property";562 internal const string nameShallow = "Shallow";563 #endregion564 565 /// <summary>566 /// Static parameter definition entries.567 /// </summary>568 private static readonly Dictionary<string, HashSet<ParameterDefinitionEntry>> parameters = new()569 {570 {571 nameCimSession, new HashSet<ParameterDefinitionEntry> {572 new ParameterDefinitionEntry(CimBaseCommand.QuerySessionSet, true),573 new ParameterDefinitionEntry(CimBaseCommand.CimInstanceSessionSet, true),574 new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, true),575 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, true),576 }577 },578 {579 nameResourceUri, new HashSet<ParameterDefinitionEntry> {580 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, true),581 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, true),582 new ParameterDefinitionEntry(CimBaseCommand.CimInstanceComputerSet, false),583 new ParameterDefinitionEntry(CimBaseCommand.CimInstanceSessionSet, false),584 new ParameterDefinitionEntry(CimBaseCommand.QueryComputerSet, false),585 new ParameterDefinitionEntry(CimBaseCommand.QuerySessionSet, false),586 }587 },588 {589 nameClassName, new HashSet<ParameterDefinitionEntry> {590 new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, true),591 new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, true),592 }593 },594 {595 nameComputerName, new HashSet<ParameterDefinitionEntry> {596 new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),597 new ParameterDefinitionEntry(CimBaseCommand.QueryComputerSet, false),598 new ParameterDefinitionEntry(CimBaseCommand.CimInstanceComputerSet, false),599 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),600 }601 },602 {603 nameKeyOnly, new HashSet<ParameterDefinitionEntry> {604 new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),605 new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, false),606 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, false),607 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),608 }609 },610 {611 nameNamespace, new HashSet<ParameterDefinitionEntry> {612 new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),613 new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, false),614 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, false),615 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),616 new ParameterDefinitionEntry(CimBaseCommand.QueryComputerSet, false),617 new ParameterDefinitionEntry(CimBaseCommand.QuerySessionSet, false),618 }619 },620 {621 nameCimInstance, new HashSet<ParameterDefinitionEntry> {622 new ParameterDefinitionEntry(CimBaseCommand.CimInstanceComputerSet, true),623 new ParameterDefinitionEntry(CimBaseCommand.CimInstanceSessionSet, true),624 }625 },626 {627 nameQuery, new HashSet<ParameterDefinitionEntry> {628 new ParameterDefinitionEntry(CimBaseCommand.QuerySessionSet, true),629 new ParameterDefinitionEntry(CimBaseCommand.QueryComputerSet, true),630 }631 },632 {633 nameQueryDialect, new HashSet<ParameterDefinitionEntry> {634 new ParameterDefinitionEntry(CimBaseCommand.QuerySessionSet, false),635 new ParameterDefinitionEntry(CimBaseCommand.QueryComputerSet, false),636 new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, false),637 new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),638 }639 },640 {641 nameShallow, new HashSet<ParameterDefinitionEntry> {642 new ParameterDefinitionEntry(CimBaseCommand.QuerySessionSet, false),643 new ParameterDefinitionEntry(CimBaseCommand.QueryComputerSet, false),644 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, false),645 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),646 new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, false),647 new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),648 }649 },650 {651 nameFilter, new HashSet<ParameterDefinitionEntry> {652 new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, false),653 new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),654 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, false),655 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),656 }657 },658 {659 nameSelectProperties, new HashSet<ParameterDefinitionEntry> {660 new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, false),661 new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),662 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, false),663 new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),664 }665 },666 };667 668 /// <summary>669 /// Static parameter set entries.670 /// </summary>671 private static readonly Dictionary<string, ParameterSetEntry> parameterSets = new()672 {673 { CimBaseCommand.CimInstanceComputerSet, new ParameterSetEntry(1) },674 { CimBaseCommand.CimInstanceSessionSet, new ParameterSetEntry(2) },675 { CimBaseCommand.ClassNameComputerSet, new ParameterSetEntry(1, true) },676 { CimBaseCommand.ClassNameSessionSet, new ParameterSetEntry(2) },677 { CimBaseCommand.QueryComputerSet, new ParameterSetEntry(1) },678 { CimBaseCommand.ResourceUriSessionSet, new ParameterSetEntry(2) },679 { CimBaseCommand.ResourceUriComputerSet, new ParameterSetEntry(1) },680 { CimBaseCommand.QuerySessionSet, new ParameterSetEntry(2) }681 };682 #endregion683 }684}685