2020-03-24 19:08:37 +01:00
|
|
|
// Copyright (c) Microsoft Corporation.
|
2018-02-13 18:23:53 +01:00
|
|
|
// Licensed under the MIT License.
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
using System.Management.Automation.Internal;
|
|
|
|
|
|
|
|
namespace System.Management.Automation.Provider
|
|
|
|
{
|
|
|
|
#region ItemCmdletProvider
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// The base class for Cmdlet providers that expose an item as an MSH path.
|
|
|
|
/// </summary>
|
|
|
|
/// <remarks>
|
|
|
|
/// The ItemCmdletProvider class is a base class that a provider derives from to
|
|
|
|
/// inherit a set of methods that allows the Monad engine
|
|
|
|
/// to provide a core set of commands for getting and setting of data on one or
|
|
|
|
/// more items. A provider should derive from this class if they want
|
2017-01-16 22:31:14 +01:00
|
|
|
/// to take advantage of the item core commands that are
|
2016-03-30 23:20:52 +02:00
|
|
|
/// already implemented by the Monad engine. This allows users to have common
|
|
|
|
/// commands and semantics across multiple providers.
|
|
|
|
/// </remarks>
|
|
|
|
public abstract class ItemCmdletProvider : DriveCmdletProvider
|
|
|
|
{
|
|
|
|
#region internal methods
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Internal wrapper for the GetItem protected method. It is called instead
|
|
|
|
/// of the protected method that is overridden by derived classes so that the
|
|
|
|
/// context of the command can be set.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
2017-01-16 22:31:14 +01:00
|
|
|
/// The path to the item to retrieve.
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Nothing is returned, but all objects should be written to the WriteObject method.
|
|
|
|
/// </returns>
|
|
|
|
internal void GetItem(string path, CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
Context = context;
|
|
|
|
|
|
|
|
// Call virtual method
|
|
|
|
|
|
|
|
GetItem(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider to attach additional parameters to
|
|
|
|
/// the get-item cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
internal object GetItemDynamicParameters(string path, CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
Context = context;
|
|
|
|
return GetItemDynamicParameters(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Internal wrapper for the SetItem protected method. It is called instead
|
|
|
|
/// of the protected method that is overridden by derived classes so that the
|
|
|
|
/// context of the command can be set.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// The path to the item to set.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="value">
|
|
|
|
/// The value of the item specified by the path.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// The item that was set at the specified path.
|
|
|
|
/// </returns>
|
|
|
|
internal void SetItem(
|
|
|
|
string path,
|
|
|
|
object value,
|
|
|
|
CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
providerBaseTracer.WriteLine("ItemCmdletProvider.SetItem");
|
|
|
|
|
|
|
|
Context = context;
|
|
|
|
|
|
|
|
// Call virtual method
|
|
|
|
|
|
|
|
SetItem(path, value);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider to attach additional parameters to
|
|
|
|
/// the set-item cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="value">
|
|
|
|
/// The value of the item specified by the path.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
internal object SetItemDynamicParameters(
|
2016-07-29 22:02:49 +02:00
|
|
|
string path,
|
|
|
|
object value,
|
2016-03-30 23:20:52 +02:00
|
|
|
CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
Context = context;
|
|
|
|
return SetItemDynamicParameters(path, value);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Internal wrapper for the ClearItem protected method. It is called instead
|
|
|
|
/// of the protected method that is overridden by derived classes so that the
|
|
|
|
/// context of the command can be set.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// The path to the item to clear.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
internal void ClearItem(
|
|
|
|
string path,
|
|
|
|
CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
providerBaseTracer.WriteLine("ItemCmdletProvider.ClearItem");
|
|
|
|
|
|
|
|
Context = context;
|
|
|
|
|
|
|
|
// Call virtual method
|
|
|
|
|
|
|
|
ClearItem(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider to attach additional parameters to
|
|
|
|
/// the clear-item cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
internal object ClearItemDynamicParameters(
|
2016-07-29 22:02:49 +02:00
|
|
|
string path,
|
2016-03-30 23:20:52 +02:00
|
|
|
CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
Context = context;
|
|
|
|
return ClearItemDynamicParameters(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-07-29 22:02:49 +02:00
|
|
|
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <summary>
|
|
|
|
/// Internal wrapper for the InvokeDefaultAction protected method. It is called instead
|
|
|
|
/// of the protected method that is overridden by derived classes so that the
|
|
|
|
/// context of the command can be set.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// The path to the item to perform the default action on.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
internal void InvokeDefaultAction(
|
|
|
|
string path,
|
|
|
|
CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
providerBaseTracer.WriteLine("ItemCmdletProvider.InvokeDefaultAction");
|
|
|
|
|
|
|
|
Context = context;
|
|
|
|
|
|
|
|
// Call virtual method
|
|
|
|
|
|
|
|
InvokeDefaultAction(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-07-29 22:02:49 +02:00
|
|
|
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider to attach additional parameters to
|
|
|
|
/// the invoke-item cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
internal object InvokeDefaultActionDynamicParameters(
|
2016-07-29 22:02:49 +02:00
|
|
|
string path,
|
2016-03-30 23:20:52 +02:00
|
|
|
CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
Context = context;
|
|
|
|
return InvokeDefaultActionDynamicParameters(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Internal wrapper for the Exists protected method. It is called instead
|
|
|
|
/// of the protected method that is overridden by derived classes so that the
|
|
|
|
/// context of the command can be set.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
2017-01-16 22:31:14 +01:00
|
|
|
/// The path to the item to see if it exists.
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// True if the item exists, false otherwise.
|
|
|
|
/// </returns>
|
2016-07-29 22:02:49 +02:00
|
|
|
internal bool ItemExists(string path, CmdletProviderContext context)
|
2016-03-30 23:20:52 +02:00
|
|
|
{
|
|
|
|
Context = context;
|
|
|
|
|
|
|
|
// Call virtual method
|
|
|
|
|
|
|
|
bool itemExists = false;
|
|
|
|
try
|
|
|
|
{
|
|
|
|
// Some providers don't expect non-valid path elements, and instead
|
|
|
|
// throw an exception here.
|
2016-07-29 22:02:49 +02:00
|
|
|
itemExists = ItemExists(path);
|
2016-03-30 23:20:52 +02:00
|
|
|
}
|
2016-11-01 23:24:07 +01:00
|
|
|
catch (Exception)
|
2016-03-30 23:20:52 +02:00
|
|
|
{
|
|
|
|
}
|
|
|
|
|
|
|
|
return itemExists;
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider to attach additional parameters to
|
|
|
|
/// the test-path cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
2016-07-29 22:02:49 +02:00
|
|
|
internal object ItemExistsDynamicParameters(
|
2016-03-30 23:20:52 +02:00
|
|
|
string path,
|
|
|
|
CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
Context = context;
|
2016-07-29 22:02:49 +02:00
|
|
|
return ItemExistsDynamicParameters(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Internal wrapper for the IsValidPath protected method. It is called instead
|
|
|
|
/// of the protected method that is overridden by derived classes so that the
|
|
|
|
/// context of the command can be set.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
2017-01-16 22:31:14 +01:00
|
|
|
/// The path to check for validity.
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// True if the path is syntactically and semantically valid for the provider, or
|
|
|
|
/// false otherwise.
|
|
|
|
/// </returns>
|
|
|
|
/// <remarks>
|
2016-08-28 07:51:23 +02:00
|
|
|
/// This test should not verify the existence of the item at the path. It should
|
2016-03-30 23:20:52 +02:00
|
|
|
/// only perform syntactic and semantic validation of the path. For instance, for
|
|
|
|
/// the file system provider, that path should be canonicalized, syntactically verified,
|
|
|
|
/// and ensure that the path does not refer to a device.
|
|
|
|
/// </remarks>
|
2016-07-29 22:02:49 +02:00
|
|
|
internal bool IsValidPath(string path, CmdletProviderContext context)
|
2016-03-30 23:20:52 +02:00
|
|
|
{
|
|
|
|
Context = context;
|
|
|
|
|
|
|
|
// Call virtual method
|
|
|
|
|
2016-07-29 22:02:49 +02:00
|
|
|
return IsValidPath(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Internal wrapper for the ExpandPath protected method. It is called instead
|
|
|
|
/// of the protected method that is overridden by derived classes so that the
|
|
|
|
/// context of the command can be set. Only called for providers that declare
|
|
|
|
/// the ExpandWildcards capability.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// The path to expand. Expansion must be consistent with the wildcarding
|
|
|
|
/// rules of PowerShell's WildcardPattern class.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="context">
|
|
|
|
/// The context under which this method is being called.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// A list of provider paths that this path expands to. They must all exist.
|
|
|
|
/// </returns>
|
|
|
|
internal string[] ExpandPath(string path, CmdletProviderContext context)
|
|
|
|
{
|
|
|
|
Context = context;
|
|
|
|
|
|
|
|
// Call virtual method
|
|
|
|
return ExpandPath(path);
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
#endregion internal methods
|
|
|
|
|
|
|
|
#region Protected methods
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gets the item at the specified path.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
2017-01-16 22:31:14 +01:00
|
|
|
/// The path to the item to retrieve.
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Nothing is returned, but all objects should be written to the WriteItemObject method.
|
|
|
|
/// </returns>
|
|
|
|
/// <remarks>
|
|
|
|
/// Providers override this method to give the user access to the provider objects using
|
|
|
|
/// the get-item and get-childitem cmdlets.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>
|
|
|
|
/// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those
|
|
|
|
/// requirements by accessing the appropriate property from the base class.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
|
|
|
/// By default overrides of this method should not write objects that are generally hidden from
|
2016-03-30 23:20:52 +02:00
|
|
|
/// the user unless the Force property is set to true. For instance, the FileSystem provider should
|
2017-01-16 22:31:14 +01:00
|
|
|
/// not call WriteItemObject for hidden or system files unless the Force property is set to true.
|
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.
|
|
|
|
/// </remarks>
|
|
|
|
protected virtual void GetItem(string path)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
throw
|
|
|
|
PSTraceSource.NewNotSupportedException(
|
|
|
|
SessionStateStrings.CmdletProvider_NotSupported);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider an opportunity to attach additional parameters to
|
|
|
|
/// the get-item cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
protected virtual object GetItemDynamicParameters(string path)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
return null;
|
|
|
|
}
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Sets the item specified by the path.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// The path to the item to set.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="value">
|
|
|
|
/// The value of the item specified by the path.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Nothing. The item that was set should be passed to the WriteItemObject method.
|
|
|
|
/// </returns>
|
|
|
|
/// <remarks>
|
|
|
|
/// Providers override this method to give the user the ability to modify provider objects using
|
|
|
|
/// the set-item cmdlet.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>
|
|
|
|
/// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those
|
|
|
|
/// requirements by accessing the appropriate property from the base class.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
|
|
|
/// By default overrides of this method should not set or write objects that are generally hidden from
|
2016-03-30 23:20:52 +02:00
|
|
|
/// the user unless the Force property is set to true. An error should be sent to the WriteError method if
|
|
|
|
/// the path represents an item that is hidden from the user and Force is set to false.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.
|
|
|
|
/// </remarks>
|
|
|
|
protected virtual void SetItem(
|
|
|
|
string path,
|
|
|
|
object value)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
throw
|
|
|
|
PSTraceSource.NewNotSupportedException(
|
|
|
|
SessionStateStrings.CmdletProvider_NotSupported);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider an opportunity to attach additional parameters to
|
|
|
|
/// the set-item cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <param name="value">
|
|
|
|
/// The value of the item specified by the path.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
protected virtual object SetItemDynamicParameters(string path, object value)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
return null;
|
|
|
|
}
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Clears the item specified by the path.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// The path to the item to clear.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Nothing. The item that was cleared should be passed to the WriteItemObject method.
|
|
|
|
/// </returns>
|
|
|
|
/// <remarks>
|
|
|
|
/// Providers override this method to give the user the ability to clear provider objects using
|
|
|
|
/// the clear-item cmdlet.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>
|
|
|
|
/// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those
|
|
|
|
/// requirements by accessing the appropriate property from the base class.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
|
|
|
/// By default overrides of this method should not clear or write objects that are generally hidden from
|
2016-03-30 23:20:52 +02:00
|
|
|
/// the user unless the Force property is set to true. An error should be sent to the WriteError method if
|
|
|
|
/// the path represents an item that is hidden from the user and Force is set to false.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.
|
|
|
|
/// </remarks>
|
|
|
|
protected virtual void ClearItem(
|
|
|
|
string path)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
throw
|
|
|
|
PSTraceSource.NewNotSupportedException(
|
|
|
|
SessionStateStrings.CmdletProvider_NotSupported);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider an opportunity to attach additional parameters to
|
|
|
|
/// the clear-item cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
protected virtual object ClearItemDynamicParameters(string path)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
return null;
|
|
|
|
}
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
2017-01-16 22:31:14 +01:00
|
|
|
/// Invokes the default action on the specified item.
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// The path to the item to perform the default action on.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Nothing. The item that was set should be passed to the WriteItemObject method.
|
|
|
|
/// </returns>
|
|
|
|
/// <remarks>
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation does nothing.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// Providers override this method to give the user the ability to invoke provider objects using
|
|
|
|
/// the invoke-item cmdlet. Think of the invocation as a double click in the Windows Shell. This
|
|
|
|
/// method provides a default action based on the path that was passed.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>
|
|
|
|
/// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those
|
|
|
|
/// requirements by accessing the appropriate property from the base class.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
|
|
|
/// By default overrides of this method should not invoke objects that are generally hidden from
|
2016-03-30 23:20:52 +02:00
|
|
|
/// the user unless the Force property is set to true. An error should be sent to the WriteError method if
|
|
|
|
/// the path represents an item that is hidden from the user and Force is set to false.
|
2017-01-16 22:31:14 +01:00
|
|
|
/// </remarks>
|
2016-03-30 23:20:52 +02:00
|
|
|
protected virtual void InvokeDefaultAction(
|
2016-07-29 22:02:49 +02:00
|
|
|
string path)
|
2016-03-30 23:20:52 +02:00
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
throw
|
|
|
|
PSTraceSource.NewNotSupportedException(
|
|
|
|
SessionStateStrings.CmdletProvider_NotSupported);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider an opportunity to attach additional parameters to
|
|
|
|
/// the invoke-item cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
protected virtual object InvokeDefaultActionDynamicParameters(string path)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
return null;
|
|
|
|
}
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Determines if an item exists at the specified path.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
2017-01-16 22:31:14 +01:00
|
|
|
/// The path to the item to see if it exists.
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// True if the item exists, false otherwise.
|
|
|
|
/// </returns>
|
|
|
|
/// <returns>
|
|
|
|
/// Nothing. The item that was set should be passed to the WriteItemObject method.
|
|
|
|
/// </returns>
|
|
|
|
/// <remarks>
|
|
|
|
/// Providers override this method to give the user the ability to check for the existence of provider objects using
|
|
|
|
/// the set-item cmdlet.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>
|
|
|
|
/// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those
|
|
|
|
/// requirements by accessing the appropriate property from the base class.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The implementation of this method should take into account any form of access to the object that may
|
2017-01-16 22:31:14 +01:00
|
|
|
/// make it visible to the user. For instance, if a user has write access to a file in the file system
|
2016-03-30 23:20:52 +02:00
|
|
|
/// provider bug not read access, the file still exists and the method should return true. Sometimes this
|
|
|
|
/// may require checking the parent to see if the child can be enumerated.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-03-30 23:20:52 +02:00
|
|
|
/// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.
|
|
|
|
/// </remarks>
|
|
|
|
protected virtual bool ItemExists(string path)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
throw
|
|
|
|
PSTraceSource.NewNotSupportedException(
|
|
|
|
SessionStateStrings.CmdletProvider_NotSupported);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Gives the provider an opportunity to attach additional parameters to
|
|
|
|
/// the test-path cmdlet.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// If the path was specified on the command line, this is the path
|
|
|
|
/// to the item to get the dynamic parameters for.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// Overrides of this method should return an object that has properties and fields decorated with
|
2017-01-16 22:31:14 +01:00
|
|
|
/// parsing attributes similar to a cmdlet class or a
|
2016-03-30 23:20:52 +02:00
|
|
|
/// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.
|
2017-01-16 22:31:14 +01:00
|
|
|
///
|
2016-08-28 07:51:23 +02:00
|
|
|
/// The default implementation returns null. (no additional parameters)
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </returns>
|
|
|
|
protected virtual object ItemExistsDynamicParameters(string path)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
return null;
|
|
|
|
}
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Providers must override this method to verify the syntax and semantics
|
|
|
|
/// of their paths.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
2017-01-16 22:31:14 +01:00
|
|
|
/// The path to check for validity.
|
2016-03-30 23:20:52 +02:00
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// True if the path is syntactically and semantically valid for the provider, or
|
|
|
|
/// false otherwise.
|
|
|
|
/// </returns>
|
|
|
|
/// <remarks>
|
2016-08-28 07:51:23 +02:00
|
|
|
/// This test should not verify the existence of the item at the path. It should
|
2016-03-30 23:20:52 +02:00
|
|
|
/// only perform syntactic and semantic validation of the path. For instance, for
|
|
|
|
/// the file system provider, that path should be canonicalized, syntactically verified,
|
|
|
|
/// and ensure that the path does not refer to a device.
|
|
|
|
/// </remarks>
|
|
|
|
protected abstract bool IsValidPath(string path);
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
/// Expand a provider path that contains wildcards to a list of provider
|
|
|
|
/// paths that the path represents.Only called for providers that declare
|
|
|
|
/// the ExpandWildcards capability.
|
|
|
|
/// </summary>
|
|
|
|
/// <param name="path">
|
|
|
|
/// The path to expand. Expansion must be consistent with the wildcarding
|
|
|
|
/// rules of PowerShell's WildcardPattern class.
|
|
|
|
/// </param>
|
|
|
|
/// <returns>
|
|
|
|
/// A list of provider paths that this path expands to. They must all exist.
|
|
|
|
/// </returns>
|
|
|
|
protected virtual string[] ExpandPath(string path)
|
|
|
|
{
|
|
|
|
using (PSTransactionManager.GetEngineProtectionScope())
|
|
|
|
{
|
|
|
|
return new string[] { path };
|
|
|
|
}
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
#endregion Protected methods
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|
|
|
|
#endregion ItemCmdletProvider
|
2018-12-08 17:53:30 +01:00
|
|
|
}
|
2016-03-30 23:20:52 +02:00
|
|
|
|