System.CommandExecuterProbe

Article
05/16/2012

Applies To: Operations Manager 2007 R2

The System.CommandExecuterProbe module is a probe action module type that is used to execute a batch file or an executable file from the command prompt. A module of this type accepts any type of data as the input data type, and it outputs System.CommandOutput data.

Usage

This module type can be used to run scripts by specifying Cscript.exe as the command to run and passing suitable configuration. However, you should use the Microsoft.Windows.ScriptProbeAction module type instead for this purpose because it provides a pre-built composition that simplifies the parameters and is tailored for script execution scenarios.

The difference between this module type and the System.Secure.CommandExecuterProbe module type is that the CommandLine parameter is overrideable.

Note

The System.CommandExecuterProbe module does not support batching. Multiple System.CommandExecuterProbe modules in a workflow will run serially, rather than in parallel.

A probe module type should not be used when any aspect of the system is being changed. If you want to change some aspect of the system, use the System.CommandExecuter write action module.

Type Definition

<ProbeActionModuleType ID="System.CommandExecuterProbe" Accessibility="Public" PassThrough="false" Batching="false">
  <Configuration>
    <IncludeSchemaTypes>
      <SchemaType>System.CommandExecuterSchema</SchemaType>
    </IncludeSchemaTypes>
    <xsd:element name="ApplicationName" type="xsd:string"/>
    <xsd:element name="WorkingDirectory" type="xsd:string"/>
    <xsd:element name="CommandLine" type="xsd:string"/>
    <xsd:element name="SecureInput" minOccurs="0" maxOccurs="1">
      <xsd:simpleType>
        <xsd:restriction base="xsd:string">
          <xsd:maxLength value="256"/>
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:element>
    <xsd:element name="TimeoutSeconds" type="xsd:integer"/>
    <xsd:element name="RequireOutput" type="xsd:boolean"/>
    <xsd:element minOccurs="0" maxOccurs="1" name="Files" type="CommandExecuterFilesType"/>
    <xsd:element minOccurs="0" maxOccurs="1" name="DefaultEventPolicy" type="CommandExecuterEventPolicyType"/>
    <xsd:element minOccurs="0" maxOccurs="1" name="EventPolicy" type="CommandExecuterEventPolicyType"/>
  </Configuration>
  <OverrideableParameters>
    <OverrideableParameter ID="TimeoutSeconds" Selector="$Config/TimeoutSeconds$" ParameterType="int"/>
  </OverrideableParameters>
  <ModuleImplementation Isolation="Any">
    <Composite>
      <MemberModules>
        <ProbeAction TypeID="System.CommandExecuterProbeBase" ID="Command">
          <ApplicationName>$Config/ApplicationName$</ApplicationName>
          <WorkingDirectory>$Config/WorkingDirectory$</WorkingDirectory>
          <CommandLine>$Config/CommandLine$</CommandLine>
          <SecureInput>$Config/SecureInput$</SecureInput>
          <TimeoutSeconds>$Config/TimeoutSeconds$</TimeoutSeconds>
          <RequireOutput>$Config/RequireOutput$</RequireOutput>
          <Files>$Config/Files$</Files>
          <OutputType>System.CommandOutput</OutputType>
          <DefaultEventPolicy>$Config/DefaultEventPolicy$</DefaultEventPolicy>
          <EventPolicy>$Config/EventPolicy$</EventPolicy>
        </ProbeAction>
      </MemberModules>
      <Composition>
        <Node ID="Command"/>
      </Composition>
    </Composite>
  </ModuleImplementation>
  <OutputType>System.CommandOutput</OutputType>
  <InputType>System.BaseData</InputType>
</ProbeActionModuleType>

Parameters

The System.CommandExecuterProbe module supports the following configuration parameters:

Parameter	Type	Overrideable	Description
ApplicationName	String	False	Contains the full path to the executable file or the batch file to run.
WorkingDirectory	String	False	Specifies the working directory to use during execution. This can be left empty if the current directory is to be used.
CommandLine	String	False	Contains the full command-line arguments to pass to the application.
SecureInput	String	False	Optional. Contains data that is to be passed to the command in a secure method. This parameter is used to provide passwords to a batch file during execution. The string length must not exceed 256 characters.
TimeoutSeconds	Integer	True	Specifies the time the script is allowed to execute before being closed by the module and marked as failed.
RequireOutput	Boolean	False	Defines whether output is expected from the application or batch file. If it is set to true, the module logs an error to the event log if no output is returned by the application or batch file.
Files	CommandExecuterFilesType	False	Optional. Contains one or more text-based scripts or batch files.
DefaultEventPolicy	CommandExecuterEventPolicyType	False	Contains the default event policy to be applied if no event policy is specified. This parameter is optional, and it should be set only when defining a new composite from the module type.
EventPolicy	CommandExecuterEventPolicyType	False	Optional. Controls the success or failure result of the module

ApplicationName

This parameter defines the full path to the executable file that will be run. It is possible to use variable path names (such as %windir%) as part of the application path. The parameter can contain static values or use $Target values, as required.

The following code shows an example that executes IPConfig:

<ApplicationName>%WINDIR%\System32\IPCONFIG.EXE</ApplicationName>

WorkingDirectory

The WorkingDirectory parameter specifies the directory that is used when starting the application. If the full path is not specified in the ApplicationName parameter, this directory must be specified.

This parameter is required as part of the configuration, but it can be empty.

CommandLine

The value that is specified in CommandLine is passed to the application that is specified in the ApplicationName parameter as command-line parameters. This element can contain static values or $Target values.

SecureInput

The SecureInput parameter is primarily used to pass secure data, such as passwords, into the application or batch file through StdIn. Passing this data in the CommandLine parameter is not secure and should not be done. Passwords are passed by using $RunAs syntax.

TimeoutSeconds

The TimeoutSeconds parameter specifies the maximum length of time that the command can run before being halted. If the command exceeds this timeout and is halted, the module reports a data loss on execution and an event is logged to the local Operations Manager event log.

For commands that are run as part of rule or monitor workflows, the timeout value should be less that the frequency with which the command runs on for a given instance.

RequireOutput

The RequireOutput parameter specifies whether output is required from the command. In monitoring and discovery workflows, this is parameter is almost always set to true. The workflow expects output and raises an error event in the local Operations Manager event log if no output is generated, depending on the event policy that is defined.

For information about the Files parameter, see CommandExecuterFilesType.

For more information about the DefaultEventPolicy and EventPolicy parameters, see CommandExecuterEventPolicyType.

Composition

The System.CommandExecuterProbe module is a composite module that contains the following member modules:

Workflow Run Order	Module Type	Usage
1	System.CommandExecuterProbeBase	Internal module.

Module Type	Usage
System.CommandExecuter	Used to execute a command that changes the system in some way. This module type takes the same configuration as the probe module type that is defined in this topic.
System.Secure.CommandExecuterProbe	Used to execute a command that does not change the system in some way. This module type takes the same configuration as the probe module type that is defined in this topic. The CommandLine parameter for this module type can be overridden.
System.CommandExecuterDiscoveryDataSource	Used for a command execution that outputs discovery data. Modules of this type are used only in discovery workflows.
System.CommandExecuterPropertyBagSource	Used for a command execution that outputs property bag data rather than command output.
Microsoft.Windows.ScriptProbeAction	Used to execute a Windows Script Host script.

External Module References

None.

Sample

The following code shows a simple task that executes the IPConfig command and passes a single value to the command line:

<Task ID="Microsoft.Samples.IPConfig" Target="Windows!Microsoft.Windows.Computer" Accessibility="Internal">
  <Category>Operations</Category>
  <ProbeAction ID="Command" TypeID="System!System.CommandExecuterProbe">
    <ApplicationName>%WINDIR%\System32\IPCONFIG.EXE</ApplicationName>
    <WorkingDirectory/>
    <CommandLine>/ALL</CommandLine>
    <TimeoutSeconds>30</TimeoutSeconds>
    <RequireOutput>true</RequireOutput>
    <Files/>
  </ProbeAction>
</Task>

The following code shows a more complex task example from the SQL 2005 management pack that executes a DBCC command, using a number of target properties:

<Task ID="Microsoft.SQLServer.2005.Database.DBCC.CheckAlloc" Target="SQL2005Core!Microsoft.SQLServer.2005.Database" Accessibility="Internal">
  <Category>Maintenance</Category>
  <ProbeAction ID="PA" TypeID="System!System.CommandExecuterProbe">
    <ApplicationName>$Target/Host/Property[Type="SQL!Microsoft.SQLServer.DBEngine"]/ToolsPath$\Binn\OSQL.EXE</ApplicationName>
    <WorkingDirectory>$Target/Host/Property[Type="SQL!Microsoft.SQLServer.DBEngine"]/ToolsPath$\Binn</WorkingDirectory>
    <CommandLine>-S $Target/Host/Property[Type="SQL!Microsoft.SQLServer.DBEngine"]/ConnectionString$ -E -Q "DBCC CHECKALLOC('$Target/Property[Type="SQL!Microsoft.SQLServer.Database"]/DatabaseName$')"</CommandLine>
    <TimeoutSeconds>300</TimeoutSeconds>
    <RequireOutput>true</RequireOutput>
  </ProbeAction>
</Task>

The following example shows the use of a file that is a simple PowerShell script.

<Task ID="Microsoft.Samples.PSTask" Accessibility="Internal" Target="Windows!Microsoft.Windows.Computer">
  <Category>Operations</Category>
  <ProbeAction ID="PS" TypeID="System!System.CommandExecuterProbe">
    <ApplicationName><![CDATA[%systemroot%\System32\windowspowershell\v1.0\powershell.exe]]></ApplicationName>
    <WorkingDirectory/>
    <CommandLine><![CDATA[ -Command ".\GetService.ps1"]]></CommandLine>
    <TimeoutSeconds>20</TimeoutSeconds>
    <RequireOutput>true</RequireOutput>
    <Files>
      <File>
        <Name>GetService.ps1</Name>
        <Contents>
          Get-Process
        </Contents>
        <Unicode>false</Unicode>
      </File>
    </Files>
  </ProbeAction>
</Task>

Information


Module Type	ProbeActionModuleType
Input Type	System.BaseData
Output Type	System.CommandOutput
Implementation	Composite
Library	Microsoft.Windows.Library