11/11/2008

Mobile Device Manager (MDM) Shell, built on Microsoft Windows PowerShell technology, provides a powerful command-line interface and associated command-line plug-ins for MDM that enable the automation of administrative tasks.

Administrators can use MDM Shell to manage MDM. MDM Shell can perform every task that MDM Console performs, and more. In fact, when you use MDM Console to run an administrative task, one or more MDM Shell cmdlets actually performs this task. For information regarding the administrator security roles required to use these cmdlets, see Server Administrator Roles in MDM.

Note:
MDM software distribution functions and Group Policy extensions are not based on cmdlets. Therefore, these functions are not available in MDM Shell.

MDM Shell uses an object model that is based on the Microsoft .NET Framework instead of a text-based model. This object model enables MDM Shell cmdlets to apply the output from one command to other later commands.

Cmdlets

A cmdlet, pronounced "command-let", resembles built-in commands in other shells. For example, the dircommand found in Cmd.exe. Similar to these familiar commands, you can call cmdlets directly from the command line in MDM Shell and run the cmdlets under the context of the shell, instead of as a separate process.

Usually, cmdlets perform repetitive administrative tasks. MDM Shell provides cmdlets for management tasks specific to MDM. These cmdlets are available in addition to the standard administrative cmdlets included in the basic Microsoft Windows PowerShell design.

Important:
To access MDM cmdlets, on the Microsoft System Center Mobile Device Managerprogram menu, select Mobile Device Manager Shell.

All cmdlets in MDM Shell are presented in verb-noun pairs. The verb-noun pair is always separated by a hyphen (-), without spaces, and the cmdlet nouns are always singular. Verbs refer to the action that the cmdlet takes. Nouns refer to the object on which the cmdlet takes action. For example, in the New-WipeRequestcmdlet, the verb is New, and the noun is WipeRequest. All MDM Shell cmdlets that manage a particular feature share the same noun.

Cmdlet Parameters

Most cmdlets rely on parameters. Parameters are elements that provide information to the cmdlet. Either the parameters identify an object and its attributes to act upon, or the parameter controls how the cmdlet performs its task. The name of the parameter starts with a hyphen (-), followed by the value of the parameter. In the following example, the hyphen in front of the parameter name tells MDM Shell that the word immediately following the hyphen is a parameter that passes to the cmdlet. The next separate word after the parameter is the value of that parameter.

Copy Code
New-WipeRequest -deviceID device1

A positional parameteris a parameter that lets you specify the value of the parameter without specifying the name of that parameter. A parameter is a positional parameter if the Positionattribute of the parameter is an integer. This integer indicates the position on the command line where the cmdlet can find the value of the parameter. The following example shows that for the New-WipeRequestcmdlet, the Positionattribute of the DeviceIDparameter is 1 so that the cmdlet may be specified as follows:

Copy Code
New-WipeRequest device1

In the syntax definition for the following cmdlet, the parameter name appears in square brackets to indicate that the name is optional.

Copy Code
New-WipeRequest [-DeviceId] <DeviceIdParameter>

If a parameter is not a positional parameter, it is considered a named parameter. You must specify the parameter name and parameter value for named parameters.

Boolean Parameters

Boolean parametersare used in MDM Shell to determine whether a feature or option is enabled, $True, or not enabled, $False. The value that you assign to a Boolean parameter is stored in the configuration of the object that you are modifying. When you supply a value to a Boolean parameter, you must use the values $Trueor 1, or $Falseor 0. The dollar sign ($) must be included with $Trueand $False.

Switch Parameters

Switch parametersare used in MDM Shell to set a state for the immediate running of a command. This state is not saved between commands. Switch parameters resemble Boolean parameters but serve different purposes and require different syntax. The standard WhatIfand Confirmparameters are examples of switch parameters.

Switch parameters do not require a value. By default, if you specify a switch parameter on a command line without a value, the parameter evaluates to $True. Switch parameters, such as Boolean parameters, accept only $Trueor 1, or $Falseor 0. The dollar sign ($) must be included with $Trueand $False. Unlike Boolean parameters, you must include a colon (:) between the switch parameter name and switch value.

