Professional Windows PowerShell Programming phần 10 doc

protected virtual object GetItemDynamicParameters string path ; //Override this method to allow the user to modify //provider objects using the set-item cmdlet.. protected virtual void S

//Wildcard patterns to determine which items are excluded //when performing an action.

public Collection <string> Exclude { get; }

//The provider-specific filter supplied by the caller public string Filter { get; }

//Whether to try vigorously to perform an operation public SwitchParameter Force { get; }

//The host interaction APIs public PSHost Host { get; }

//Wildcard patterns to determine which items are included //when performing an action.

public Collection <string> Include { get; }

//Get the command invocation API for the current runspace public CommandInvocationIntrinsics InvokeCommand { get; }

//Get the provider interface APIs for the current runspace public ProviderIntrinsics InvokeProvider { get; }

//Get the session state for the current runspace public SessionState SessionState { get; }

//Whether a stop request has been made on the provider.

public bool Stopping { get; }

//Get the dynamic parameters specified by the user.

protected Object DynamicParameters { get; }

//Get information about the current PowerShell provider.

protected internal ProviderInfo ProviderInfo { get; }

//Get the drive for the current operation protected PSDriveInfo PSDriveInfo { get; }

//Query user to confirm whether PowerShell should proceed //with an operation.

//

//Both should-process and should-continue can be used to //confirm an operation with the user While the behavior of

//ShouldProcess can be affected by preference settings and

//command-line parameters that can specify whether the query

//is displayed to the user, the behavior of ShouldContinue

//is not affected by preference settings or command-line

ref bool yesToAll,

ref bool noToAll

);

//Query user to confirm an operation before making changes

//to the system.

//

//Both should-process and should-continue can be used to

//confirm an operation with the user While the behavior of

//ShouldProcess can be affected by preference settings and

//command-line parameters that can specify whether the query

//is displayed to the user, the behavior of ShouldContinue

//is not affected by preference settings or command-line

//parameters.

public bool ShouldProcess(string target);

public bool ShouldProcess(

//PowerShell provider should call this method when encounter

//a fatal error Call WriteError method for nonfatal error.

public void ThrowTerminatingError(

ErrorRecord errorRecord

);

//Writes a debug message to the host.

public void WriteDebug(

string text

);

//Call this method write a error record to the pipeline //and the provider will continue to perform more operations.

public void WriteError(

ErrorRecord errorRecord );

//Write an item to the output as a PSObject object public void WriteItemObject(

Object item, string path, bool isContainer );

//Write a progress record to the host This method is called //to display the progress of a PowerShell provider for a long //running operation The behavior of progress status can be //configured through the ProgressPreference variable.

public void WriteProgress(

ProgressRecord progressRecord );

//Write a property object to the output public void WritePropertyObject(

Object propertyValue, string path

);

//Writes a security descriptor object to the output public void WriteSecurityDescriptorObject(

ObjectSecurity securityDescriptor, string path

);

//Write a message to the host for informational purpose public void WriteVerbose(

string text );

//Write a warning message to the host The behavior of //Warning messages can be configured through the //WarningPreference variable or the Verbose and Debug //command-line options.

public void WriteWarning(

string text );

//Get the resource string from the current assembly that //corresponds to the specified base name and resource //identifier Override this method if a different behavior //is required.

public virtual string GetResourceString(

string baseName, string resourceId );

//PowerShell runtime call this method to initialize the //provider when the provider is loaded into a session.

//The default implementation of this method returns the object //specified in the providerInfo parameter Provider should //override this method if it needs to initialize the provider //with additional information.

protected virtual ProviderInfo Start(

ProviderInfo providerInfo );

//Call this method to add more parameters to the Start method //implemented by a PowerShell provider.

protected virtual Object StartDynamicParameters();

//The PowerShell runtime calls this method before it removes //a provider A PowerShell provider should override this //method to free any resources before the provider is removed //by the PowerShell runtime.

protected virtual void Stop();

//The PowerShell runtime call this method when the user //cancels an opertion.

protected internal virtual void StopProcessing();

}

}

DriveCmdletProvider

The DriveCmdletProvider class defines a Windows PowerShell drive provider that supports

opera-tions for adding new drives, removing existing drives, and initializing default drives For example,

