MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4#region Using directives5using System;6using System.Collections;7using System.Collections.Generic;8using System.Diagnostics.CodeAnalysis;9using System.Management.Automation;10#endregion11 12namespace Microsoft.Management.Infrastructure.CimCmdlets13{14    /// <summary>15    /// <para>16    /// This Cmdlet creates an instance of a CIM class based on the class17    /// definition, which is an instance factory18    /// </para>19    /// <para>20    /// If -ClientOnly is not specified, New-CimInstance will create a new instance21    /// on the server, otherwise just create client in-memory instance22    /// </para>23    /// </summary>24    [Alias("ncim")]25    [Cmdlet(VerbsCommon.New, "CimInstance", DefaultParameterSetName = CimBaseCommand.ClassNameComputerSet, SupportsShouldProcess = true, HelpUri = "https://go.microsoft.com/fwlink/?LinkId=227963")]26    [OutputType(typeof(CimInstance))]27    public class NewCimInstanceCommand : CimBaseCommand28    {29        #region constructor30 31        /// <summary>32        /// Initializes a new instance of the <see cref="NewCimInstanceCommand"/> class.33        /// </summary>34        public NewCimInstanceCommand()35            : base(parameters, parameterSets)36        {37            DebugHelper.WriteLogEx();38        }39 40        #endregion41 42        #region parameters43 44        /// <summary>45        /// The following is the definition of the input parameter "ClassName".46        /// Name of the Class to use to create Instance.47        /// </summary>48        [Parameter(49            Mandatory = true,50            Position = 0,51            ValueFromPipelineByPropertyName = true,52            ParameterSetName = CimBaseCommand.ClassNameSessionSet)]53        [Parameter(54            Mandatory = true,55            Position = 0,56            ValueFromPipelineByPropertyName = true,57            ParameterSetName = CimBaseCommand.ClassNameComputerSet)]58        public string ClassName59        {60            get61            {62                return className;63            }64 65            set66            {67                className = value;68                base.SetParameter(value, nameClassName);69            }70        }71 72        private string className;73 74        /// <summary>75        /// <para>76        /// The following is the definition of the input parameter "ResourceUri".77        /// Define the Resource Uri for which the instances are retrieved.78        /// </para>79        /// </summary>80        [Parameter(Mandatory = true,81                   ValueFromPipelineByPropertyName = true,82                   ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]83        [Parameter(Mandatory = true,84                   ValueFromPipelineByPropertyName = true,85                   ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]86        public Uri ResourceUri87        {88            get89            {90                return resourceUri;91            }92 93            set94            {95                this.resourceUri = value;96                base.SetParameter(value, nameResourceUri);97            }98        }99 100        private Uri resourceUri;101 102        /// <summary>103        /// <para>104        /// The following is the definition of the input parameter "Key".105        /// Enables the user to specify list of key property name.106        /// </para>107        /// <para>108        /// Example: -Key {"K1", "K2"}109        /// </para>110        /// </summary>111        [Parameter(112            ValueFromPipelineByPropertyName = true,113            ParameterSetName = CimBaseCommand.ClassNameSessionSet)]114        [Parameter(115            ValueFromPipelineByPropertyName = true,116            ParameterSetName = CimBaseCommand.ClassNameComputerSet)]117        [Parameter(118            ValueFromPipelineByPropertyName = true,119            ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]120        [Parameter(121            ValueFromPipelineByPropertyName = true,122            ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]123        [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]124        public string[] Key125        {126            get127            {128                return key;129            }130 131            set132            {133                key = value;134                base.SetParameter(value, nameKey);135            }136        }137 138        private string[] key;139 140        /// <summary>141        /// The following is the definition of the input parameter "CimClass".142        /// The CimClass is used to create Instance.143        /// </summary>144        [Parameter(145            Mandatory = true,146            Position = 0,147            ValueFromPipeline = true,148            ParameterSetName = CimClassSessionSet)]149        [Parameter(150            Mandatory = true,151            Position = 0,152            ValueFromPipeline = true,153            ParameterSetName = CimClassComputerSet)]154        public CimClass CimClass155        {156            get157            {158                return cimClass;159            }160 161            set162            {163                cimClass = value;164                base.SetParameter(value, nameCimClass);165            }166        }167 168        private CimClass cimClass;169 170        /// <summary>171        /// <para>172        /// The following is the definition of the input parameter "Property".173        /// Enables the user to specify instances with specific property values.174        /// </para>175        /// <para>176        /// Example: -Property @{P1="Value1";P2="Value2"}177        /// </para>178        /// </summary>179        [Parameter(180            Position = 1,181            ValueFromPipelineByPropertyName = true)]182        [SuppressMessage("Microsoft.Usage", "CA2227:CollectionPropertiesShouldBeReadOnly")]183        [Alias("Arguments")]184        public IDictionary Property { get; set; }185 186        /// <summary>187        /// The following is the definition of the input parameter "Namespace".188        /// Namespace used to look for the classes under to store the instances.189        /// Default namespace is 'root\cimv2'190        /// </summary>191        [Parameter(192            ValueFromPipelineByPropertyName = true,193            ParameterSetName = CimBaseCommand.ClassNameSessionSet)]194        [Parameter(195            ValueFromPipelineByPropertyName = true,196            ParameterSetName = CimBaseCommand.ClassNameComputerSet)]197        [Parameter(198            ValueFromPipelineByPropertyName = true,199            ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]200        [Parameter(201            ValueFromPipelineByPropertyName = true,202            ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]203        public string Namespace204        {205            get206            {207                return nameSpace;208            }209 210            set211            {212                nameSpace = value;213                base.SetParameter(value, nameNamespace);214            }215        }216 217        private string nameSpace;218 219        /// <summary>220        /// The following is the definition of the input parameter "OperationTimeoutSec".221        /// Operation Timeout of the cmdlet in seconds. Overrides the value in the Cim222        /// Session.223        /// </summary>224        [Alias(AliasOT)]225        [Parameter]226        public uint OperationTimeoutSec { get; set; }227 228        /// <summary>229        /// <para>230        /// The following is the definition of the input parameter "CimSession".231        /// Identifies the CimSession which is to be used to create the instances.232        /// </para>233        /// </summary>234        [Parameter(235            Mandatory = true,236            ValueFromPipeline = true,237            ParameterSetName = CimBaseCommand.ClassNameSessionSet)]238        [Parameter(239            Mandatory = true,240            ValueFromPipeline = true,241            ParameterSetName = CimBaseCommand.ResourceUriSessionSet)]242        [Parameter(243            Mandatory = true,244            ValueFromPipeline = true,245            ParameterSetName = CimClassSessionSet)]246        [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]247        public CimSession[] CimSession248        {249            get250            {251                return cimSession;252            }253 254            set255            {256                cimSession = value;257                base.SetParameter(value, nameCimSession);258            }259        }260 261        private CimSession[] cimSession;262 263        /// <summary>264        /// <para>The following is the definition of the input parameter "ComputerName".265        /// Provides the name of the computer from which to create the instances.266        /// </para>267        /// <para>268        /// If no ComputerName is specified the default value is "localhost"269        /// </para>270        /// </summary>271        [Alias(AliasCN, AliasServerName)]272        [Parameter(273            ValueFromPipelineByPropertyName = true,274            ParameterSetName = CimBaseCommand.ClassNameComputerSet)]275        [Parameter(276            ValueFromPipelineByPropertyName = true,277            ParameterSetName = CimBaseCommand.ResourceUriComputerSet)]278        [Parameter(279            ValueFromPipelineByPropertyName = true,280            ParameterSetName = CimClassComputerSet)]281        [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]282        public string[] ComputerName283        {284            get285            {286                return computerName;287            }288 289            set290            {291                computerName = value;292                base.SetParameter(value, nameComputerName);293            }294        }295 296        private string[] computerName;297 298        /// <summary>299        /// <para>300        /// The following is the definition of the input parameter "ClientOnly".301        /// Indicates to create a client only ciminstance object, NOT on the server.302        /// </para>303        /// </summary>304        [Alias("Local")]305        [Parameter(306            ParameterSetName = CimBaseCommand.ClassNameSessionSet)]307        [Parameter(308            ParameterSetName = CimBaseCommand.ClassNameComputerSet)]309        [Parameter(310            ParameterSetName = CimBaseCommand.CimClassComputerSet)]311        [Parameter(312            ParameterSetName = CimBaseCommand.CimClassSessionSet)]313        public SwitchParameter ClientOnly314        {315            get316            {317                return clientOnly;318            }319 320            set321            {322                clientOnly = value;323                base.SetParameter(value, nameClientOnly);324            }325        }326 327        private SwitchParameter clientOnly;328 329        #endregion330 331        #region cmdlet methods332 333        /// <summary>334        /// BeginProcessing method.335        /// </summary>336        protected override void BeginProcessing()337        {338            this.CmdletOperation = new CmdletOperationBase(this);339            this.AtBeginProcess = false;340        }341 342        /// <summary>343        /// ProcessRecord method.344        /// </summary>345        protected override void ProcessRecord()346        {347            base.CheckParameterSet();348            this.CheckArgument();349            if (this.ClientOnly)350            {351                string conflictParameterName = null;352                if (this.ComputerName != null)353                {354                    conflictParameterName = @"ComputerName";355                }356                else if (this.CimSession != null)357                {358                    conflictParameterName = @"CimSession";359                }360 361                if (conflictParameterName != null)362                {363                    ThrowConflictParameterWasSet(@"New-CimInstance", conflictParameterName, @"ClientOnly");364                    return;365                }366            }367 368            CimNewCimInstance cimNewCimInstance = this.GetOperationAgent() ?? CreateOperationAgent();369 370            cimNewCimInstance.NewCimInstance(this);371            cimNewCimInstance.ProcessActions(this.CmdletOperation);372        }373 374        /// <summary>375        /// EndProcessing method.376        /// </summary>377        protected override void EndProcessing()378        {379            CimNewCimInstance cimNewCimInstance = this.GetOperationAgent();380            cimNewCimInstance?.ProcessRemainActions(this.CmdletOperation);381        }382 383        #endregion384 385        #region helper methods386 387        /// <summary>388        /// <para>389        /// Get <see cref="CimNewCimInstance"/> object, which is390        /// used to delegate all New-CimInstance operations.391        /// </para>392        /// </summary>393        private CimNewCimInstance GetOperationAgent()394        {395            return this.AsyncOperation as CimNewCimInstance;396        }397 398        /// <summary>399        /// <para>400        /// Create <see cref="CimNewCimInstance"/> object, which is401        /// used to delegate all New-CimInstance operations.402        /// </para>403        /// </summary>404        /// <returns></returns>405        private CimNewCimInstance CreateOperationAgent()406        {407            CimNewCimInstance cimNewCimInstance = new();408            this.AsyncOperation = cimNewCimInstance;409            return cimNewCimInstance;410        }411 412        /// <summary>413        /// Check argument value.414        /// </summary>415        private void CheckArgument()416        {417            switch (this.ParameterSetName)418            {419                case CimBaseCommand.ClassNameComputerSet:420                case CimBaseCommand.ClassNameSessionSet:421                    // validate the classname422                    this.className = ValidationHelper.ValidateArgumentIsValidName(nameClassName, this.className);423                    break;424                default:425                    break;426            }427        }428        #endregion429 430        #region private members431 432        #region const string of parameter names433        internal const string nameClassName = "ClassName";434        internal const string nameResourceUri = "ResourceUri";435        internal const string nameKey = "Key";436        internal const string nameCimClass = "CimClass";437        internal const string nameProperty = "Property";438        internal const string nameNamespace = "Namespace";439        internal const string nameCimSession = "CimSession";440        internal const string nameComputerName = "ComputerName";441        internal const string nameClientOnly = "ClientOnly";442        #endregion443 444        /// <summary>445        /// Static parameter definition entries.446        /// </summary>447        private static readonly Dictionary<string, HashSet<ParameterDefinitionEntry>> parameters = new()448        {449            {450                nameClassName, new HashSet<ParameterDefinitionEntry> {451                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, true),452                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, true),453                                 }454            },455            {456                nameResourceUri, new HashSet<ParameterDefinitionEntry> {457                                    new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, true),458                                    new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, true),459                                 }460            },461            {462                nameKey, new HashSet<ParameterDefinitionEntry> {463                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, false),464                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),465                                    new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),466                                    new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, false),467                                 }468            },469            {470                nameCimClass, new HashSet<ParameterDefinitionEntry> {471                                    new ParameterDefinitionEntry(CimBaseCommand.CimClassSessionSet, true),472                                    new ParameterDefinitionEntry(CimBaseCommand.CimClassComputerSet, true),473                                 }474            },475            {476                nameNamespace, new HashSet<ParameterDefinitionEntry> {477                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, false),478                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),479                                    new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),480                                    new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, false),481                                 }482            },483            {484                nameCimSession, new HashSet<ParameterDefinitionEntry> {485                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, true),486                                    new ParameterDefinitionEntry(CimBaseCommand.ResourceUriSessionSet, true),487                                    new ParameterDefinitionEntry(CimBaseCommand.CimClassSessionSet, true),488                                 }489            },490            {491                nameComputerName, new HashSet<ParameterDefinitionEntry> {492                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, false),493                                    new ParameterDefinitionEntry(CimBaseCommand.ResourceUriComputerSet, false),494                                    new ParameterDefinitionEntry(CimBaseCommand.CimClassComputerSet, false),495                                 }496            },497            {498                nameClientOnly, new HashSet<ParameterDefinitionEntry> {499                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameSessionSet, true),500                                    new ParameterDefinitionEntry(CimBaseCommand.ClassNameComputerSet, true),501                                    new ParameterDefinitionEntry(CimBaseCommand.CimClassSessionSet, true),502                                    new ParameterDefinitionEntry(CimBaseCommand.CimClassComputerSet, true),503                                 }504            },505        };506 507        /// <summary>508        /// Static parameter set entries.509        /// </summary>510        private static readonly Dictionary<string, ParameterSetEntry> parameterSets = new()511        {512            {   CimBaseCommand.ClassNameSessionSet, new ParameterSetEntry(2)     },513            {   CimBaseCommand.ClassNameComputerSet, new ParameterSetEntry(1, true)     },514            {   CimBaseCommand.CimClassSessionSet, new ParameterSetEntry(2)     },515            {   CimBaseCommand.CimClassComputerSet, new ParameterSetEntry(1)     },516            {   CimBaseCommand.ResourceUriSessionSet, new ParameterSetEntry(2)     },517            {   CimBaseCommand.ResourceUriComputerSet, new ParameterSetEntry(1)     },518        };519        #endregion520    }521}522