WIXLIB

Kumaravelftoc.tex V2 - 01/08/200812:04amContentsParameter SetsParameter ValidationParameter Transformation717880Processing Pipeline Input84Pipeline Parameter Binding87Generating Pipeline OutputReporting Errors9192ErrorRecordErrorDetailsNon-terminating Errors and Terminating Errors939597Supporting ShouldProcess98Confirming Impact LevelShouldContinue()100101Working with the PowerShell PathDocumenting Cmdlet HelpBest Practices for Cmdlet DevelopmentNaming ConventionsInteractions with the Host101106114114115Summary116Chapter 5: Providers117Why Implement a Provider?118Providers versus CmdletsEssential ConceptsPathsDrivesError HandlingCapabilitiesHello World ProviderBuilt-in ProvidersAlias ProviderEnvironment ProviderFileSystem ProviderFunction ProviderRegistry ProviderVariable ProviderCertificate 128Base Provider tProvider129129129xiPage xi

Kumaravelftoc.tex V2 - nCmdletProvider131132Optional Provider criptorCmdletProviderCmdletProviderMethods and Properties on 2133134134134136139141147153Design Guidelines and TipsSummary162163Chapter 6: Hosting the PowerShell Engine in Applications165Runspaces and PipelinesGetting StartedExecuting a Command Line165166166Using RunspaceInvokeUsing Runspace and PipelineUsing the Output of a PipelineThe Return Value of Invoke()Using PSObject Objects Returned from a PipelineHandling Terminating Errors166168170170170171Input, Output, and Errors for Synchronous Pipelines172Passing Input to Your PipelineThe Output Pipe in Synchronous ExecutionRetrieving Non-Terminating Errors from the Error PipeThe ErrorRecord Type172173173174Other Pipeline TricksNested PipelinesReusing PipelinesCopying a Pipeline Between RunspacesConfiguring Your RunspaceCreating a Runspace with a Custom ConfigurationAdding and Removing Snap-InsCreating RunspaceConfiguration from a Console FileCreating RunspaceConfiguration from an AssemblyUsing SessionStateProxy to Set and Retrieve VariablesFine-Tuning 717817912:04amPage xii

Kumaravelftoc.tex V2 - 01/08/200812:04amContentsRunning a Pipeline AsynchronouslyCalling InvokeAsync()Closing the Input PipeReading Output and Error from an Asynchronous PipelineMonitoring a Pipeline’s StateChanged EventReading Terminating Errors via PipelineStateInfo.ReasonStopping a Running PipelineAsynchronous Runspace OperationsThe OpenAsync() MethodHandling the Runspace’s StateChanged EventConstructing Pipelines ProgrammaticallyCreating an Empty PipelineCreating a CommandMerging Command ResultsAdding Command ParametersAdding Commands to the PipelineCmdlets as an API Layer for GUI ApplicationsHigh-Level ArchitectureKeys to Successful GUI IntegrationProviding a Custom 92193193194194Summary195Chapter 7: Hosts197Host-Windows PowerShell Engine InteractionBuilt-In Cmdlets That Interact with the te-ProgressWrite-Host and Out-HostRead-HostCmdlet and Host InteractionPSHost iiPage xiii

Kumaravelftoc.tex V2 - 01/08/2008ContentsApplication Notification MethodsSetShouldExitPSHostUserInterface eWriteProgressWriteErrorLineWrite MethodsPrompt MethodPromptForCredentialRead awUserInterface ClassSummary227231Chapter 8: Formatting & Output233The Four View Types233Table: format-tableList: format-listCustom: format-customWide: format-wideFormatting without#.format.ps1xmlFormat Configuration File ExampleLoading Your Format ion APIAnatomy of a Format Configuration HeadersTableRowEntriesListControlListEntriesWide 42243243244244245246WideEntries246Custom Control246CustomEntries248xiv12:04amPage xiv

Kumaravelftoc.tex V2 - 01/08/200812:04amContentsMiscellaneous Configuration Entries248WrapAutoSize248248Scenarios249Format StringsFormatting Deserialized ObjectsClass InheritanceSelection SetsColors249250250253253Summary255Appendix A: Cmdlet Verb Naming Guidelines257Common VerbsData VerbsCommunication VerbsDiagnostic VerbsLifecycle VerbsSecurity Verbs257259260260261261Appendix B: Cmdlet Parameter Naming Guidelines263Ubiquitous ParametersActivity ParametersDate/Time ParametersFormat ParametersProperty ParametersQuantity ParametersResource ParametersSecurity Parameters263264266266267268268269Appendix C: Metadata271CmdletAttribute271Cmdlet Attribute ExampleParameterAttributeParameterAttribute ExampleAliasAttributeAliasAttribute ExampleArgument Validation 4274xvPage xv