the FileSystem provider provided by Windows PowerShell initializes drives for all volumes that are

mounted, such as hard drives and CD/DVD device drives.

The methods of this class must be overridden to provide the ability to create drives, initialize default

drives (those that the specific provider should supply, given the user environment), as well as to

remove drives.

Although it is possible to derive from this class, this class does not define the methods needed to get or

change the data (referred to as ‘‘item’’) in the data store In most cases, developers should derive from

one of the following classes to implement their own Windows PowerShell providers:

❑ ItemCmdletProvider: This base class defines methods that can get, set, and clear the items of a

data store.

❑ ContainerCmdletProvider: This base class defines methods that can get the child items (or just

their names) of the data store, as well as methods that create, copy, rename, and remove items of

a data store.

❑ NavigationCmdletProvider: This serves as the base class for Windows PowerShell providers

that perform operations against items in a multi-level store.

This class derives from the CmdletProvider base class The class prototype is as follows:

protected virtual Collection <PSDriveInfo>

//Use this method to add more parameters to the //New-Drive cmdlet for the provider.

protected virtual Object NewDriveDynamicParameters();

//Use this method to clean up any provider-specific data //before the drive is removed.

protected virtual PSDriveInfo RemoveDrive(

PSDriveInfo drive );

}

}

ItemCmdletProvider

This class derives from the DriveCmdletProvider base class It is a base class for cmdlet providers that

expose an item as a PowerShell path Deriving a class from ItemCmdletProvider allows the PowerShell

engine to support a core set of cmdlets for getting and setting data items; however, it does not provide

any container or navigation capabilities.

The ItemCmdletProvider prototype is as follows:

namespace System.Management.Automation.Provider

{

public abstract class ItemCmdletProvider : DriveCmdletProvider

{

//Override this method to give the user access to the provider

//objects using the get-item and get-childitem cmdlets.

//Nothing is returned and all objects should be written

//using the WriteItemObject method.

//

//Provider should not write objects that are generally hidden

//from the user unless the Force property is set to true.

protected virtual void GetItem(string path);

//Use this method to add additional custom paramaters to

//the Get-Item cmdlet.

protected virtual object GetItemDynamicParameters(

string path );

//Override this method to allow the user to modify

//provider objects using the set-item cmdlet.

//

//Provider should not write objects that are generally hidden

//from the user unless the Force property is set to true.

protected virtual void SetItem(

string path, object value );

//Use this method to add additional custom paramaters to

//the Set-Item cmdlet.

protected virtual object SetItemDynamicParameters(

string path, object value );

//Override this method to allow the user to clear

//provider objects using the Clear-Item cmdlet.

//

//Provider should not clear or write objects that are

//generally hidden from the user unless the Force property

//is set to true.

protected virtual void ClearItem(string path);

//Use this method to add additional custom paramaters to

//the Clear-Item cmdlet.

protected virtual object ClearItemDynamicParameters(

string path );

//Override this method to allow the user to invoke //provider objects using the Invoke-Item cmdlet The default //action for the path will be performed.

//

//Provider should not invoke objects that are generally //hidden from the user unless the Force property //is set to true.

protected virtual void InvokeDefaultAction(

string path );

//Use this method to add additional custom paramaters to //the Invoke-Item cmdlet It retrieves the dynamic parameters //for the item at the indicated path

protected virtual object InvokeDefaultActionDynamicParameters(

string path );

//Use this method to add additional custom paramaters to //the Test-Path cmdlet.

protected virtual object ItemExistsDynamicParameters(

string path );

}

}

ContainerCmdletProvider

The ContainerCmdletProvider base class defines a Windows PowerShell container provider that exposes

a container of items to the user Note that the Windows PowerShell container provider can be used only

when there is one container with items in it You must implement a Windows PowerShell navigation

provider to support nested containers.

The ContainerCmdletProvider derives from the ItemCmdletProvider base class By deriving from

ContainerCmdletProvider , a provider gets all the functionality of the ItemCmdletProvider base class,

plus the following set of core provider cmdlets:

❑ Get-ChildItem

❑ Rename-Item

❑ New-Item

❑ Remove-Item

//Base class for Cmdlet providers that expose a single