The following command examples perform the same function of displaying all pending enrollment requests with the enrollment password values. Not specifying a value with the IncludePasswordparameter is the same as entering the value $True.

Copy Code
Get-EnrollmentRequest -IncludePassword
Get-EnrollmentRequest -IncludePassword:$true

When you display Help with the Get-Help cmdlet, if the parameter is a switch parameter, the parameter type does not show.

Common Parameters

Common parametersare parameters that, in addition to the standard administrative cmdlets in MDM Shell, also add automatically to all commands. These parameters perform functions that can be used with, or used by, the commands that they run against. In addition, the WhatIfand Confirmparameters may be added to some cmdlets. The following lists all the common parameters that are available in MDM Shell.

WhatIf

This parameter instructs the command to which it is applied to run, but only to display the objects that would be affected by running the command, and what changes would be made to those objects. The domain does not actually change any of these objects. When you use the WhatIfparameter, you can see whether the changes that would be made to those objects match your expectations, without the worry of modifying those objects.

Confirm

This parameter instructs the command to which it is applied to stop processing before any changes are made. The command then prompts you to acknowledge each action before it continues. When you use the Confirmparameter, you can step through changes to objects to make sure that changes are made only to the specific objects that you want to change.

Verbose

This parameter instructs the command to provide detailed information about the operation.

Debug

This parameter instructs the command to provide detailed information about the operation.

ErrorAction

This parameter controls the behavior of the command when an error occurs. Values are as follows:

NotifyContinue, the default value

NotifyStop

SilentContinue

SilentStop

Inquire, asks the user what to do

ErrorVariable

This parameter specifies the name of the variable that the command uses to store errors encountered during processing. This variable is populated in addition to $ERROR.

OutVariable

This parameter specifies the name of the variable that the command uses for objects that are output from this command. This is the same as piping the command to Set-Variable <name> -Passthru:$true.

Cmdlet Pipelines

Pipeliningin MDM Shell is the act of one cmdlet that uses the output from another cmdlet when it performs an operation. Pipelining is achieved by using the pipe (|) symbol. All verbs in the same noun-cmdlet set can use piped information from another command. Some noun-cmdlet sets also let you pass data through the pipeline to another noun-cmdlet set.

For more information about pipelining, run the following command in MDM Shell:

Copy Code
Get-Help About_Pipeline

Perform Multiple Actions with Pipelines

By using pipelining to string together the actions of two or more cmdlets, MDM Shell has the power of composition. This lets you take smaller components and convert them into something more powerful. For example, you can use one cmdlet to collect data, pass that data to a second cmdlet to filter the data to a subset, and then pass that data to a third cmdlet to act on the subset only.

Process Data from Another Cmdlet with Pipelines

You can use pipelining to process data that is output by a cmdlet. For example, run the following command for a list of all failed wipe requests.

Copy Code
Get-WipeRequest | Where-Object {$_.status -eq "Failed"} |
Format-List

In this example, the Get-WipeRequestcmdlet passes objects to the Where-Objectcmdlet. The Where-Objectcmdlet picks out the objects that have a property named Status, with a value of FAILED.

In this example, the Statusproperty is preceded by the $_variable. MDM Shell automatically creates this variable to store the current pipeline object. The Where-Objectcmdlet then sends these objects to the Format-Listcmdlet to display.

Report Errors That Occur with Pipelines

To report errors, you can use the error pipeline. The error pipeline lets you report errors as a command is running. This means that you do not have to wait until the command has finished running, or put the error information in the standard result pipeline. The Write-Errorcmdlet writes its arguments to the error pipeline.

Tab Completion

Tab completion enables you to reduce how much typing is required when you use MDM Shell. When you type a partial cmdlet name, press the TAB key and MDM Shell will complete the cmdlet name if it finds a matching cmdlet. If MDM Shell finds multiple matching cmdlet names, each cmdlet name will cycle through as you press the TAB key. When you use tab completion with cmdlet names, you must also supply the verb and the hyphen (-).

See Also