Kumaravelftoc.tex V2 - ngeAttributeAllow and Disallow ributeExtending Parameter Metadata ute275275276276276277277277277278278279279Adding Attributes to Dynamic Parameters at RuntimeValidateScriptAttribute280281Appendix D: Provider Base Classes and 7298Appendix E: Core Cmdlets for Provider Interaction303Drive-Specific CmdletsItem-Specific CmdletsContainer-Specific CmdletsProperty-Specific CmdletsDynamic Property Manipulation CmdletsContent-Related CmdletsSecurity Descriptor–Related Cmdlets303303304304305305305Indexxvi30712:04amPage xvi

Kumaravelflast.texV2 - 01/07/200810:54pmPrefaceWelcome to Professional Windows PowerShell Programming.Way back in 2003, I attended a talk at a conference center at Microsoft by some engineers from theMicrosoft Management Console team who were giving a demonstration of a prototype enhancementto MMC. The prototype was one of the early murmurs of Microsoft’s response to the deluge of customerfeedback they’d received about the Windows administrative user experience after the delivery of theirfirst truly Internet-focused server operating system, Windows 2000 Server. The feedback wasn’t all good.Windows 2000 Server started its long evolution as a text-based file manager for DOS. During the bulkof its development, there was simply no idea that anyone would use it for anything other than checkingtheir mail and organizing a 20-megabyte hard disk. As a result, the management story for Windows 2000Server was provided in The Windows Way, which was a rich interactive experience, a full set of nativeand COM APIs, and no bridge between the two. In Linux, you could write a shell script to configure yourmail and DNS servers; in Windows, you had to either do it manually or learn C and COM.The incorporation of Visual Basic Script and JavaScript into Windows served this niche to a certainextent, but never really brought parity between the GUI experience and the command-line experience.Since these scripting languages interact with the operating system through a subset of COM, and a GUIapplication can use all of COM, call the Win32 API, and (in the case of certain programs such as TaskManager) call directly into the native kernel API, the capabilities of Windows scripts were alwayseclipsed by what was provided in the GUI.But back to the demo: People filed into the room, a pair of engineers behind the podium broke the iceby joking about the PA system, the lights dimmed, and they started the show. The new MMC prototype,they revealed, was a GUI that used a command-line engine as its API layer. Every node expansion becamea query, every ‘‘OK’’ click became a command, and every action taken by the GUI operator was displayedas script at the bottom of the screen with 100% fidelity. Old engineers shifted nervously in their seats,senior managers sat entranced with dollar signs in their eyes, and the caterer, noticing the direction ofeveryone’s eyes, palmed an hors d’oeuvre and went outside to smoke a cigarette.This demo ushered in what, in the following three years, would become Windows PowerShell.Version 1, available for download on the web and as an optional component on Windows Server 2008,provides a rich programming environment for users of every stripe, and for the first time gives Windowsusers a consistent glide path from the command-line experience all the way to COM and beyond.This book is intended for the PowerShell snap-in and host developer audience, and introduces the readerto PowerShell programming from the API level. Written by members of the PowerShell v1.0 team, itcovers development of cmdlets, providers, snap-ins, hosting applications, and custom host implementations in greater depth than the SDK documentation.Enjoy.Page xvii

Kumaravelflast.texV2 - 01/07/200810:54pmPage xviii

Kumaravelfintro.tex V2 - 01/08/200812:14amIntroductionConventionsTo help you get the most from the text and keep track of what’s happening, we’ve used a number ofconventions throughout the book.Boxes like this one hold important, not-to-be-forgotten information that is directlyrelevant to the surrounding text.Notes to the current discussion are offset and placed in italics like this.As for styles in the text: We highlight new terms and important words when we introduce them. We show keyboard strokes like this: Ctrl A. Filenames, URLs, and code within the text appear like so: persistence.properties. We present code in two different ways:We use a monofont type with no highlighting for most code examples.We use gray highlighting to emphasize code that’s particularly importantin the present context.Source CodeAs you work through the examples in this book, you may choose either to type in all the code manually orto use the source code files that accompany the book. All of the source code used in this book is availablefor download at www.wrox.com. Once at the site, simply locate the book’s title (either by using the Searchbox or by using one of the title lists) and click the Download Code link on the book’s detail page to obtainall the source code for the book. Because many books have similar titles, you may find it easiest to searchby ISBN; this book’s ISBN is 978-0-470-17393-0.Once you download the code, just decompress it with your favorite compression tool. Alternatively, youcan go to the main Wrox code download page at www.wrox.com/dynamic/books/download.aspx to seethe code available for this book and all other Wrox books.Page xix