//level container of items.

public abstract class ContainerCmdletProvider : ItemCmdletProvider

{

//Get the children of the item specifed by the path.

//all objects should be written to the WriteItemObject method.

//

//Providers override this method to allow the user access

//to data objects using the Get-ChildItem cmdlet.

//

//The value for recurse should only be true for classes

//derived from NavigationCmdletProvider.

//

//The provider implementation should prevent infinite

//recursion when there are circular links and the like.

//

//Provider should not get objects that are generally

//hidden from the user unless the Force property

//is set to true.

protected virtual void GetChildItems(

string path, bool recurse );

//Use this method to add additional custom paramaters to

//the Get-ChildItem cmdlet.

protected virtual object GetChildItemsDynamicParameters(

string path, bool recurse );

//Get names of the children of the specified path All

//objects should be written to the WriteItemObject method.

//

//Providers override this method to give the user access

//to data objects using the get-childitem -name cmdlet.

//

//The provider implementation should prevent infinite

//recursion when there are circular links and the like.

//

//Provider should not get objects that are generally

//hidden from the user unless the Force property

//is set to true.

protected virtual void GetChildNames(

string path, ReturnContainers returnContainers );

//Use this method to add additional custom paramaters to //the Get-ChildItem -name cmdlet.

protected virtual object GetChildNamesDynamicParameters(

//Use this method to add additional custom paramaters to //the Rename-Item cmdlet.

protected virtual object RenameItemDynamicParameters(

string path, string newName );

//Create a new item of the specified type at the //specified path.

//

//Providers override this method to support the ability //to create new objects using the new-item cmdlet.

//

//itemTypeName is provider specific.

protected virtual void NewItem(

string path, string itemTypeName, object newItemValue );

//Use this method to add additional custom paramaters to //the New-Item cmdlet.

protected virtual object NewItemDynamicParameters(

string path, string itemTypeName, object newItemValue );

//Remove the item specified by the path

//

//recurse is a boolean value used to determine if all children

//in a subtree should be removed This parameter should only

//be true for NavigationCmdletProvider derived classes.

//

//Providers override this method to support the ability

//to remove objects using the remove-item cmdlet.

//

//Provider should not allow removing objects that are

//generally hidden from the user unless the Force property

//is set to true.

protected virtual void RemoveItem(

string path,

bool recurse

);

//Override this method to add additional custom paramaters to

//the Remove-Item cmdlet.

protected virtual object RemoveItemDynamicParameters(

//Providers override this method to give the provider

//infrastructure the ability to determine if a particular

//provider object has children without having to retrieve

//all the child items.

protected virtual bool HasChildItems(string path);

//Copy an item to a new path The boolean value of recurse

//tells the provider whether to recurse sub-containers

//when copying, and it should only be true for

//NavigationCmdletProvider derived providers.

//

//Providers override this method to support the ability to

//copy objects using the copy-item cmdlet.

//

//By default overrides of this method should not copy objects

//over existing items unless the Force property is set to

//true.

//

//If recurse is true, the provider implementation should

//prevent infinite recursion when there are circular links

//and the like.

protected virtual void CopyItem(

string path,

string copyPath,

bool recurse

);

//Use this method to add additional custom paramaters to //the Copy-Item cmdlet.

protected virtual Object CopyItemDynamicParameters(

string path, string destination, bool recurse );

}

}

NavigationCmdletProvider

The NavigationCmdletProvider class defines a Windows PowerShell navigation provider that performs

operations for items that use more than one container Deriving from this class enables users to work with

nested containers using path and recursive commands The NavigationCmdletProvider class derives

from the ContainerCmdletProvider base class.

Here’s the definition of the NavigationCmdletProvider class:

namespace System.Management.Automation.Provider

{

public abstract class NavigationCmdletProvider :

ContainerCmdletProvider {

//Join two path segments with a path separator character.

protected virtual string MakePath(

string parent, string child );

//Get and return the remaining parent segment of the path.

protected virtual string GetParentPath(

string path, string root );

//Return the normalized path relative to the basePath.

protected virtual string NormalizeRelativePath(

string path, string basePath );

//Return the child segment of the path protected virtual string GetChildName(string path);

//Return true if the path is a container.

//

//Providers supporting ExpandWildcards, Filter, Include, or //Exclude should ensure that the path passed meets those //requirements.

protected virtual bool IsItemContainer(string path);

//Move the item specified by path to the destination path.

//All the objects that were moved should be written using //WriteItemObject method Implementing this methods allows //the provider to support the Move-Item cmdlet.

//

//By default overrides of this method should not move objects //over existing items unless the Force property is set to //true.

protected virtual void MoveItem(

string path, string destination );

//Use this method to add additional custom paramaters to //the Move-Item cmdlet.

protected virtual object MoveItemDynamicParameters(

string path, string destination );

//Only classes that derive from CmdletProvider or its

//derived classes should implement this interface.

public interface IContentCmdletProvider

{

//Get the content reader for the item.

//

//By default overrides of this method should not return //a content reader for hidden objects unless the Force //property is set to true.

IContentReader GetContentReader(string path);

//Use this method to add additional custom paramaters to //the Get-Content cmdlet.

object GetContentReaderDynamicParameters(string path);

//Get the content writer for the item.

//

//By default overrides of this method should not return //a content writer for hidden objects unless the Force //property is set to true.

IContentWriter GetContentWriter(string path);

//Use this method to add additional custom paramaters to //the Set-Content and Add-Content cmdlets.

object GetContentWriterDynamicParameters(string path);

//Clear the content from the item.

//

//By default overrides of this method should not clear //hidden objects unless the Force property is set to true.

void ClearContent(string path);

//Use this method to add additional custom paramaters to //the Clear-Content cmdlet.

object ClearContentDynamicParameters(string path);

//Read an array of blocks of data from the item.

//What makes a "block" is provider specific.

IList Read(long readCount);

//Set the position from where data will be read next time.

void Seek(long offset, SeekOrigin origin);

//Closes the reader and resources held by the reader.

void Close();

}

}

//Write an array of blocks of data to the item.

//What makes a "block" is provider specific.

IList Write(IList content);

//Set the position from where data will be written next time.

void Seek(long offset, SeekOrigin origin);

//Closes the writer and resources held by the writer.

void Close();

}

}

