Professional Windows PowerShell Programming phần 10 doc

Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 284 Appendix D: Provider Base Classes and Overrides/Interfaces //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 284 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 285 Appendix D: Provider Base Classes and Overrides/Interfaces //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 ShouldContinue( string query, string caption ); public bool ShouldContinue(string query, string caption, 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( string target, string action ); public bool ShouldProcess( string verboseDescription, string verboseWarning, string caption ); public bool ShouldProcess( string verboseDescription, string verboseWarning, string caption, out ShouldProcessReason shouldProcessReason ); //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 ); 285 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 286 Appendix D: Provider Base Classes and Overrides/Interfaces //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 ); 286 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 287 Appendix D: Provider Base Classes and Overrides/Interfaces //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. 287 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 288 Appendix D: Provider Base Classes and Overrides/Interfaces 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: namespace System.Management.Automation.Provider { public abstract class DriveCmdletProvider : CmdletProvider { //The provider override this method to map drives after //initialization. All providers should mount a root drive //to increase discoverability. This root drive might contain //a set of locations that would be interesting as roots for //other mounted drives. protected virtual Collection < PSDriveInfo > InitializeDefaultDrives(); //Use this method to associate provider-specific data //with a drive by deriving a new class from PSDriveInfo. protected virtual PSDriveInfo NewDrive( PSDriveInfo drive ); //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 288 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 289 Appendix D: Provider Base Classes and Overrides/Interfaces 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. 289 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 290 Appendix D: Provider Base Classes and Overrides/Interfaces 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 PowerShellcontainerproviderthatexposes 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 290 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 291 Appendix D: Provider Base Classes and Overrides/Interfaces ❑ Set-Location ❑ Push-Location ❑ Pop-Location ❑ Get-Location -stack The prototype of ContainerCmdletProvider is as follows: namespace System.Management.Automation.Provider { //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. 291 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 292 Appendix D: Provider Base Classes and Overrides/Interfaces 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( string path); //Rename the item to the new name. The renamed items //should be written using WriteItemObject. // //Providers override this method to support the ability //to rename objects using the rename-item cmdlet. // //Provider should not allow renaming objects that are //generally hidden from the user unless the Force property //is set to true. // //RanameItem does not support moving the object from one //location to another. Use MoveItem instead for that purpose. protected virtual void RenameItem( string path, string newName ); //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 ); 292 Kumaravel bappd.tex V2 - 01/07/2008 2:47pm Page 293 Appendix D: Provider Base Classes and Overrides/Interfaces //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( string path, bool recurse ); //Determines if the item specified by the path has children. // //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 ); 293 [...]... verb-noun syntax of, 2 in Windows PowerShell Engine, 10 cmdlets, developing best practices, 114–116 command discovery, 65–66 command invocation, 67 command-line parsing, 65 documenting cmdlet help, 106 –114 generating pipeline output, 91–92 getting started, 63–65 parameter binding, 66 processing pipeline input, 84–91 reporting errors, 92–98 supporting ShouldProcess ( ) method, 98 100 using parameters See... design principles, 2 ADSI, PowerShell and, 2 Alias provider, 125–126 AliasAttribute metadata, 273 AllowEmptyCollection metdata, 277 AllowEmptyString metdata, 276 AllowNullAttribute metdata, 276 APIs, and provider errors, 122 appendPath parameter, update-formatdata cmdlet, 239 architecture GUI integration with command line, 193–194 host application, 9 10 Windows PowerShell Engine, 10 argument validation... about providers, 117 documenting cmdlet help, 106 –114 overview of, 4–5 GetItem( ) method, ItemCmdletProvider, 145–146 get-item cmdlet, 130 get-itemproperty cmdlet, 134, 156–158, 297–298 get-location cmdlet, 132, 147 get-member cmdlet, 6–8 get-pssnapin cmdlet, 10 11, 19 get-pssnapin -registered command, 22–23 GetResolvedProviderPathFromPSPath( ) method, file path resolution, 103 106 GetVariable( ) method,... variable, cmdlet and host interaction, 205 well-known members, PSObject, 62 -whatif parameter, ShouldProcess ( ) method, 100 wide view, 235–236, 246 WideControl, 246 WideEntries, 246 wildcard characters, 4, 122–123 WildcarePattern class, 122–123 Windows PowerShell Engine, 10 WMI, PowerShell and, 2, 8 node, format configuration, 248 Write( )method IContentCmdletProvider interface, 161–162 input... pipeline input, 84–91 reporting errors, 92–98 supporting ShouldProcess ( ) method, 98 100 using parameters See parameters working with PowerShell path, 101 106 colon (:), drive-qualified paths, 120 colon, double (::), provider paths, 120–121 colors, customizing text, 253–255 COM, PowerShell and, 2, 8 command arguments binding to command parameters with, 66 command-line parsing using, 65 parameter binding of... property, 210 CurrentUICulture property, 210 defined, 198 EnterNestedPrompt( )method, 211–212 ExitNestedPrompt( )method, 212–214 InstanceID property, 208–209 Name property, 209– 210 NotifyBeginApplication( )method, 214 NotifyEndApplication( )method, 214 11:38am Page 312 bindex.tex V1 - 01/07/2008 11:38am RunspaceStateInfo property, runspace StateChanged event overview of, 207–208 PrivateData property, 210 SetShouldExit(... ShouldContinue ( ) method best practices for cmdlets, 115 CmdletProvider used with, 137, 163 working with, 101 ShouldProcess ( ) method best practices for cmdlets, 115 CmdletProvider used with, 136–137 NavigationCmdletProvider used with, 155–156 overview of, 98 100 provider capabilities using, 122–123 working with, 100 101 SilentlyContinue value DebugPreference variable with, 199 Write-Progress cmdlet with, 203... pipelines programmatically, 189–193 executing existing native OS, 7–8 executing PowerShell Engine API, 166–169 Commands collection, 175–176 communication verbs, cmdlet names, 260 compatibility, of PowerShell, 2 complete cell type, 230–231 308 XML node, format, 240 -confirm parameter, ShouldProcess ( ), 100 101 ConfirmImpact property, ShouldProcess ( ), 99 console file (.pscl), creating... retrieving pipeline output, 170–172 reusing pipelines, 175 running pipeline asynchronously, 181–187 runspaces and pipelines, 165–166 PowerShell. exe, 9 10 precedence, TypeNames, 53–54 prependPath parameter, update-formatdata cmdlet, 239 PrivateData property, PSHost class, 210 ProcessRecord( ) method, command invocation, 67 profiles, saving snap-in configuration, 23 ProgressPreference variable, Write-Progress... developers handling, 121–122 runtime, 55–56 errors, reporting cmdlet, 92–98 creating ErrorDetails, 95–96 creating ErrorRecord, 93–95 non-terminating and terminating errors, 97–98 overview of, 92–93 PowerShell path, 101 106 ETS (Extended Type System), 29 See also PSObject exceptions ErrorRecord, 93 from ETS during runtime, 55–56 Exclude operation, capabilities, 122 exit command, 214 ExitNestedPrompt( )method, . path ); } } ContainerCmdletProvider The ContainerCmdletProvider base class defines a Windows PowerShellcontainerproviderthatexposes a container of items to the user. Note that the Windows PowerShell container provider can be used only when. 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. virtual void StopProcessing(); } } DriveCmdletProvider The DriveCmdletProvider class defines a Windows PowerShell drive provider that supports opera- tions for adding new drives, removing existing