azuredatastudio/extensions/resource-deployment/DEVELOPER_GUIDE.md

Resource Deployment Extension Developer Guide

This guide is meant to provide details on what this extension does and how other extension authors are meant to use it. If there is any missing or incorrect information please submit an issue.

Overview

This extension provides a way for other extension authors to contribute types to the Resource Deployment Wizard which allows users to create and deploy resources such as servers.

This wizard is launched by either running the Deployment: New Deployment... command from the command palette or by clicking File on the menu bar and selecting New Deployment...

How to Contribute a new Type

Resource Deployment types are contributed through the package.json of a loaded extension. This is done by adding an resourceDeploymentTypes property under the contributes section of your package.json.

   ... // Other sections in your package.json
   "contributes": {
	   ..., // Other contributions
	   "resourceDeploymentTypes": [
		   // provided types go here
	   ]
   }

The rest of this guide will detail the various options and configuration available to provided types - most contributions will only need a subset of the available features.

The sample-resource-deployment extension provides working examples of contributed sample resource deployment types.

resourceDeploymentTypes Schema

The contribution must adhere to a specific schema, if there is an error in your package.json such as an unexpected type then this may result in errors in both your extension and the feature as a whole.

!! THIS IS A WORK IN PROGRESS, IF YOU NEED INFORMATION ON A SPECIFIC TOPIC PLEASE OPEN AN ISSUE!

resourceDeploymentTypes

This is the top contribution and must be an array of ResourceType objects.

"resourceDeploymentTypes": [
	{
		... // Contributed type
	},
	{
		... // Another contributed type
	}
]

ResourceType

The type is defined here.

There are a number of properties on each ResourceType.

name - The name of the type, this is not displayed to the user so should be a non-localized value and typically - delimited (e.g. my-resource-type)

displayName - The name of the type displayed to the user, this should be a localized string

description - The description of the type displayed to the user

platforms - The OS platforms that the type supports running on, options are linux (Linux distros), darwin (MacOS), win32 (Windows) or* for all.

icon - The icon to display for the type - supports either single icon or separate ones for light and dark mode. The icon should be in svg format.

options - An array of ResourceTypeOption objects, allowing users to provide different sub-options for a given resource type. (e.g. the specific version of SQL Server to deploy)

providers - An array of DeploymentProvider objects which define the wizards, dialogs or other means for a user to deploy their resource.

agreements - OPTIONAL An array of AgreementInfo objects which define any agreements the user must accept before proceeding with the deployment.

displayIndex - OPTIONAL A number corresponding to where the type should be displayed relative to the other types. A lower number means it will show up earlier in the list. Any types which don't specify this value will be shown last.

okButtonText - OPTIONAL The text to use for the OK button at the bottom of the Type Picker dialog. Default is Select.

helpTexts - OPTIONAL An array of strings to display to the user providing more information for the resource type (such as links to docs)

tags - OPTIONAL An array of strings that are used to indicate the category that the resource type belongs to. The usable tags are defined here.

ResourceTypeOption

TODO

DeploymentProvider

Provider Types

There are a number of different types of providers that can be used which affect what happens when the user selects that provider. These are indicated by what fields the provider contains - the provider is checked in order of top to bottom for each property and uses the first type that it finds in the properties for that provider.

Notebook Wizard - A wizard is opened that can be used to prompt the user for values and display information, and then at the very end will open the specified Notebook with those values injected in. Indicated by the presence of the notebookWizard property.

Dialog - A single page dialog is opened that can be used to prompt the user for values. Indicated by the presence of the dialog property.

Notebook - The specified Notebook is opened for the user to run. Indicated by the presence of the notebook property.

Download - An installer is downloaded and ran. Indicated by the presence of the downloadUrl property.

Web Page - The specified URL is opened in the default browser for the user. Indicated by the presence of the webPageUrl property.

Command - The specified command is executed. Indicated by the presence of the command property.

AgreementInfo

TODO

NotebookWizard (extends WizardInfoBase)

See NotebookWizardInfo for how it's defined in code.

notebook - The path to the Python-based Notebook that is used as a template for the wizard.

pages - An array of NotebookWizardPageInfo containing information for each page in the Notebook Wizard.

codeCellInsertionPosition - OPTIONAL The index of the code cell to insert the injected parameters cell. Default is 0.

WizardInfoBase

doneAction

scriptAction - OPTIONAL

title

name - OPTIONAL

pages - An array of the pages for this wizard. Each wizard implementation will usually have its own page type that extends PageInfoBase.

isSummaryPageAutoGenerated - OPTIONAL

NotebookWizardPageInfo (extends PageInfoBase)

description - OPTIONAL The page description to display at the top of the page.

PageInfoBase

title - The title to display for the page

isSummaryPage - OPTIONAL Whether this page is set as a summary page that displays a summary of the Note

sections - An array of [SectionInfo] objects containing the details of each section to display on this page.

SectionInfo (extends FieldInfoBase)

title - OPTIONAL The title to display at the top of the section

