This topic is part of the System Center 2012 R2 Virtual Machine Role Authoring Guide.

The Microsoft System Center team has validated this content as of Revision #3.  We will continue to review any changes and periodically provide validations on later revisions as they are made.  Please feel free to make any corrections or additions to this content that you think would assist other users.



Introduction

Resource Definition and Resource Extensions can parameterize almost every property. You define parameters in the Resource Definition to allow the user to select different options when they provision a new resource. Values for the parameters are collected from the user through the View Definition, which is a file included in the Resource Definition package, and then used to populate the parameters in the Resource Definition. Parameters allow Resource Extensions to be reused for a variety of scenarios and for different tenants to customize their deployment.

The following diagram illustrates how parameter values are collected from the user using information in the View Definition and then used to passed to equivalent parameters in the Resource Definition. These values can then either be used for settings in the Resource Definition or be passed on to parameters required by the Resource Extension. The Resource Definition can also provide explicit values for the Resource Extension parameters.

Resource Parameters

Declaring Parameters

Parameters used in the Resource Definition File and Resource Extension File must be declared before use and specify a Name, Data Type, and Description. For Resource Definitions, parameters are declared in the ResourceParameters section. For Resource Extensions, parameters are declared in the ResourceExtensionParameters section.

To associate a parameter from the Resource Definition to the View Definition, you give it the same name. When a value is collected from the tenant, it is stored in a separate document called a Resource Definition Configuration. When the Virtual Machine Role is provisioned, this file is submitted with the Resource Definition. The value for each parameter in the Resource Definition Configuration is matched with the parameter with the same name in the Resource Definition. More information is provided below in the Resource Definition section of this guide.

The Resource Definition file includes a section for Resource Extension References. This section defines the Resource Extensions that are used by the Resource Definition and provides values for the Resource Extension’s parameters. The value from a parameter in the Resource Definition can be used to populate this Resource Extension parameter. This method allows you to collect information from the tenant and use it in both the Resource Definition and Resource Extension.

Using Parameters

You use the value of a parameter in a Resource Definition or Resource Extension with the following syntax.

[Param.ParameterName]

 

Data Types

Resource Parameters have fewer parameter types than View Parameters. Those types that use drop down controls in the View Definition are passed converted to strings. The following table lists the different Resource Parameter data types.

 

Data Type

Allowed Values

Examples

String

Any string

Declaration:

"ResourceParameters" : [
    {
        "Name" : "ComputerNamePattern",
        "Type" : "String",
        "Description" : "Computer Name Pattern",
    },
],

Value:

"ParameterValues" : "{
    \"ComputerNamePattern\" : \"web-###\",
}",

Int

Any integer

Declaration:

"ResourceParameters" : [
    {
        "Name" : "DefaultInstanceCount",
        "Type" : "Int",
        "Description" : "Default # instances",
    },
],

Value:

"ParameterValues" : "{
    \"DefaultInstanceCount\" : 5
}",

Bool

True

False

Declaration:

"ResourceParameters" : [
    {
        "Name" : "EnableTCP",
        "Type" : "boolean",
        "Description" : "Enables TCP",
    },
],

Value:

"ParameterValues" : "{
    \"EnableTCP\" : false,
}",

Credential

<UserName>:<Password>

Declaration:

"ResourceParameters" : [
    {
        "Name" : "JoinDomainCrede",
        "Type" : "Credential",
        "Description" : "Join Domain Creds",
    },
],

Value:

"ParameterValues" : "{
    \"JoinDomainCred\" : \"user:password\",
}",

 

 

Parameter Names

