System.CommandExecuter

  • Article

Applies To: Operations Manager 2007 R2

The System.CommandExecuter module is a write action module type that is used to run 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.ScriptWriteAction module type instead for this purpose because it provides a pre-built composition that simplifies the parameters and is tailored for script execution scenarios.

Note

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

A write module type can be used when any aspect of the system is being changed by the running program. If you do not want to change some aspect of the system with this module, use the System.CommandExecuterProbe probe action module.

Type Definition

<WriteActionModuleType ID="System.CommandExecuter" Accessibility="Public" Batching="false">
  <Configuration>
    <IncludeSchemaTypes>
      <SchemaType>System.CommandExecuterSchema</SchemaType>
    </IncludeSchemaTypes>
    <xsd:element name="ApplicationName" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="WorkingDirectory" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="CommandLine" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="SecureInput" minOccurs="0" maxOccurs="1" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <xsd:simpleType>
        <xsd:restriction base="xsd:string">
          <xsd:maxLength value="256" />
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:element>
    <xsd:element name="TimeoutSeconds" type="xsd:integer" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="RequireOutput" type="xsd:boolean" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element minOccurs="0" maxOccurs="1" name="Files" type="CommandExecuterFilesType" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element minOccurs="0" maxOccurs="1" name="DefaultEventPolicy" type="CommandExecuterEventPolicyType" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element minOccurs="0" maxOccurs="1" name="EventPolicy" type="CommandExecuterEventPolicyType" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
  </Configuration>
  <OverrideableParameters>
    <OverrideableParameter ID="TimeoutSeconds" Selector="$Config/TimeoutSeconds$" ParameterType="int" />
  </OverrideableParameters>
  <ModuleImplementation Isolation="Any">
    <Composite>
      <MemberModules>
        <WriteAction ID="Command" TypeID="System.CommandExecuterBase">
          <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>
        </WriteAction>
      </MemberModules>
      <Composition>
        <Node ID="Command" />
      </Composition>
    </Composite>
  </ModuleImplementation>
  <OutputType>System.CommandOutput</OutputType>
  <InputType>System.BaseData</InputType>
</WriteActionModuleType>

Parameters

The System.CommandExecuter module supports the configuration parameters described in the following table.

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 run 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

For information about the parameters of this module, see System.CommandExecuterProbe.

Composition

The System.CommandExecuter module is a composite module that contains the member module described in the following table.

Workflow Run Order Module Type Usage

1

System.CommandExecuterBase

Internal module.
Module Type Usage

System.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 cannot be overridden.

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 run a Windows Script Host script.

External Module References

The System.CommandExecuter module is a member of the module described in the following table.

Module Type Library Usage

Microsoft.Windows.ScriptWriteAction

Microsoft.Windows.Library

Runs system-altering scripts using cscript.exe.

Sample

The following code shows a simple task that runs the net start command to run a service:

<Task ID="Microsoft.BizTalk.Library.Tasks.StartESSO" Accessibility="Public" Enabled="true" Target="BZLib!Microsoft.BizTalk.Library.BizTalkGroup" Timeout="300" Remotable="false">
  <Category>Maintenance</Category>
  <WriteAction ID="WA" TypeID="System!System.CommandExecuter">
    <ApplicationName />
    <WorkingDirectory />
    <CommandLine>net start "ENTSSO" /y</CommandLine>
    <TimeoutSeconds>120</TimeoutSeconds>
    <RequireOutput>true</RequireOutput>
    <Files />
  </WriteAction>
</Task>

The following code shows a more complex task example from the SQL 2000 management pack that executes a Transact-SQL procedure:

<Task ID="Microsoft.SQLServer.2000.StopSQLServerMail" Target="SQL2000Core!Microsoft.SQLServer.2000.DBEngine" Accessibility="Internal" Enabled="true">
  <Category>Maintenance</Category>
  <WriteAction ID="WA" TypeID="System!System.CommandExecuter">
    <ApplicationName>$Target/Property[Type="SQL!Microsoft.SQLServer.DBEngine"]/ToolsPath$\Binn\OSQL.EXE</ApplicationName>
    <WorkingDirectory>$Target/Property[Type="SQL!Microsoft.SQLServer.DBEngine"]/ToolsPath$\Binn</WorkingDirectory>
    <CommandLine>-S $Target/Property[Type="SQL!Microsoft.SQLServer.DBEngine"]/ConnectionString$ -E -Q "xp_stopmail"</CommandLine>
    <TimeoutSeconds>300</TimeoutSeconds>
    <RequireOutput>true</RequireOutput>
    <Files />
  </WriteAction>
</Task>

Information

   

Module Type

WriteActionModuleType

Input Type

System.BaseData

Output Type

System.CommandOutput

Implementation

Composite

Library

Microsoft.Windows.Library