Be kind to your consumer as it often turn out to be you that are the consumer, fill in a short description of what the PowerCommand is doing and how to use it. This is easy with the usage of the PowerCommandsAttribute, just apply them on the top of your class definition.
Now lets take a practical example...
You want to create a simple Command that converts a yaml file to json or xml format. Your choose to solve this with one Command that handles both this formats, you will use options. You can read more about how the class will look like here: Design your command
This is how the PowerCommandAttribute look like, to help the user consume this command.
When the user running this application and wants to now more about the Convert command, he or she just types either:
describe convert
Or use the help option
convert --help
And this help will be displayed:
[PowerCommandDesign( description: "Converting yaml format to json or xml format",
options: "!path|format",
example: "//Convert to json format|convert --path \"c:\\temp\\test.yaml\" --format json|//Convert to xml format|convert --path \"c:\\temp\\test.yaml\" --format xml")]
The user can use this command like this (note that argument and quotes are not described in the attribute because this command do not use them):
If you look close at the example above you see two options are declared like this !path and format the ! character before the option name tells the Core Runtime that this option requires a value and it will be validated before the command Run methods executes, if he user omits the path option value this will occur:
Describe your arguments, separate them with | use // to display a commented line over the actual argument.
Describe your quotes, separate them with | use // to display a commented line over the actual quote.
Suggestion will be added to the autocomplete functionality so the user could use tab to cycle trough the commands and commands with a suggested argument.
Describe your options, separate them with | use // to display a commented line over the actual option, all options that are described will also be used by the autocomplete functionality to help the user find the right option. Read more about options.
Describe your secrets that the commands needs, you probably want to declare a secret as required with ! character, in the sample above secret cnDatabase is marked as required.
[PowerCommandDesign( description: "Database command",
secrets: "!cnDatabase",
example: "//Get customers|customer")]
Read more about how to manage Secrets.
Describe examples on how to use the command, separate them with | use // to display a commented line over the actual example.
options, quotes, arguments and example all have a property on the PowerCommandAttribute, each item are separated with | and if you want to put a comment row before your item add this with the prefix //, if you look at the example it is used to describe two examples of usage.
example: "//Convert to json format|convert --path "c:\temp\test.yaml" --format json|//Convert to xml format|convert --path "c:\temp\test.yaml"
This will hopefully give you more understanding on how to describe your command and design them.
Read more about: