MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Collections.ObjectModel;5 6using Dbg = System.Management.Automation;7 8namespace System.Management.Automation9{10    /// <summary>11    /// Exposes the Cmdlet Family Provider's drives to the Cmdlet base class. The methods of this class12    /// get and set provider data in session state.13    /// </summary>14    public sealed class DriveManagementIntrinsics15    {16        #region Constructors17 18        /// <summary>19        /// Hide the default constructor since we always require an instance of SessionState.20        /// </summary>21        private DriveManagementIntrinsics()22        {23            Dbg.Diagnostics.Assert(24                false,25                "This constructor should never be called. Only the constructor that takes an instance of SessionState should be called.");26        }27 28        /// <summary>29        /// Constructs a Drive management facade.30        /// </summary>31        /// <param name="sessionState">32        /// The instance of session state that facade wraps.33        /// </param>34        /// <exception cref="ArgumentNullException">35        /// If <paramref name="sessionState"/> is null.36        /// </exception>37        internal DriveManagementIntrinsics(SessionStateInternal sessionState)38        {39            if (sessionState == null)40            {41                throw PSTraceSource.NewArgumentNullException(nameof(sessionState));42            }43 44            _sessionState = sessionState;45        }46 47        #endregion Constructors48 49        #region Public methods50 51        /// <summary>52        /// Gets the drive information for the current working drive.53        /// </summary>54        /// <remarks>55        /// This property is readonly. To set the current drive use the56        /// SetLocation method.57        /// </remarks>58        public PSDriveInfo Current59        {60            get61            {62                Dbg.Diagnostics.Assert(63                    _sessionState != null,64                    "The only constructor for this class should always set the sessionState field");65 66                return _sessionState.CurrentDrive;67            }68        }69 70        #region New71 72        /// <summary>73        /// Creates a new PSDrive in session state.74        /// </summary>75        /// <param name="drive">76        /// The drive to be created.77        /// </param>78        /// <param name="scope">79        /// The ID of the scope to create the drive in. This may be one of the scope80        /// keywords like global or local, or it may be an numeric offset of the scope81        /// generation relative to the current scope.82        /// If the scopeID is null or empty the local scope is used.83        /// </param>84        /// <returns>85        /// The drive that was created.86        /// </returns>87        /// <exception cref="ArgumentNullException">88        /// If <paramref name="drive"/> is null.89        /// </exception>90        /// <exception cref="ArgumentException">91        /// If the drive already exists,92        /// or93        /// If <paramref name="drive"/>.Name contains one or more invalid characters; ~ / \\ . :94        /// </exception>95        /// <exception cref="NotSupportedException">96        /// If the provider is not a DriveCmdletProvider.97        /// </exception>98        /// <exception cref="ProviderNotFoundException">99        /// The provider for the <paramref name="drive"/> could not be found.100        /// </exception>101        /// <exception cref="ProviderInvocationException">102        /// If the provider threw an exception or returned null.103        /// </exception>104        public PSDriveInfo New(PSDriveInfo drive, string scope)105        {106            Dbg.Diagnostics.Assert(107                _sessionState != null,108                "The only constructor for this class should always set the sessionState field");109 110            // Parameter validation is done in the session state object111 112            return _sessionState.NewDrive(drive, scope);113        }114 115        /// <summary>116        /// Creates a new MSH drive in session state.117        /// </summary>118        /// <param name="drive">119        /// The drive to be created.120        /// </param>121        /// <param name="scope">122        /// The ID of the scope to create the drive in. This may be one of the scope123        /// keywords like global or local, or it may be an numeric offset of the scope124        /// generation relative to the current scope.125        /// If the scopeID is null or empty the local scope is used.126        /// </param>127        /// <param name="context">128        /// The context under which this command is running.129        /// </param>130        /// <returns>131        /// Nothing. The drive that is created is written to the context.132        /// </returns>133        /// <exception cref="ArgumentNullException">134        /// If <paramref name="drive"/> or <paramref name="context"/> is null.135        /// </exception>136        /// <exception cref="ArgumentException">137        /// If the drive already exists138        /// or139        /// If <paramref name="drive"/>.Name contains one or more invalid characters; ~ / \\ . :140        /// </exception>141        /// <exception cref="NotSupportedException">142        /// If the provider is not a DriveCmdletProvider.143        /// </exception>144        /// <exception cref="ProviderNotFoundException">145        /// The provider for the <paramref name="drive"/> could not be found.146        /// </exception>147        /// <exception cref="ProviderInvocationException">148        /// If the provider threw an exception or returned null.149        /// </exception>150        internal void New(151            PSDriveInfo drive,152            string scope,153            CmdletProviderContext context)154        {155            Dbg.Diagnostics.Assert(156                _sessionState != null,157                "The only constructor for this class should always set the sessionState field");158 159            // Parameter validation is done in the session state object160 161            _sessionState.NewDrive(drive, scope, context);162        }163 164        /// <summary>165        /// Gets an object that defines the additional parameters for the NewDrive implementation166        /// for a provider.167        /// </summary>168        /// <param name="providerId">169        /// The provider ID for the drive that is being created.170        /// </param>171        /// <param name="context">172        /// The context under which this method is being called.173        /// </param>174        /// <returns>175        /// An object that has properties and fields decorated with176        /// parsing attributes similar to a cmdlet class.177        /// </returns>178        /// <exception cref="NotSupportedException">179        /// If the <paramref name="providerId"/> is not a DriveCmdletProvider.180        /// </exception>181        /// <exception cref="ProviderNotFoundException">182        /// If <paramref name="providerId"/> does not exist.183        /// </exception>184        internal object NewDriveDynamicParameters(185            string providerId,186            CmdletProviderContext context)187        {188            Dbg.Diagnostics.Assert(189                _sessionState != null,190                "The only constructor for this class should always set the sessionState field");191 192            // Parameter validation is done in the session state object193 194            return _sessionState.NewDriveDynamicParameters(providerId, context);195        }196 197        #endregion New198 199        #region Remove200 201        /// <summary>202        /// Removes the specified drive.203        /// </summary>204        /// <param name="driveName">205        /// The name of the drive to be removed.206        /// </param>207        /// <param name="force">208        /// Determines whether drive should be forcefully removed even if there was errors.209        /// </param>210        /// <param name="scope">211        /// The ID of the scope to remove the drive from. This may be one of the scope212        /// keywords like global or local, or it may be an numeric offset of the scope213        /// generation relative to the current scope.214        /// If the scopeID is null or empty the local scope is used.215        /// </param>216        public void Remove(string driveName, bool force, string scope)217        {218            Dbg.Diagnostics.Assert(219                _sessionState != null,220                "The only constructor for this class should always set the sessionState field");221 222            // Parameter validation is done in the session state object223 224            _sessionState.RemoveDrive(driveName, force, scope);225        }226 227        /// <summary>228        /// Removes the specified drive.229        /// </summary>230        /// <param name="driveName">231        /// The name of the drive to be removed.232        /// </param>233        /// <param name="force">234        /// Determines whether drive should be forcefully removed even if there was errors.235        /// </param>236        /// <param name="scope">237        /// The ID of the scope to remove the drive from. This may be one of the scope238        /// keywords like global or local, or it may be an numeric offset of the scope239        /// generation relative to the current scope.240        /// If the scopeID is null or empty the local scope is used.241        /// </param>242        /// <param name="context">243        /// The context under which this command is running.244        /// </param>245        internal void Remove(246            string driveName,247            bool force,248            string scope,249            CmdletProviderContext context)250        {251            Dbg.Diagnostics.Assert(252                _sessionState != null,253                "The only constructor for this class should always set the sessionState field");254 255            // Parameter validation is done in the session state object256 257            _sessionState.RemoveDrive(driveName, force, scope, context);258        }259 260        #endregion Remove261 262        #region Get263 264        /// <summary>265        /// Gets the drive information for the drive specified by name.266        /// </summary>267        /// <param name="driveName">268        /// The name of the drive to get the drive information for.269        /// </param>270        /// <returns>271        /// The drive information that represents the drive of the specified name.272        /// </returns>273        /// <exception cref="ArgumentNullException">274        /// If <paramref name="driveName"/> is null.275        /// </exception>276        /// <exception cref="DriveNotFoundException">277        /// If there is no drive with <paramref name="driveName"/>.278        /// </exception>279        public PSDriveInfo Get(string driveName)280        {281            Dbg.Diagnostics.Assert(282                _sessionState != null,283                "The only constructor for this class should always set the sessionState field");284 285            // Parameter validation is done in the session state object286 287            return _sessionState.GetDrive(driveName);288        }289 290        /// <summary>291        /// Gets the drive information for the drive specified by name.292        /// </summary>293        /// <param name="driveName">294        /// The name of the drive to get the drive information for.295        /// </param>296        /// <param name="scope">297        /// The ID of the scope to get the drive from. This may be one of the scope298        /// keywords like global or local, or it may be an numeric offset of the scope299        /// generation relative to the current scope.300        /// If the scopeID is null or empty the local scope is used.301        /// </param>302        /// <returns>303        /// The drive information that represents the drive of the specified name.304        /// </returns>305        /// <exception cref="ArgumentNullException">306        /// If <paramref name="driveName"/> is null.307        /// </exception>308        /// <exception cref="ArgumentException">309        /// If <paramref name="scope"/> is less than zero, or not310        /// a number and not "script", "global", "local", or "private"311        /// </exception>312        /// <exception cref="ArgumentOutOfRangeException">313        /// If <paramref name="scopeID"/> is less than zero or greater than the number of currently314        /// active scopes.315        /// </exception>316        public PSDriveInfo GetAtScope(string driveName, string scope)317        {318            Dbg.Diagnostics.Assert(319                _sessionState != null,320                "The only constructor for this class should always set the sessionState field");321 322            // Parameter validation is done in the session state object323 324            return _sessionState.GetDrive(driveName, scope);325        }326 327        /// <summary>328        /// Retrieves all the drives in the specified scope.329        /// </summary>330        public Collection<PSDriveInfo> GetAll()331        {332            Dbg.Diagnostics.Assert(333                _sessionState != null,334                "The only constructor for this class should always set the sessionState field");335 336            return _sessionState.Drives(null);337        }338 339        /// <summary>340        /// Retrieves all the drives in the specified scope.341        /// </summary>342        /// <param name="scope">343        /// The scope to retrieve the drives from. If null, the344        /// drives in all the scopes will be returned.345        /// </param>346        /// <exception cref="ArgumentException">347        /// If <paramref name="scope"/> is less than zero, or not348        /// a number and not "script", "global", "local", or "private"349        /// </exception>350        /// <exception cref="ArgumentOutOfRangeException">351        /// If <paramref name="scopeID"/> is less than zero or greater than the number of currently352        /// active scopes.353        /// </exception>354        public Collection<PSDriveInfo> GetAllAtScope(string scope)355        {356            Dbg.Diagnostics.Assert(357                _sessionState != null,358                "The only constructor for this class should always set the sessionState field");359 360            return _sessionState.Drives(scope);361        }362 363        /// <summary>364        /// Gets all the drives for the specified provider.365        /// </summary>366        /// <param name="providerName">367        /// The name of the provider to get the drives for.368        /// </param>369        /// <returns>370        /// All the drives in all the scopes for the given provider.371        /// </returns>372        public Collection<PSDriveInfo> GetAllForProvider(string providerName)373        {374            Dbg.Diagnostics.Assert(375                _sessionState != null,376                "The only constructor for this class should always set the sessionState field");377 378            // Parameter validation is done in the session state object379 380            return _sessionState.GetDrivesForProvider(providerName);381        }382 383        #endregion GetDrive384 385        #endregion Public methods386 387        #region private data388 389        // A private reference to the internal session state of the engine.390        private readonly SessionStateInternal _sessionState;391 392        #endregion private data393    }394}395