Microsoft Command Line Standard

Radhika Tadinada [MSFT]

The Microsoft Command Line Standard is now published HERE. I wrote the draft of this document (Dean Tsaltas did the editing) to define the operational standard for any command line tool independent of the technology that is implemented in. Clearly the preferred implementation is Windows PowerShell. There is no cheaper way to implement the standard than by providing PowerShell Cmdlets (because the PowerShell engine implements the standards for you). That said, as long as you implement the standards in this document, you’ll be delivering our common customers a common experience and that is what counts at the end of the day. I really like the structure of the document because it provides an introduction and then does multiple passes on the guidance with progressively more information. The first pass is very pithy and is meant to fit one or two pieces of paper that you can keep next to your keyboard. The next pass provides details about the guidance. The last pass is a series of Appendixes with very concrete detailed information about the requirements. I hope you like the structure. Here is the Introduction and the first pass of the guidelines so you get a feel for the content. NOTE: PowerShell V1.0 implements almost all of this standard but not 100% (in particular the support for TCSV is absent in V1). (“To ship is to choose.”) Joel pointed out (in a comment and then on his BLOG) a mismatch between the standard verbs in this document and the ones we posted earlier on this blog (HERE). The command line standard needs to be updated. We thought it was up to date but we were wrong – apologizes. We’ll update it in a couple of weeks with these and the new verbs as well. 10,000 thanks to Joel for pointing this out! Also – thanks to jmanning for pointing out my typo (now corrected). Cheers! Jeffrey Snover [MSFT] Windows Management Partner Architect Visit the Windows PowerShell Team blog at: http://blogs.msdn.com/PowerShell Visit the Windows PowerShell ScriptCenter at: http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx Introduction In order to provide a consistent, composable user experience, across a wide range of commands, this document provides guidance on:

1. Consistent verb and parameter naming conventions. 2. Consistent command syntax 3. Common behaviors. 4. Consistent error messages and exit codes. 5. Schema-enhanced data-streams and formatting. This document builds upon the traditional command line compositional model. That traditional model had the following three characteristics:

• Commands are standalone processes that accept a sequence of text parameters (that might have been typed on a command line), accept data from STDIN, write results to STDOUT, write error messages to STDERR, and exit with a code indicating success or failure. • Commands are focused on performing specific operations. The user composes a sequence of commands to implement a task or user-scenario. • Composition is achieved by picking out the important elements of one command’s output and providing as parameters or data to another command. If you create command-line tools that have these three characteristics, you will have achieved UNIX level interoperability. Building upon that, there are Enhanced and Optimal levels of interoperability. This document primarily focuses on the Optimal level of interoperability, but guidelines for Enhanced interoperability are available in Appendix H – Enhanced Interoperability Guidance . Enhanced interoperability provides a stepping stone for existing commands. As a first step, you can elevate them to Enhanced interoperability on the way to achieving Optimal interoperability. This document is structured as a progressive disclosure: The Summary List of Guidance section is a two page summary. The Details section provides details and background for each guideline in the summary. The Appendixes provide reference material necessary to implement the guidelines. Summary List of Guidance Command Names Required:

• Command names must be well-formed names consisting of a noun and a verb in the form: verb-noun. Verbs Required:

• Commands must use verbs from the list of standard verbs in Appendix A. Recommended:

• Developers should implement as many verbs in the defined Verb groupings (Verb Sets) as makes sense for their feature. Noun Names Recommended:

• Commands should avoid using the noun names Windows PowerShell has reserved (See Section 3.3 Nouns). • Commands should use their product or feature name (or abbreviation) to prefix their noun. Consistent Syntax Required:

• Commands must use the “-” character for parameter delimitation; a colon (:) or whitespace to separate the parameter name and its arguments and a comma (,) to separate multiple values within an argument. Input Required:

• Commands must accept text or CliXml input (using CliXmlDataStream Schema defined in Appendix E – Standardized Data Schema ) in STDIN. Recommended:

• Commands should accept Typed-CSV (TCSV) input in STDIN. • Commands should provide a –InputFormat [XML | TCSV | TEXT ] parameter to allow the user to identify what type of data will be coming in on STDIN. Parameters Required:

• Commands must support -?, –Help, -Version, –Verbose, and –Debug for all commands. • Commands must support –WhatIf and -Confirm for any operation which has a side-effect. • Commands must support –ErrorAction to determine behavior when errors occur. • Parameter names must be case-insensitive. • Passwords must not be accepted as a parameter argument. Recommended:

• Commands should choose parameters from the standards specified in Appendix B. • Commands should support –SelectProperty to specify which properties to output on STDOUT. • Commands should allow the user to specify just enough of a parameter name to disambiguate it from other parameter names and provide a one or two character shortcut to specify a verbose parameter name. • Commands should document their parameter names using Pascal casing rules (capitalize the start of every word). Targeting Recommended:

• Commands should use wildcard expansion for input globbing (Appendix D – Globbing). • Commands should use common parameters for specifying the target of a command (e.g. –Name, -ID, -File, -ComputerName) . • Commands should support multi-value targets as well as the –Include and –Exclude parameters. • Commands should support the –Filter parameter to specify a domain-specific query or filter. Output Formatting Required:

• Output must be written using the logic illustrated in Appendix I: Win32 code to write output to properly address globalization requirements. • Commands must support the –OutputFormat parameter to allow users to specify their desired format and the –OutputPreamble to configure schema enhanced data streams • Commands must use the value of the environmental variable CliDataStreamSchema when –OutputFormat is not specified. • Commands must support at least one format of schema-enhanced dataStreams (TCSV or CliXml). Recommended:

• Commands should support CliXml Appendix F – CliXmlDataStream Data Schema and Appendix K – Error Record Schema and tag which stream (DEBUG, ERROR, OUTPUT VERBOSE, or WARNING) the data came from. Commands must output CliXml when the environmental variable CliXmlStreams is set to TRUE. Commands must output XML using CliXmlDataStream schema. • Commands should support other XML schemas where there is a community of tools that will consume that output (e.g. CimXml). Exit, Errors, and Others Required:

• Error messages (as well as VERBOSE and DEBUG messages) must be written to STDERR. • Commands must terminate with an exit code indicating success (0) or failure (non-zero). Recommended:

• Commands should use the exit codes and standardized error messages defined in Appendix C. Augment those standardized error messages with specific detailed error messages. • Commands should tell the user (on STDERR) the Syntax of a command if they specify a syntactically invalid command.

0 comments

Discussion is closed.

Feedback usabilla icon