MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Collections.ObjectModel;5 6#nullable enable7namespace System.Management.Automation.Provider8{9    #region IPropertyCmdletProvider10 11    /// <summary>12    /// An interface that can be implemented by a Cmdlet provider to expose properties of an item.13    /// </summary>14    /// <remarks>15    /// An IPropertyCmdletProvider provider implements a set of methods that allows16    /// the use of a set of core commands against the data store that the provider17    /// gives access to. By implementing this interface users can take advantage18    /// the commands that expose the contents of an item.19    ///     get-itemproperty20    ///     set-itemproperty21    ///     etc.22    /// This interface should only be implemented on derived classes of23    /// <see cref="CmdletProvider"/>, <see cref="ItemCmdletProvider"/>,24    /// <see cref="ContainerCmdletProvider"/>, or <see cref="NavigationCmdletProvider"/>.25    ///26    /// A namespace provider should implemented this interface if items in the27    /// namespace have properties the provide wishes to expose.28    /// </remarks>29    public interface IPropertyCmdletProvider30    {31        /// <summary>32        /// Gets the properties of the item specified by the path.33        /// </summary>34        /// <param name="path">35        /// The path to the item to retrieve properties from.36        /// </param>37        /// <param name="providerSpecificPickList">38        /// A list of properties that should be retrieved. If this parameter is null39        /// or empty, all properties should be retrieved.40        /// </param>41        /// <returns>42        /// Nothing.  The property that was retrieved should be passed to the WritePropertyObject method.43        /// </returns>44        /// <remarks>45        /// Providers override this method to give the user the ability to add properties to provider objects46        /// using the get-itemproperty cmdlet.47        ///48        /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>49        /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those50        /// requirements by accessing the appropriate property from the base class.51        ///52        /// By default overrides of this method should not retrieve properties from objects that are generally hidden from53        /// the user unless the Force property is set to true. An error should be sent to the WriteError method if54        /// the path represents an item that is hidden from the user and Force is set to false.55        ///56        /// An <see cref="System.Management.Automation.PSObject"/> can be used as a property bag for the57        /// properties that need to be returned if the <paramref name="providerSpecificPickList"/> contains58        /// multiple properties to write.59        /// </remarks>60        void GetProperty(61            string path,62            Collection<string>? providerSpecificPickList);63 64        /// <summary>65        /// Gives the provider an opportunity to attach additional parameters to the66        /// get-itemproperty cmdlet.67        /// </summary>68        /// <param name="path">69        /// If the path was specified on the command line, this is the path70        /// to the item to get the dynamic parameters for.71        /// </param>72        /// <param name="providerSpecificPickList">73        /// A list of properties that should be retrieved. If this parameter is null74        /// or empty, all properties should be retrieved.75        /// </param>76        /// <returns>77        /// Overrides of this method should return an object that has properties and fields decorated with78        /// parsing attributes similar to a cmdlet class or a79        /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.80        ///81        /// The default implementation returns null. (no additional parameters)82        /// </returns>83        object? GetPropertyDynamicParameters(84            string path,85            Collection<string>? providerSpecificPickList);86 87        /// <summary>88        /// Sets the specified properties of the item at the specified path.89        /// </summary>90        /// <param name="path">91        /// The path to the item to set the properties on.92        /// </param>93        /// <param name="propertyValue">94        /// A PSObject which contains a collection of the name, type, value95        /// of the properties to be set.96        /// </param>97        /// <returns>98        /// Nothing.  The property that was set should be passed to the WritePropertyObject method.99        /// </returns>100        /// <remarks>101        /// Providers override this method to give the user the ability to set the value of provider object properties102        /// using the set-itemproperty cmdlet.103        ///104        /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>105        /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those106        /// requirements by accessing the appropriate property from the base class.107        ///108        /// By default overrides of this method should not retrieve properties from objects that are generally hidden from109        /// the user unless the Force property is set to true. An error should be sent to the WriteError method if110        /// the path represents an item that is hidden from the user and Force is set to false.111        ///112        /// An <see cref="System.Management.Automation.PSObject"/> can be used as a property bag for the113        /// properties that need to be returned if the <paramref name="providerSpecificPickList"/> contains114        /// multiple properties to write.115        /// <paramref name="propertyValue"/> is a property bag containing the properties that should be set.116        /// See <see cref="System.Management.Automation.PSObject"/> for more information.117        /// </remarks>118        void SetProperty(119            string path,120            PSObject propertyValue);121 122        /// <summary>123        /// Gives the provider an opportunity to attach additional parameters to the124        /// get-itemproperty cmdlet.125        /// </summary>126        /// <param name="path">127        /// If the path was specified on the command line, this is the path128        /// to the item to get the dynamic parameters for.129        /// </param>130        /// <param name="propertyValue">131        /// A PSObject which contains a collection of the name, type, value132        /// of the properties to be set.133        /// </param>134        /// <returns>135        /// Overrides of this method should return an object that has properties and fields decorated with136        /// parsing attributes similar to a cmdlet class or a137        /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.138        ///139        /// The default implementation returns null. (no additional parameters)140        /// </returns>141        object? SetPropertyDynamicParameters(142            string path,143            PSObject propertyValue);144 145        /// <summary>146        /// Clears a property of the item at the specified path.147        /// </summary>148        /// <param name="path">149        /// The path to the item on which to clear the property.150        /// </param>151        /// <param name="propertyToClear">152        /// The name of the property to clear.153        /// </param>154        /// <returns>155        /// Nothing.  The property that was cleared should be passed to the WritePropertyObject method.156        /// </returns>157        /// <remarks>158        /// Providers override this method to give the user the ability to clear the value of provider object properties159        /// using the clear-itemproperty cmdlet.160        ///161        /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>162        /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those163        /// requirements by accessing the appropriate property from the base class.164        ///165        /// By default overrides of this method should not clear properties from objects that are generally hidden from166        /// the user unless the Force property is set to true. An error should be sent to the WriteError method if167        /// the path represents an item that is hidden from the user and Force is set to false.168        ///169        /// An <see cref="System.Management.Automation.PSObject"/> can be used as a property bag for the170        /// properties that need to be returned if the <paramref name="providerSpecificPickList"/> contains171        /// multiple properties to write.172        /// </remarks>173        void ClearProperty(174            string path,175            Collection<string> propertyToClear);176 177        /// <summary>178        /// Gives the provider an opportunity to attach additional parameters to the179        /// clear-itemproperty cmdlet.180        /// </summary>181        /// <param name="path">182        /// If the path was specified on the command line, this is the path183        /// to the item to get the dynamic parameters for.184        /// </param>185        /// <param name="propertyToClear">186        /// The name of the property to clear.187        /// </param>188        /// <returns>189        /// Overrides of this method should return an object that has properties and fields decorated with190        /// parsing attributes similar to a cmdlet class or a191        /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.192        ///193        /// The default implementation returns null. (no additional parameters)194        /// </returns>195        object? ClearPropertyDynamicParameters(196            string path,197            Collection<string> propertyToClear);198    }199 200    #endregion IPropertyCmdletProvider201}202