Parameters and Types [SPFSDK][VMROLE]

 

Applies To: Windows Azure Pack

Parameters are used by various object properties. Parameters are described by a name, a specified type, and a helpful description. To use a parameter on a property, use the [param.parameter_name] syntax. The value of the identified parameter is used when the object is read or run, which depends on its context.

Parameter

There are generally three parts to a parameter. First, the parameter is declared somewhere, as in a ResourceDefinition [SPFSDK][VMROLE] object or a ResourceExtension [SPFSDK][VMROLE] object. Second, the values for a parameter are provided externally from the declaration, such as the ResourceConfiguration [SPFSDK][VMROLE]. And finally, a parameter is used by another object property.

Declaration

Syntax

{
    "Name": "Name of the parameter",
    "Type": "Type of parameter ",
    "Description": "Description for the parameter"
}

Properties

Name	Type	Required	Default value	Description
Name	String	Yes	None	The name of the parameter.
Type	String	Yes	None	The type of parameter. The Parameter Types section describes the available parameter types.
Description	String	No	null	The publisher name of this resource extension.

Usage

The following code example demonstrates how to declare a parameter in a ResourceExtension [SPFSDK][VMROLE] object to hold the name of an instance of Microsoft SQL Server.

{
    ... other properties ...

    "ResourceExtensionParameters": [
        {
            "Name": "SQLInstance",
            "Type": "string",
            "Description": "The name of the SQL Server instance."
        }
    ],

    ... other properties ...
}

Throughout the ResourceExtension [SPFSDK][VMROLE] object model, a parameter can be referenced. To reference a parameter, use a special identifier syntax: [param.parameter_name]. The following example shows how a ResourceExtension [SPFSDK][VMROLE].ExtensionSettings [SPFSDK][VMROLE].ApplicationProfile.WindowsApplicationProfile [SPFSDK][VMROLE].SQLProfile [SPFSDK][VMROLE].SQLDeployment object uses the previous parameter.

{
    "SQLDeployments": [
        {
            "DeploymentName": "SQL Deployment 1",
            "InstanceName": "[Param.SQLInstance]",
            "InstanceID": "[Param.SQLInstance]",
            "EnableNamedPipes": false,
            "EnableTCP": true,
            "MediaSource": "c:\\SQLMediaPath\\sqlsetup.exe",
            "ProductKey": "abcdefghijklmnopqrstuvwxyz",
            "SQLAuthenticationType": "WindowsAuthentication",
            "SQLSysAdminMemberList": "domain\\user",
            "DeploymentTimeOutInSeconds": 3600,
            "SQLConfigurationPayloadId": "61A33949-46CE-4d0f-921F-A0059DA9AD1F",
            "SAPassword": "MySAPassword",

            "SQLDeploymentCredential": "domain\\user:password",
            "SQLAgentServiceCredential": "NT AUTHORITY\\System:",
            "SQLServiceCredential": "NT AUTHORITY\\NetworkService:",
            "SQLReportingServiceCredential": "domain\\user:password"
        }
    ]
}

Now that the resource extension is configured, you can supply a value for the parameter through the VirtualMachineRole.ResourceConfiguration [SPFSDK][VMROLE] object’s ParameterValues property.

{
    "Version" : "1.0.0.0",

    "ParameterValues" : "{    
                \"SQLInstance\" : \"HomeSQLServer\"
    }"
}

Parameter Types

The following sections represent the available parameter types:

• String

• Int

• Boolean

• Credential

• SecureString

String

• Value
  Any string value.

• Declaration example

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

• Configuration example

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

Int

• Value
  Any integer value.

• Declaration example

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

• Configuration example

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

Boolean

• Value
  true or false.

• Declaration example

  "ResourceParameters" : [ 
      {
          "Name" : "EnableTCP",
          "Type" : "Boolean",
          "Description" : "When True, enables TCP"
      }
  ]
  

• Configuration example

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

Credential

• Value
  A user name and password combination in the user:password format.

• Declaration example

  "ResourceParameters" : [ 
      {
          "Name" : "JoinDomainCreds",
          "Type" : "Credential",
          "Description" : "The credentials to join the domain",
      }
  ]
  

• Configuration example

  ParameterValues Example
  "ParameterValues" : "{
      \"JoinDomainCreds\" : \"myuser:mypassword\"
  }"
  

SecureString

• Value
  Any string value. If GET, returns the string value of __**__.

• Declaration example

  "ResourceParameters" : [ 
      {
          "Name" : "CreditCard",
          "Type" : "SecureString",
          "Description" : "Credit card number",
      }
  ]
  

• Configuration example

  "ParameterValues" : "{
      \"CreditCard\" : \"0000-0000-0000-0000\"
  }"
  

See Also

VM Role JSON Reference [SPFSDK][VMROLE]
ResourceDefinition [SPFSDK][VMROLE]
ResourceConfiguration [SPFSDK][VMROLE]