fields - OPTIONAL An array of FieldInfo objects containing details for each field in this section.

rows - OPTIONAL Used for wide dialogs or wizards, the label for each field will be placed to the left of the field component.

collapsible - OPTIONAL Whether the section is collapsible or not. Default is true.

collapsed - OPTIONAL Whether the section starts off collapsed. Default is false.

spaceBetweenFields - OPTIONAL A string defining how much space should be between each field. Default is 50px.

FieldInfo

subFields

type

defaultValue

confirmationRequired

confirmationLabel

min

max

required

options - REQUIRED if type is options. See Options for more information.

placeHolder

description

labelCSSStyles

fontWeight

editable

enabled

dynamicOptions

isEvaluated

validations

valueProvider - OPTIONAL If defined then the value for this field is retrieved using the specified Value Provider.

Options

This defines the set of options for this field to display. There are a number of different ways to configure the set of options :

• String array (string[]) - A static list of values that will be shown as a dropdown. Default value selected is defined as FieldInfo.defaultValue.

• CategoryValue array (azdata.CategoryValue[]) - A static list of CategoryValue objects that will be shown as a dropdown. Each value will define a display name separate from its value - use this for values you want to display differently to the user (such as names for an Azure region). If you use a CategoryValue array as your options, ensure you set the defaultValue to the CategoryValue's displayName rather than the name.

• OptionsInfo - An object allowing more control over the option values.

• Dynamic Options - Change the options available for one field based on the option selected in another. Radio buttons only. Can use CategoryValue type as values.

See sample-options for example implementations.

OptionsInfo

This object defines a set of options for a field, similar to the arrays that can be used for the options field but with greater control over of the options. Currently there are two reasons that you would use this object over the arrays - either you want to display the options as something other than a dropdown or you wish to use an Options Source Provider to populate the options dynamically.

values - An array of either strings or azdata.CategoryValue objects. See options for more details on each of those. defaultValue - The string value of the default option to have selected optionsType - How to display the options, either radio or dropdown source - OPTIONAL If set defines the Options Source Provider to use for populating the options dynamically.

Dynamic Options

This enables you to dynamically change what options for a field are displayed to the user based on a previous selection they made. For example, if a user selects "Cookies" over "Cakes" in the first field, the second field will show options ["Chocolate chip", "Snickerdoodle"] instead of ["Red velvet", "Cheesecake", "Black forest"], and vice versa.

NOTE This is currently only enabled for radio buttons. This works with CategoryValue values as well.

Placement of the dynamicOptions object in the package.json should be in the field whose values are doing the changing, not in the field whose value determines the other fields' options.

target - The variable name of the field to look at in order to detemine what options the current field should use.

alternates - An array of objects in which the objects represent the alternate options of the current field. An object has three values: selection, alternateValues, and defaultValue. selection is the variable name of a value in the target field that was not selected by default. alternateValues is an array of values that will be shown as options if the value in selection is chosen in the target field. defaultValue is simply the value that is selected by default out of the array of alternateValues.

			...
			"variableName": "AZDATA_NB_VAR_COOKIE_TYPES", // Our current field's name
                        "options": {
                          "values": ["Chocolate chip", "Snickerdoodle"], // Since Cookies is the default selection for the target field, these will be the values shown for this current field.
                          "defaultValue": "Chocolate chip",
                          "optionsType": "radio"
                        },
                        "dynamicOptions":
                        {
                          "target": "AZDATA_NB_VAR_DESSERT_TYPES", // The field that determines what options our current field will show
                          "alternates": [
                            {
                              "selection": "Cakes", // If the user selected Cakes previously, the options shown will be as follows:
                              "alternateValues": [
                                "Red velvet",
				"Cheesecake",
				"Black forest"
                              ],
                              "defaultValue": "Red velvet"
                            }
                          ]
                        }

Options Source Provider

Value Provider

When a field specifies a value provider then it is saying that the value for that field is dynamic and will be retrieved from a value provider that is registered by an extension separately. This can be used for more complex logic such as running calculations, reading files, making web requests, etc.

See sample-value-provider for an example implementation.

NOTE There is currently some behavior that should be known before using this :

1. The value providers are hooked up after all the components are made, so order doesn't generally matter (you don't have to define the trigger fields before the target field) when the values are on the same page.
2. If the fields are on different pages then currently the hookup logic is non-deterministic and so you may end up with trigger components not existing yet if they are on a different page which hasn't completed its initialization. So currently having a value provider that has trigger fields on another page is not something officially supported. Contact the dev team if you need this for your scenario

providerId - The string ID of this provider, this must be registered by an extension using registerValueProvider.

triggerFields - The field IDs (variableName or label) of the fields that - when changed - will trigger getValue to be called and the result set as the value of the dependent field. NOTE While variableName OR label is supported it is generally strongly suggested to use a variableName (even if you don't need that variable in the final deployment target) due to potential localization mismatches that could happen between the localized strings in the package.json and the ones used by the valueProvider.