IProper tyCmdletProvider

The IPropertyCmdletProvider interface is used by PowerShell providers to expose properties of an

item in the data store Implementing this interface enables the provider to support the following

ItemProperty -related cmdlets:

void GetProperty(

string path, Collection <string> providerSpecificPickList

);

//Use this method to add additional custom paramaters to //the Get-Itemproperty cmdlet.

object GetPropertyDynamicParameters(

string path, Collection <string> providerSpecificPickList

void SetProperty(

string path, PSObject propertyValue );

//Use this method to add additional custom paramaters to //the Set-Itemproperty cmdlet.

object SetPropertyDynamicParameters(

string path, PSObject propertyValue);

//Providers implement this method to support the //Clear-Itemproperty cmdlet.

//

//By default overrides of this method should not clear //properties of hidden objects unless the Force property //is set to true.

void ClearProperty(

string path, Collection <string> propertyToClear

}

}

IDynamicProper tyCmdletProvider

The IDynamicPropertyCmdletProvider interface, derived from IPropertyCmdletProvider , is used by

PowerShell providers to manage dynamic properties of an item Implementing this interface enables the

provider to support the following ItemProperty -related cmdlets:

❑ Copy-ItemProperty

❑ Move-ItemProperty

//Providers implement this method to support the

//New-Itemproperty cmdlet.

//

//By default overrides of this method should not create

//a new property from hidden objects unless the Force property

//is set to true.

void NewProperty(

string path, string propertyName, string propertyTypeName, object value

);

//Use this method to add additional custom paramaters to

//the New-Itemproperty cmdlet.

object NewPropertyDynamicParameters(

string path, string propertyName, string propertyTypeName, object value

);

//Providers implement this method to support the

//Remove-Itemproperty cmdlet.

//

//By default overrides of this method should not remove

//properties from hidden objects unless the Force property

//is set to true.

void RemoveProperty(

string path, string propertyName );

//Use this method to add additional custom paramaters to

//the Remove-Itemproperty cmdlet.

object RemovePropertyDynamicParameters(

string path, string propertyName );