Kumaravelfintro.tex V2 - 01/08/2008IntroductionErrataWe make every effort to ensure that there are no errors in the text or in the code. However, no one isperfect, and mistakes do occur. If you find an error in one of our books, such as a spelling mistake or afaulty piece of code, we would be very grateful for your feedback. By sending in errata, you may saveanother reader hours of frustration, and at the same time you will be helping us provide even higherquality information.To find the errata page for this book, go to www.wrox.com and locate the title using the Search box or oneof the title lists. Then, on the book details page, click the Book Errata link. On this page you can view allerrata that has been submitted for this book and posted by Wrox editors. A complete book list, includinglinks to each book’s errata, is also available at www.wrox.com/misc-pages/booklist.shtml.If you don’t spot ‘‘your’’ error on the Book Errata page, go to www.wrox.com/contact/techsupport.shtml and complete the form there to send us the error you have found. We’ll check the informationand, if appropriate, post a message to the book’s errata page and fix the problem in subsequent editionsof the book.p2p.wrox.comFor author and peer discussion, join the P2P forums at p2p.wrox.com. The forums are a Web-based system for you to post messages relating to Wrox books and related technologies and to interact with otherreaders and technology users. The forums offer a subscription feature to e-mail you topics of interest ofyour choosing when new posts are made to the forums. Wrox authors, editors, other industry experts,and your fellow readers are present on these forums.At http://p2p.wrox.com you will find a number of different forums that will help you not only as youread this book, but also as you develop your own applications. To join the forums, just follow these steps:1.2.3.Go to p2p.wrox.com and click the Register link.4.You will receive an e-mail with information describing how to verify your account andcomplete the joining process.Read the terms of use and click Agree.Complete the required information to join as well as any optional information you wish toprovide and click Submit.You can read messages in the forums without joining P2P but in order to post your own messages, youmust join.Once you join, you can post new messages and respond to messages other users post. You can readmessages at any time on the Web. If you would like to have new messages from a particular forume-mailed to you, click the Subscribe to this Forum icon by the forum name in the forum listing.For more information about how to use the Wrox P2P, be sure to read the P2P FAQs for answers toquestions about how the forum software works as well as many common questions specific to P2P andWrox books. To read the FAQs, click the FAQ link on any P2P page.xx12:14amPage xx

Kumaravelc01.texV2 - 01/07/2008Introduction to PowerShellWelcome to Windows PowerShell, the new object-based command-line interface shell and scriptinglanguage built on top of .NET. PowerShell provides improved control and automation of IT administration tasks for the Windows platform. It is designed to make IT professionals and developersmore productive.Several books that introduce end-user IT professionals to Windows PowerShell are already available, but PowerShell development from the perspective of cmdlet, provider, and host developershas gone largely unmentioned. This book attempts to fill that gap by introducing the reader to theconcepts, components, and development techniques behind building software packages that leverage Windows PowerShell. This book is written for developers who want to extend the functionalityof Windows PowerShell and extend their applications using PowerShell.Traditionally, when developers write a command-line utility, they have to write code for parsingthe parameters, binding the argument values to parameters during runtime. In addition, they haveto write code for formatting the output generated by the command. Windows PowerShell makesthat easy by providing a runtime engine with its own parser. It also provides functionality thatenables developers to add custom formatting when their objects are displayed. By performingthe common tasks associated with writing command-line utilities, Windows PowerShell enablesdevelopers to focus on the business logic of their application, rather than spend development timesolving universal problems.Windows PowerShell Design PrinciplesWindows PowerShell was designed in response to years of customer feedback about the administrative experience on Microsoft Windows. Early on, many users asked why some of the traditionalUnix shells weren’t licensed and included in Windows, and it became apparent that the right answerwas to produce a whole new kind of shell that would leave these legacy technologies behind. Thisthinking was distilled into four guiding principles that provided the foundation for PowerShell’sdesign effort.11:14amPage 1

Kumaravelc01.texV2 - 01/07/2008Chapter 1: Introduction to PowerShellPreserve the Customer’s Existing InvestmentWhen a new technology is rolled out, it takes time for the technology to be adopted. Moreover, customersare likely to have already invested a lot in existing technologies. It’s unreasonable to expect people tothrow out their existing investments, which is why PowerShell was designed from the ground up to becompatible with existing Windows Management technologies.In fact, PowerShell runs existing commands and scripts seamlessly. You can make use of PowerShell’sintegration with COM, WMI, and ADSI technologies alongside its tight integration with .NET. Indeed,PowerShell is the only technology that enables you to create and work with objects from these varioustechnologies in one environment. You can see examples of this and other design principles in a quicktour of PowerShell later in the chapter.Provide a Powerful, Object-Oriented ShellCMD.exe and other traditional shells are text-based, meaning that the commands in these shells take textas input and produce text as output. Even if these commands convert the text internally into objects, whenthey produce output they convert it back to text. In traditional shells, when you want to put togethersimple commands in the pipeline, a lot of text processing is done between commands to produce desiredoutput. Tools such as SED, AWK, and Perl became popular among command-line scripters because oftheir powerful text-processing c

PowerShell script in 2004. When he's not working (or writing about work) he's either sailing or playing with fire in the backyard. You can contact him at. jwh@microsoft.com. Michael Naixin Li. is the Senior Test Lead working on the Windows PowerShell team and currently oversees the testing of Windows PowerShell 2.0.