Parameter names have the following restrictions:

  • Parameter names must begin with a letter followed by any number of alphanumeric characters.
  • Parameter names are case sensitive.
  • Literal [ characters must be escaped using [[.
  • If the parameter type is a string, then you can use multiple parameters together to build a single string value.

You should leverage standard names when defining parameters so that you can reuse snippets from existing Resource Definitions, Resource Extensions, and View Definitions when creating a new Virtual Machine Role.

The following table provides the standard set of parameter names for Resource Definitions. These are organized according to the section of the Resource Definition File that are described below.

 

Property

Parameter

Hardware Profile

VMSize

[Param.VMRoleVMSize]

Scaleout Settings

InitialInstanceCount

[Param.VMRoleInitialInstanceCount]

MinimumInstanceCount

[Param.VMRoleMinimumInstanceCount]

MaximumInstanceCount

[Param.VMRoleMaximumInstanceCount]

UpgradeDomainCount

[Param.VMRoleUpgradeDomainCount]

OS Profile

ComputerNamePattern

If single instance, parameterize the name:

[Param.VMRoleComputerName]

If scale out, parameterize the prefix, followed by ###:

[Param.VMRoleComputerNamePrefix]

If allowing entire pattern to be entered, parameterize the whole name:

[Param.VMRoleComputerNamePattern]

AdminCredential

[Param.VMRoleAdminCredential]

Timezone

[Param.VMRoleTimezone]

Windows Operating System Profile

WorkgroupName

[Param.VMRoleWindowsWorkgroupName]

Domain

[Param.VMRoleWindowsDomainToJoin]

Domain join creds

[Param.VMRoleWindowsDomainJoinCredentials]

Linux Operating System Profile

LinuxOperatingSystemProfileDNSDomainName

[Param,VMRoleLinuxDNSDomainName]

SSHPublicKey

[Param,VMRoleLinuxSSHPublicKey]

Network Profile

NetworkAdapters.NetworkRef

[Param.VMRoleNetworkRef]

Storage Profile

OSImageNameVersion

[Param.VMRoleOSVHDImageNameVersion]

(need validator to format input as “Name:Version”)

Data Virtual Hard Disks

[Param.VMRoleDataVHDNameVersion01]

[Param.VMRoleDataVHDLUN01]

(repeat for 2, 3, …)

 

The following table provides the standard set of parameter names for Resource Extensions. These are organized according to the section of the Resource Extension File that are described below.

 

Property

Parameter

Linux Application Profile

None

None

Windows Application Profile

None

None

SQL Profile

SQLDeployments.DeploymentName

[Param.VMRoleSQLDeploymentName

SQLDeployments.InstanceName

[Param.VMRoleSQLInstanceName

SQLDeployments.InstanceID

[Param.VMRoleSQLInstanceID

SQLDeployments.SQLAuthenticationType

[Param.VMRoleSQLAuthenticationType

SQLDeployments.SQLSysAdminMemberList

[Param.VMRoleSQLSysAdminMemberList

SQLDeployments.SAPassword

[Param.VMRoleSQLSAPassword

SQLDeployments.SQLDeploymentCredential

[Param.VMRoleSQLDeploymentCredential

SQLDeployments.SQLAgentServiceCredential

[Param.VMRoleSQLAgentServiceCredential

SQLDeployments.SQLServiceCredential

[Param.VMRoleSQLServiceCredential

SQLDeployments.SQLReportingServiceCredential

[Param.VMRoleSQLReportingServiceCredential

Provisioning Scripts

None

None

Web Deploy Applications

ScriptCommands.ScriptCredential

[Param.VMRoleWebScriptCredential]

WebDeployParameters.ConnectionString

[Param.VMRoleWebConnectionString]

SQL Dac Applications

ScriptCommands.ScriptCredential.UserName

[Param.VMRoleSQLDacScriptCredentialUserName]

ScriptCommands.ScriptCredential.Password

[Param.VMRoleSQLDacScriptCredentialPassword]

SQLScriptCommands.DatabaseName

[Param.VMRoleSQLDacDatabaseName]

SQLScriptCommands.SQLAuthenticationType

[Param.VMRoleSQLDacSQLScriptCommands.SQLAuthenticationType]

SQLScriptCommands.ScriptCredential

[Param.VMRoleSQLDacSQLScriptCommands.ScriptCredential]

DacInstance

[Param.VMRoleSQLDacInstance]

SQLAuthenticationType

[Param.VMRoleSQLDacSQLAuthenticationType]

SQLDeploymentCredential

[Param.VMRoleSQLDacSQLDeploymentCredential]

SQLInstance

[Param.VMRoleSQLDacSQLInstance]

Script Applications

ScriptCommands.ScriptCredential

[Param.VMRoleSAScriptCommandsScriptCredential

ScriptCredential

[Param.VMRoleSAScriptCredential]

 

 

View Definition Parameters

The View Definition describes a set of parameters that are collected from the tenant when they provision a new Virtual Machine Role. The parameter type determines the following:

  • The value that can be assigned to the parameter.
  • The validations that may be performed against the parameter’s value.
  • The control that is presented in the dialog box to collect the value for the parameter.

The following table lists the parameter types that can be used in the View Definition Template:

 

Type

Validation

Control

Example

ComputerNamePattern

Required
Length (Min/Max)
RegEx

Text box

{
    Type : "ComputerNamePattern",
    Default: "MyMachine###"
}

String

Required
Length
RegEx

Text box

{
    Type : "String",
    Validation: {
        Required: true,
        MinLength: 10,
        MaxLength: 100,
        RegEx: "expression",
        Messages: {
            Required: "message",
            Length: "message",
            RegEx: "message"
        }
    }
}

Number

Required
Range

Text box

{
    Type: "Number",
    Default: "0.0",
    Validation: {
        Required: true,
        MinRange: 10,
        MaxRange: 100,
        Messages: {
            Required: "message",
            Range: "message"
        }
    }
}

Boolean

Required

Drop down

{
    Type : “Boolean”,
    Default: true
    Validation: {
        Required: true
        Messages: {
            Required: "message"
        }
    }
}

Option

Required

Drop down

{
    Type : "Option",
    Default: "val1",
    Options: [
        { "val1": "Value 1" },
        { "val2": "Value 2" }
    ],
    Validation: {
        Required: true
        Messages: {
            Required: "message"
        }
    }
}

Credential

Required
IsPasswordRequired
Portal password validation applies.

Text boxes

{
    Type : "Credential",
    Validation: {
        Required: true
        Messages: {
            Required: "message"
        }
    }
}

VMSize

Required

Drop down

{
    Type: "VMSize"
}

OSVirtualHardDisk

Required

Drop down

{
    Type: "OSVirtualHardDisk",
    ImageTags: {
        "WindowsServer2012",
        "R2",
        "SQLServer"
    }
}

DataVirtualHardDisk

Required

Drop down

{
    Type: "DataVirtualHardDisk"
}

Network

Required

Drop down

{
    Type: "Network"
}

OSTimeZone

Required

Drop down

{
    Type: "OSTimeZone"
}

 

See Also

Resource Definition Package
Resource Extension Package
VHD Tags
Installing a Virtual Machine Role
Sample Virtual Machine Role Packages
Virtual Machine Role Resource JSON Reference