Guidelines for Community Extensions Advanced Functions

(Please note, under construction)

Naming Conventions

PowerShell's naming convention is Verb-SingularNoun. For example Get-VM where Get is a verb and VM is a singular noun. The singular noun convention means you don't define a cmdlet like Get-VMsOnHost since this introduces two separate concepts (the VMs and the Hosts they run on). Additionally, PowerShell defines a set of recommended verbs that you are encouraged to use.

There are exceptions to these rules, both in PowerShell products produced by Microsoft and other parties. In general though, it's best to stick as close to this basic naming guideline as possible.

In the Community Extensions there is an additional constraint placed on naming guidelines: to help identify commands as coming from the Community Extensions they must be prefaced with "Tke", which stands for "Toolkit Extensions".

Examples:
* Get-TkeVmxEntries
* Restart-TkeVMHost

If you are writing a Set-* function, you are encouraged to also write a Get-* cmdlet that will produce objects for the Set-* function to operate upon. Get-* cmdlets are important for selecting the objects on which users wish to operate, as well as other functions like creating reports.

Capitalization should follow the recommended practices for .NET code.

Defining Parameters

A full explanation of defining parameters can be found by typing help aboutfunctionsadvanced_parameters at your PowerShell prompt. For now here's an example with some commentary:
function Get-TkeDatastoreFile {
param(
	[Parameter(Mandatory=$true,ValueFromPipeline=$true,HelpMessage="Datastores to get files from")]
	[VMware.VimAutomation.Client20.DatastoreImpl[]]
	$datastore,

	[Parameter(HelpMessage="Subpath to search")]
	[string]
	$subpath = "",

	[Parameter(HelpMessage="If set to true, don't get the file size")]
	[switch]
	$noSize,

	[Parameter(HelpMessage="If set to true, don't get the file type")]
	[switch]
	$noType,

	[Parameter(HelpMessage="If set to true, don't get the file modification date")]
	[switch]
	$noModification
)


This code defines one parameter set. The first parameter, $datastore, is mandatory and is also accepted on the pipeline. The type of $datastore is an array of VMware.VimAutomation.Client20.DatastoreImpl objects, which helps PowerShell know whether a given object on the pipeline should be accepted or not. The second argumetn sets a default value of the empty string. The last 3 arguments, noSize, noType and noModification are switch parameters. For example, if this function is called as Get-TkeDatastoreFile -noType, $noType will be set to $true while $noSize and $noModification will both be set to $false.

If you're ever unsure about the type of an object, you can always call its GetType() method to find out what it is, for example:
> $str = "fdsa"
> $str.GetType()

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Begin, Process and End

Dealing with tasks

Supporting -Whatif and -Confirm

If you function changes system state it should support -Whatif and -Confirm. Examples include changing a system setting, creating a new object (like a VM) or removing an existing object. Adding -Whatif and -Confirm support is done with the CmdletBinding directive, for example:
[CmdletBinding(SupportsShouldProcess=$true,ConfirmImpact="high")]


If your function defines these, your function will have access to a variable called $psfunction that you can use to support -Whatif and -Confirm. All you need to do then is, before taking action that would change system state, make a call like this:
if (($psfunction.ShouldProcess($objectName, $message))) {
	// Change the system.
}


If the user has specified -Whatif, they will simply get a message showing them the object name and message. If -Confirm has been specified, and the functions ConfirmImpact setting is greater than or equal to than the user's $ConfirmPreference variable, they will be prompted to decide if the action should truly take place.

Documentation

Advanced functions can have documentation embedded in the module that is displayed when a user types help Your-AdvancedFunction.

For example, this code snippet defines help for the Defrobulate-Modulator cmdlet.
<#
.SYNOPSIS
Removes all frobulations from the system modulator.
.DESCRIPTION
Only use this command if you are a certified modulator technician.
.LINK
Frobulate-Modulator
#>
Function Defrobulate-Modulator {
	# Code withheld pending patent approval.
}


When the user types *help Defrobulate-Modulator at his prompt, the following is produced:
PS> help defrobulate-modulator
NAME
    Defrobulate-Modulator

SYNOPSIS
    Removes all frobulations from the system modulator.


SYNTAX
    Defrobulate-Modulator [<CommonParameters>]


DETAILED DESCRIPTION
    Only use this command if you are a certified modulator technician.


RELATED LINKS
    Frobulate-Modulator

REMARKS
    To see the examples, type: "get-help Defrobulate-Modulator -examples".
    For more information, type: "get-help Defrobulate-Modulator -detailed".
    For technical information, type: "get-help Defrobulate-Modulator -full".


Following is a list of all documentation sections.

Last edited Dec 31, 2008 at 5:25 PM by cartershanklin, version 1

Comments

No comments yet.