MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using Dbg = System.Management.Automation;5 6namespace System.Management.Automation7{8    /// <summary>9    /// Exposes the APIs to manipulate variables in the Runspace.10    /// </summary>11    public sealed class PSVariableIntrinsics12    {13        #region Constructors14 15        /// <summary>16        /// Hide the default constructor since we always require an instance of SessionState.17        /// </summary>18        private PSVariableIntrinsics()19        {20            Dbg.Diagnostics.Assert(21                false,22                "This constructor should never be called. Only the constructor that takes an instance of SessionState should be called.");23        }24 25        /// <summary>26        /// Constructs a facade for the specified session.27        /// </summary>28        /// <param name="sessionState">29        /// The session for which the facade wraps.30        /// </param>31        /// <exception cref="ArgumentNullException">32        /// If <paramref name="sessionState"/> is null.33        /// </exception>34        internal PSVariableIntrinsics(SessionStateInternal sessionState)35        {36            if (sessionState == null)37            {38                throw PSTraceSource.NewArgumentException(nameof(sessionState));39            }40 41            _sessionState = sessionState;42        }43 44        #endregion Constructors45 46        #region Public methods47 48        /// <summary>49        /// Gets the specified variable from session state.50        /// </summary>51        /// <param name="name">52        /// The name of the variable to get. The name can contain drive and/or53        /// scope specifiers like "ENV:path" or "global:myvar".54        /// </param>55        /// <returns>56        /// The specified variable.57        /// </returns>58        /// <exception cref="ArgumentNullException">59        /// If <paramref name="name"/> is null.60        /// </exception>61        public PSVariable Get(string name)62        {63            Dbg.Diagnostics.Assert(64                _sessionState != null,65                "The only constructor for this class should always set the sessionState field");66 67            // Parameter validation is done in the session state object68 69            // Null is returned whenever the requested variable is string.Empty.70            // As per Powershell V1 implementation:71            // 1. If the requested variable exists in the session scope, the variable value is returned.72            // 2. If the requested variable is not null and does not exist in the session scope, then a null value is returned to the pipeline.73            // 3. If the requested variable is null then an NewArgumentNullException is thrown.74            // PowerShell V3 has the similar experience.75            if (name != null && name.Equals(string.Empty))76            {77                return null;78            }79 80            return _sessionState.GetVariable(name);81        }82 83        /// <summary>84        /// Gets the specified variable from session state in the specified scope.85        /// If the variable doesn't exist in the specified scope no additional lookup86        /// will be done.87        /// </summary>88        /// <param name="name">89        /// The name of the variable to get. The name can contain drive and/or90        /// scope specifiers like "ENV:path" or "global:myvar".91        /// </param>92        /// <param name="scope">93        /// The ID of the scope to do the lookup in.94        /// </param>95        /// <returns>96        /// The specified variable.97        /// </returns>98        /// <exception cref="ArgumentNullException">99        /// If <paramref name="name"/> is null.100        /// </exception>101        /// <exception cref="ArgumentException">102        /// If <paramref name="scope"/> is less than zero, or not103        /// a number and not "script", "global", "local", or "private"104        /// </exception>105        /// <exception cref="ArgumentOutOfRangeException">106        /// If <paramref name="scopeID"/> is less than zero or greater than the number of currently107        /// active scopes.108        /// </exception>109        internal PSVariable GetAtScope(string name, string scope)110        {111            Dbg.Diagnostics.Assert(112                _sessionState != null,113                "The only constructor for this class should always set the sessionState field");114 115            // Parameter validation is done in the session state object116 117            return _sessionState.GetVariableAtScope(name, scope);118        }119 120        /// <summary>121        /// Gets the specified variable value from session state.122        /// </summary>123        /// <param name="name">124        /// The name of the variable to get. The name can contain drive and/or125        /// scope specifiers like "ENV:path" or "global:myvar".126        /// </param>127        /// <returns>128        /// The value of the specified variable.129        /// </returns>130        /// <exception cref="ArgumentNullException">131        /// If <paramref name="name"/> is null.132        /// </exception>133        /// <exception cref="ProviderNotFoundException">134        /// If the <paramref name="name"/> refers to a provider that could not be found.135        /// </exception>136        /// <exception cref="DriveNotFoundException">137        /// If the <paramref name="name"/> refers to a drive that could not be found.138        /// </exception>139        /// <exception cref="NotSupportedException">140        /// If the provider that the <paramref name="name"/> refers to does141        /// not support this operation.142        /// </exception>143        /// <exception cref="ProviderInvocationException">144        /// If the provider threw an exception.145        /// </exception>146        public object GetValue(string name)147        {148            Dbg.Diagnostics.Assert(149                _sessionState != null,150                "The only constructor for this class should always set the sessionState field");151 152            // Parameter validation is done in the session state object153 154            return _sessionState.GetVariableValue(name);155        }156 157        /// <summary>158        /// Gets the specified variable from session state. If the variable159        /// is not found the default value is returned.160        /// </summary>161        /// <param name="name">162        /// The name of the variable to get. The name can contain drive and/or163        /// scope specifiers like "ENV:path" or "global:myvar".164        /// </param>165        /// <param name="defaultValue">166        /// The default value returned if the variable could not be found.167        /// </param>168        /// <returns>169        /// The value of the specified variable or the default value if the variable170        /// is not found.171        /// </returns>172        /// <exception cref="ArgumentNullException">173        /// If <paramref name="name"/> is null.174        /// </exception>175        /// <exception cref="ProviderNotFoundException">176        /// If the <paramref name="name"/> refers to a provider that could not be found.177        /// </exception>178        /// <exception cref="DriveNotFoundException">179        /// If the <paramref name="name"/> refers to a drive that could not be found.180        /// </exception>181        /// <exception cref="NotSupportedException">182        /// If the provider that the <paramref name="name"/> refers to does183        /// not support this operation.184        /// </exception>185        /// <exception cref="ProviderInvocationException">186        /// If the provider threw an exception.187        /// </exception>188        public object GetValue(string name, object defaultValue)189        {190            Dbg.Diagnostics.Assert(191                _sessionState != null,192                "The only constructor for this class should always set the sessionState field");193 194            // Parameter validation is done in the session state object195 196            return _sessionState.GetVariableValue(name) ?? defaultValue;197        }198 199        /// <summary>200        /// Gets the specified variable from session state in the specified scope.201        /// If the variable doesn't exist in the specified scope no additional lookup202        /// will be done.203        /// </summary>204        /// <param name="name">205        /// The name of the variable to get. The name can contain drive and/or206        /// scope specifiers like "ENV:path" or "global:myvar".207        /// </param>208        /// <param name="scope">209        /// The ID of the scope to do the lookup in.210        /// </param>211        /// <returns>212        /// The value of the specified variable.213        /// </returns>214        /// <exception cref="ArgumentNullException">215        /// If <paramref name="name"/> is null.216        /// </exception>217        /// <exception cref="ArgumentException">218        /// If <paramref name="scope"/> is less than zero, or not219        /// a number and not "script", "global", "local", or "private"220        /// </exception>221        /// <exception cref="ArgumentOutOfRangeException">222        /// If <paramref name="scopeID"/> is less than zero or greater than the number of currently223        /// active scopes.224        /// </exception>225        /// <exception cref="ProviderNotFoundException">226        /// If the <paramref name="name"/> refers to a provider that could not be found.227        /// </exception>228        /// <exception cref="DriveNotFoundException">229        /// If the <paramref name="name"/> refers to a drive that could not be found.230        /// </exception>231        /// <exception cref="NotSupportedException">232        /// If the provider that the <paramref name="name"/> refers to does233        /// not support this operation.234        /// </exception>235        /// <exception cref="ProviderInvocationException">236        /// If the provider threw an exception.237        /// </exception>238        internal object GetValueAtScope(string name, string scope)239        {240            Dbg.Diagnostics.Assert(241                _sessionState != null,242                "The only constructor for this class should always set the sessionState field");243 244            // Parameter validation is done in the session state object245 246            return _sessionState.GetVariableValueAtScope(name, scope);247        }248 249        /// <summary>250        /// Sets the variable to the specified value.251        /// </summary>252        /// <param name="name">253        /// The name of the variable to be set. The name can contain drive and/or254        /// scope specifiers like "ENV:path" or "global:myvar".255        /// </param>256        /// <param name="value">257        /// The value to set the variable to.258        /// </param>259        /// <exception cref="ArgumentNullException">260        /// If <paramref name="name"/> is null.261        /// </exception>262        /// <exception cref="SessionStateUnauthorizedAccessException">263        /// If the variable is read-only or constant.264        /// </exception>265        /// <exception cref="ProviderNotFoundException">266        /// If the <paramref name="name"/> refers to a provider that could not be found.267        /// </exception>268        /// <exception cref="DriveNotFoundException">269        /// If the <paramref name="name"/> refers to a drive that could not be found.270        /// </exception>271        /// <exception cref="NotSupportedException">272        /// If the provider that the <paramref name="name"/> refers to does273        /// not support this operation.274        /// </exception>275        /// <exception cref="ProviderInvocationException">276        /// If the provider threw an exception.277        /// </exception>278        public void Set(string name, object value)279        {280            Dbg.Diagnostics.Assert(281                _sessionState != null,282                "The only constructor for this class should always set the sessionState field");283 284            // Parameter validation is done in the session state object285 286            _sessionState.SetVariableValue(name, value, CommandOrigin.Internal);287        }288 289        /// <summary>290        /// Sets the variable.291        /// </summary>292        /// <param name="variable">293        /// The variable to set294        /// </param>295        /// <exception cref="ArgumentNullException">296        /// If <paramref name="variable"/> is null.297        /// </exception>298        /// <exception cref="SessionStateUnauthorizedAccessException">299        /// If the variable is read-only or constant.300        /// </exception>301        public void Set(PSVariable variable)302        {303            Dbg.Diagnostics.Assert(304                _sessionState != null,305                "The only constructor for this class should always set the sessionState field");306 307            // Parameter validation is done in the session state object308 309            _sessionState.SetVariable(variable, false, CommandOrigin.Internal);310        }311 312        /// <summary>313        /// Removes the specified variable from session state.314        /// </summary>315        /// <param name="name">316        /// The name of the variable to be removed. The name can contain drive and/or317        /// scope specifiers like "ENV:path" or "global:myvar".318        /// </param>319        /// <exception cref="ArgumentNullException">320        /// If <paramref name="name"/> is null.321        /// </exception>322        /// <exception cref="SessionStateUnauthorizedAccessException">323        /// if the variable is constant.324        /// </exception>325        /// <exception cref="ProviderNotFoundException">326        /// If the <paramref name="name"/> refers to a provider that could not be found.327        /// </exception>328        /// <exception cref="DriveNotFoundException">329        /// If the <paramref name="name"/> refers to a drive that could not be found.330        /// </exception>331        /// <exception cref="NotSupportedException">332        /// If the provider that the <paramref name="name"/> refers to does333        /// not support this operation.334        /// </exception>335        /// <exception cref="ProviderInvocationException">336        /// If the provider threw an exception.337        /// </exception>338        public void Remove(string name)339        {340            Dbg.Diagnostics.Assert(341                _sessionState != null,342                "The only constructor for this class should always set the sessionState field");343 344            // Parameter validation is done in the session state object345 346            _sessionState.RemoveVariable(name);347        }348 349        /// <summary>350        /// Removes the specified variable from session state.351        /// </summary>352        /// <param name="variable">353        /// The variable to be removed. It is removed based on the name of the variable.354        /// </param>355        /// <exception cref="ArgumentNullException">356        /// If <paramref name="variable"/> is null.357        /// </exception>358        /// <exception cref="SessionStateUnauthorizedAccessException">359        /// if the variable is constant.360        /// </exception>361        public void Remove(PSVariable variable)362        {363            Dbg.Diagnostics.Assert(364                _sessionState != null,365                "The only constructor for this class should always set the sessionState field");366 367            // Parameter validation is done in the session state object368 369            _sessionState.RemoveVariable(variable);370        }371 372        /// <summary>373        /// Removes the specified variable from the specified scope.374        /// </summary>375        /// <param name="name">376        /// The name of the variable to remove.377        /// </param>378        /// <param name="scope">379        /// The ID of the scope to do the lookup in. The ID is a zero based index380        /// of the scope tree with the current scope being zero, its parent scope381        /// being 1 and so on.382        /// </param>383        /// <exception cref="ArgumentNullException">384        /// If <paramref name="name"/> is null.385        /// </exception>386        /// <exception cref="ArgumentOutOfRangeException">387        /// If <paramref name="scopeID"/> is less than zero or greater than the number of currently388        /// active scopes.389        /// </exception>390        /// <exception cref="SessionStateUnauthorizedAccessException">391        /// if the variable is constant.392        /// </exception>393        /// <exception cref="ProviderInvocationException">394        /// If <paramref name="name"/> refers to an MSH path (not a variable)395        /// and the provider throws an exception.396        /// </exception>397        internal void RemoveAtScope(string name, string scope)398        {399            Dbg.Diagnostics.Assert(400                _sessionState != null,401                "The only constructor for this class should always set the sessionState field");402 403            // Parameter validation is done in the session state object404 405            _sessionState.RemoveVariableAtScope(name, scope);406        }407 408        /// <summary>409        /// Removes the specified variable from the specified scope.410        /// </summary>411        /// <param name="variable">412        /// The variable to be removed. It is removed based on the name of the variable.413        /// </param>414        /// <param name="scope">415        /// The ID of the scope to do the lookup in. The ID is a zero based index416        /// of the scope tree with the current scope being zero, its parent scope417        /// being 1 and so on.418        /// </param>419        /// <exception cref="ArgumentNullException">420        /// If <paramref name="variable"/> is null.421        /// </exception>422        /// <exception cref="ArgumentOutOfRangeException">423        /// If <paramref name="scopeID"/> is less than zero or greater than the number of currently424        /// active scopes.425        /// </exception>426        /// <exception cref="SessionStateUnauthorizedAccessException">427        /// if the variable is constant.428        /// </exception>429        internal void RemoveAtScope(PSVariable variable, string scope)430        {431            Dbg.Diagnostics.Assert(432                _sessionState != null,433                "The only constructor for this class should always set the sessionState field");434 435            // Parameter validation is done in the session state object436 437            _sessionState.RemoveVariableAtScope(variable, scope);438        }439 440        #endregion Public methods441 442        #region private data443 444        private readonly SessionStateInternal _sessionState;445 446        #endregion private data447    }448}449