Parameter Types and Options

Modules support several different parameter types and all of them support a few different options which we will see outlined in this section.

Common Options to All Types

There are some options for parameters that are common to all the supported types. Some of the more obvious ones would be the Caption and Description attributes. The caption is used as the prompt for the parameter value when editing a step, whereas the description is used to provide the longer more detailed narrative about how the parameter is used when the information button is clicked on for the parameter while in the editor.

A parameter is normally configured to not be required when it is specified. This behavior can be explicitly defined by supplying the ParameterOptions: ParameterOptions.Required attribute as needed. When this is true, then when the job module is edited, the parameter will be shown as being required. If the value is not specified for a required parameter, then the job will not be able to be enabled or run until it is supplied.

Parameters can be used for sending values into a module, as well as a way for a module to emit a value upon completion. The emitted value can then be used in modules in other steps of a job. The way a parameter defines this behavior is by defining the value for its ModuleParameterDirection attribute. Parameters that only define a value for input into the module would be set to In, where a parameter that only emits a value when the module completes execution is set to Out. There also can be times when you want to use a parameter of the same name as both an input and an output of the module. This can be done by specifying that the parameter is set to InOut.

The attribute named Default is also common to all types but does behave slightly differently for each because its value is always going to be a string value. This attribute does exactly what you might imagine in that it provides a default value for the parameter when creating a new entry unless the value is overridden when defining or editing the values in a job step. Because this value is always a single string, any parameter that is not a string type, must use a value that can be successfully parsed to the native type. Thus, if a default is specified as “abc” for a numeric type, then the default value will not work for that type. A successful default for a numeric type might look like “123”.

Additional parameters have effect based on the type chosen for the parameter. The supported types are a subset of the base .NET variable types.

String

The string type is the most used parameter type. When a type is a string, it can accept a freeform value that is not constrained except if other attributes are added for the parameter. If the ParameterOptions.Password is specified, when the value is entered in the editor the characters are obscured from view.

List of Strings

The list of string type is used for a parameter when the input is expected to be a multiple line list of values. A list of filenames is an example of when this type is used. There are no additional attributes that affect this type of parameter.

Numeric

The various numeric types in the .NET Framework are all treated similarly here and therefore we will talk about them all as a single type. There is a trio of attributes for the numeric types that are useful. The first, DecimalPlaces, affects how the control for the numeric value allows input and formatting of the value. The other two MinValue and MaxValue allow you to define a lower and/or upper limit to the value for the parameter. Either one, or both, of these attributes can be specified. In the parameter editor, only valid numeric values will be able to be entered into the control.

DateTime

The datetime type is used for a parameter when the input is expected to be a Date. The control for this type in the parameter editor only allows for date values to be specified. It does not currently support the time component of the .NET Framework’s intrinsic DateTime type. There are no additional attributes that affect this type of parameter. In the parameter editor, the control displays and formats the date correctly as well as only allowing entry of a valid date.

Boolean

The boolean type is used as a parameter when only a true or false state is wanted for the parameters value. The parameter editor displays these values as a checkbox control.

Enum

The enum type is used as a parameter type when one item of a defined set of items should be selected as the valid value. The parameter editor displays these as a dropdown list control. If a default value is not specified, the control will not have an item selected initially for new entries. If the default is provided, it should match the stringified value of the enum.

Flags

The enum type can also be used when you need to select multiple options from a defined set of items. In this case the enum must be defined as a set of flags using the [Flags] attribute on the enum definition. The parameter editor displays these as a multiple selection control with convenient options for quickly selecting or deselecting all items. If the default is provided, it should match the stringified value of the individual items in the enum.

Type and Attribute combinations

Here we see an overview of where the combinations of types and attributes can be used together:

The variety of options for creating parameters to your own custom modules provides flexibility for many types of uses. For a more hands on option for trying the various parameters types, you can try the sample project available at the article below.

https://kb.jobserver.net/Q100031