MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4namespace System.Management.Automation.Provider5{6    /// <summary>7    /// Declares a class as a Cmdlet provider.8    /// </summary>9    /// <remarks>10    /// The class must be derived from System.Management.Automation.Provider.CmdletProvider to11    /// be recognized by the runspace.12    /// </remarks>13    [AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]14    public sealed class CmdletProviderAttribute : Attribute15    {16        /// <summary>17        /// Constructor for the attribute.18        /// </summary>19        /// <param name="providerName">20        /// The provider name.21        /// </param>22        /// <param name="providerCapabilities">23        /// An enumeration of the capabilities that the provider implements beyond the24        /// default capabilities that are required.25        /// </param>26        /// <exception cref="ArgumentNullException">27        /// If <paramref name="providerName"/> is null or empty.28        /// </exception>29        /// <exception cref="PSArgumentException">30        /// If <paramref name="providerName"/> contains any of the following characters: \ [ ] ? * :31        /// </exception>32        public CmdletProviderAttribute(33            string providerName,34            ProviderCapabilities providerCapabilities)35        {36            // verify parameters37 38            if (string.IsNullOrEmpty(providerName))39            {40                throw PSTraceSource.NewArgumentNullException(nameof(providerName));41            }42 43            if (providerName.IndexOfAny(_illegalCharacters) != -1)44            {45                throw PSTraceSource.NewArgumentException(46                    nameof(providerName),47                    SessionStateStrings.ProviderNameNotValid,48                    providerName);49            }50 51            ProviderName = providerName;52            ProviderCapabilities = providerCapabilities;53        }54 55        private readonly char[] _illegalCharacters = new char[] { ':', '\\', '[', ']', '?', '*' };56 57        /// <summary>58        /// Gets the name of the provider.59        /// </summary>60        public string ProviderName { get; } = string.Empty;61 62        /// <summary>63        /// Gets the flags that represent the capabilities of the provider.64        /// </summary>65        public ProviderCapabilities ProviderCapabilities { get; } = ProviderCapabilities.None;66 67        #region private data68 69        #endregion private data70    }71 72    /// <summary>73    /// This enumeration defines the capabilities that the provider implements.74    /// </summary>75    [Flags]76    public enum ProviderCapabilities77    {78        /// <summary>79        /// The provider does not add any additional capabilities beyond what the80        /// PowerShell engine provides.81        /// </summary>82        None = 0x0,83 84        /// <summary>85        /// <para>86        /// The provider does the inclusion filtering for those commands that take an Include87        /// parameter. The PowerShell engine should not try to do the filtering on behalf of this88        /// provider.89        /// </para>90        /// <para>91        /// The implementer of the provider should make every effort to filter in a way that is consistent92        /// with the PowerShell engine. This option is allowed because in many cases the provider93        /// can be much more efficient at filtering.94        /// </para>95        /// </summary>96        Include = 0x1,97 98        /// <summary>99        /// <para>100        /// The provider does the exclusion filtering for those commands that take an Exclude101        /// parameter. The PowerShell engine should not try to do the filtering on behalf of this102        /// provider.103        /// </para>104        /// <para>105        /// The implementer of the provider should make every effort to filter in a way that is consistent106        /// with the PowerShell engine. This option is allowed because in many cases the provider107        /// can be much more efficient at filtering.108        /// </para>109        /// </summary>110        Exclude = 0x2,111 112        /// <summary>113        /// <para>114        /// The provider can take a provider specific filter string.115        /// </para>116        /// <para>117        /// For implementers of providers using this attribute, a provider specific filter can be passed from118        /// the Core Commands to the provider. This filter string is not interpreted in any119        /// way by the PowerShell engine.120        /// </para>121        /// </summary>122        Filter = 0x4,123 124        /// <summary>125        /// <para>126        /// The provider does the wildcard matching for those commands that allow for it. The PowerShell127        /// engine should not try to do the wildcard matching on behalf of the provider when this128        /// flag is set.129        /// </para>130        /// <para>131        /// The implementer of the provider should make every effort to do the wildcard matching in a way that is consistent132        /// with the PowerShell engine. This option is allowed because in many cases wildcard matching133        /// cannot occur via the path name or because the provider can do the matching in a much more134        /// efficient manner.135        /// </para>136        /// </summary>137        ExpandWildcards = 0x8,138 139        /// <summary>140        /// The provider supports ShouldProcess. When this capability is specified, the141        /// -Whatif and -Confirm parameters become available to the user when using142        /// this provider.143        /// </summary>144        ShouldProcess = 0x10,145 146        /// <summary>147        /// The provider supports credentials. When this capability is specified and148        /// the user passes credentials to the core cmdlets, those credentials will149        /// be passed to the provider. If the provider doesn't specify this capability150        /// and the user passes credentials, an exception is thrown.151        /// </summary>152        Credentials = 0x20,153 154        /// <summary>155        /// The provider supports transactions. When this capability is specified, PowerShell156        /// lets the provider participate in the current PowerShell transaction.157        /// The provider does not support this capability and the user attempts to apply a158        /// transaction to it, an exception is thrown.159        /// </summary>160        Transactions = 0x40,161    }162}163