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.

 

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",     }, }",
Int	Any integer	Declaration: "ResourceParameters" : [      ], 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.

 

Web Deploy Applications

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
	[Param.VMRoleSQLAuthenticationType
SQLDeployments.SQLSysAdminMemberList	[Param.VMRoleSQLSysAdminMemberList
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: {  &ndiv>             Range: "message"         }     } }
Boolean	bsp;      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