MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System;5using System.Collections.Generic;6using System.Management.Automation;7 8namespace Microsoft.PowerShell.Cmdletization9{10    /// <summary>11    /// ObjectModelWrapper integrates OM-specific operations into generic cmdletization framework.12    /// For example - CimCmdletAdapter knows how to invoke a static method "Foo" in the CIM OM.13    /// </summary>14    /// <typeparam name="TObjectInstance">Type that represents instances of objects from the wrapped object model</typeparam>15    public abstract class CmdletAdapter<TObjectInstance>16        where TObjectInstance : class17    {18        internal void Initialize(PSCmdlet cmdlet, string className, string classVersion, IDictionary<string, string> privateData)19        {20            ArgumentNullException.ThrowIfNull(cmdlet);21            ArgumentException.ThrowIfNullOrEmpty(className);22 23            // possible and ok to have classVersion==string.Empty24            ArgumentNullException.ThrowIfNull(classVersion);25            ArgumentNullException.ThrowIfNull(privateData);26 27            _cmdlet = cmdlet;28            _className = className;29            _classVersion = classVersion;30            _privateData = privateData;31 32            if (this.Cmdlet is PSScriptCmdlet compiledScript)33            {34                compiledScript.StoppingEvent += delegate { this.StopProcessing(); };35                compiledScript.DisposingEvent +=36                        delegate37                        {38                            var disposable = this as IDisposable;39                            disposable?.Dispose();40                        };41            }42        }43 44        /// <summary>45        /// Class constructor.46        /// </summary>47        /// <param name="cmdlet"></param>48        /// <param name="className"></param>49        /// <param name="classVersion"></param>50        /// <param name="moduleVersion"></param>51        /// <param name="privateData"></param>52        public void Initialize(PSCmdlet cmdlet, string className, string classVersion, Version moduleVersion, IDictionary<string, string> privateData)53        {54            _moduleVersion = moduleVersion;55 56            Initialize(cmdlet, className, classVersion, privateData);57        }58 59        /// <summary>60        /// When overridden in the derived class, creates a query builder for a given object model.61        /// </summary>62        /// <returns>Query builder for a given object model.</returns>63        public virtual QueryBuilder GetQueryBuilder()64        {65            throw new NotImplementedException();66        }67 68        /// <summary>69        /// Queries for object instances in the object model.70        /// </summary>71        /// <param name="query">Query parameters.</param>72        /// <returns>A lazy evaluated collection of object instances.</returns>73        public virtual void ProcessRecord(QueryBuilder query)74        {75            throw new NotImplementedException();76        }77 78        /// <summary>79        /// When overridden in the derived class, performs initialization of cmdlet execution.80        /// Default implementation in the base class just returns.81        /// </summary>82        public virtual void BeginProcessing()83        {84        }85 86        /// <summary>87        /// When overridden in the derived class, performs cleanup after cmdlet execution.88        /// Default implementation in the base class just returns.89        /// </summary>90        public virtual void EndProcessing()91        {92        }93 94        /// <summary>95        /// When overridden in the derived class, interrupts currently96        /// running code within the <see cref="CmdletAdapter&lt;TObjectInstance&gt;"/>.97        /// Default implementation in the base class just returns.98        /// </summary>99        /// <remarks>100        /// The PowerShell engine will call this method on a separate thread101        /// from the pipeline thread where BeginProcessing, EndProcessing102        /// and other methods are normally being executed.103        /// </remarks>104        public virtual void StopProcessing()105        {106        }107 108        /// <summary>109        /// Invokes an instance method in the object model.110        /// </summary>111        /// <param name="objectInstance">The object on which to invoke the method.</param>112        /// <param name="methodInvocationInfo">Method invocation details.</param>113        /// <param name="passThru"><see langword="true"/> if successful method invocations should emit downstream the <paramref name="objectInstance"/> being operated on.</param>114        public virtual void ProcessRecord(TObjectInstance objectInstance, MethodInvocationInfo methodInvocationInfo, bool passThru)115        {116            throw new NotImplementedException();117        }118 119        /// <summary>120        /// Combines <see cref="ProcessRecord(QueryBuilder)"/> and <see cref="ProcessRecord(TObjectInstance,Microsoft.PowerShell.Cmdletization.MethodInvocationInfo,bool)"/>.121        /// </summary>122        /// <param name="query">Query parameters.</param>123        /// <param name="methodInvocationInfo">Method invocation details.</param>124        /// <param name="passThru"><see langword="true"/> if successful method invocations should emit downstream the object instance being operated on.</param>125        public virtual void ProcessRecord(QueryBuilder query, MethodInvocationInfo methodInvocationInfo, bool passThru)126        {127            throw new NotImplementedException();128        }129 130        /// <summary>131        /// Invokes a static method in the object model.132        /// </summary>133        /// <param name="methodInvocationInfo">Method invocation details.</param>134        public virtual void ProcessRecord(135            MethodInvocationInfo methodInvocationInfo)136        {137            throw new NotImplementedException();138        }139 140        /// <summary>141        /// Cmdlet that this ObjectModelWrapper is associated with.142        /// </summary>143        public PSCmdlet Cmdlet144        {145            get146            {147                return _cmdlet;148            }149        }150 151        private PSCmdlet _cmdlet;152 153        /// <summary>154        /// Name of the class (from the object model handled by this ObjectModelWrapper) that is wrapped by the currently executing cmdlet.155        /// </summary>156        public string ClassName157        {158            get159            {160                return _className;161            }162        }163 164        private string _className;165 166        /// <summary>167        /// Name of the class (from the object model handled by this ObjectModelWrapper) that is wrapped by the currently executing cmdlet.168        /// This value can be <see langword="null"/> (i.e. when ClassVersion attribute is omitted in the ps1xml)169        /// </summary>170        public string ClassVersion171        {172            get173            {174                return _classVersion;175            }176        }177 178        private string _classVersion;179 180        /// <summary>181        /// Module version.182        /// </summary>183        public Version ModuleVersion184        {185            get186            {187                return _moduleVersion;188            }189        }190 191        private Version _moduleVersion;192 193        /// <summary>194        /// Private data from Cmdlet Definition XML (from &lt;ObjectModelWrapperPrivateData&gt; element)195        /// </summary>196        public IDictionary<string, string> PrivateData197        {198            get199            {200                return _privateData;201            }202        }203 204        private IDictionary<string, string> _privateData;205    }206}207