azure-cli/doc/parampersist_localcontext_guidelines.md

The document provides instructions and guidelines on how to board param persist feature, prevoius name local context. The public feature name to end user is param persist. The usage is at here. In implementation, it's referenced as local context. The 2 terms are equivalent in this doc.

Local context attribute

Local context attribute is an abstraction of the definition for local context. We use this class to define how the argument supports local context.

There are 3 properties of local context attribute.

• name

name is the argument name used in local context. Usually we just use the name which defined in the function signature, for example, resource_group_name.

• scopes

scopes is an array of strings. It defines where this local context value can be referenced. The value could be a command group or a command, for example, ['vm', 'network']. If one argument can be referenced in all the commands, you can define it as ['all']. scopes is meaningful only when SET is in actions.

• actions

actions is an array of [LocalContextAction](#Local context action). It defines whether set the command parameter value to local context or get value from local context. We can define both GET and SET action for one argument.

Local context action

Local context action is defined as an enum type. The available values are GET and SET.

• GET

Used for retrieving value from local context.

• SET

Used for saving value to local context.

Parameters which support all scope by default

We define local context attribute for some command parameters by default. Commands whose function signature has the same argument name will support local context by default.

All these parameters are listed here:

• resource_group_name

    local_context_attribute=LocalContextAttribute(
        name='resource_group_name',
        actions=[LocalContextAction.SET, LocalContextAction.GET],
        scopes=[ALL]
    ))

• vnet_name

    local_context_attribute=LocalContextAttribute(name='vnet_name', actions=[LocalContextAction.GET])

• subnet

    local_context_attribute=LocalContextAttribute(name='subnet_name', actions=[LocalContextAction.GET])

For example, below is function signature for az network vnet create:

def create_vnet(cmd, resource_group_name, vnet_name, vnet_prefixes='10.0.0.0/16',
                subnet_name=None, subnet_prefix=None, dns_servers=None,
                location=None, tags=None, vm_protection=None, ddos_protection=None,
                ddos_protection_plan=None):

As resource_group_name is defined in the signature, it will automatically support local context.

Suggestions

• Only enable local context feature for resource dependency parameters.
• Do not define GET action for name parameter in create and delete command.
• Define SET action only in create command.

Examples

In order to create a webapp, a user needs to prepare an appservice plan first. Previously the user needed to run below commands to complete this scenario:

az group create --name myResourceGroup --location westus
az appservice plan create -g myResourceGroup --name myPlan
az webapp create -g myResourceGroup --plan myPlan --name myWebapp

The user has to input resource group name 3 times and plan name 2 times for this scenario. To reduce these duplicate type in, we need to enable local context feature for these parameters as below:

• az group create: set resource group name

azure-cli/azure/cli/command_modules/resource/_params.py

# define SET action for resource group name
with self.argument_context('group create') as c:
    c.argument('rg_name',
                local_context_attribute=LocalContextAttribute(name='resource_group_name',actions=[LocalContextAction.SET], scopes=[ALL]))

• az appservice plan create: get resource group name & set plan name

azure-cli/azure/cli/command_modules/appservice/custom.py

# get resource group name from local context by define function argument name as `resource_group_name`
def create_app_service_plan(cmd, resource_group_name, name, is_linux, hyper_v, per_site_scaling=False,
                            app_service_environment=None, sku='B1', number_of_workers=None, location=None,
                            tags=None, no_wait=False):

azure-cli/azure/cli/command_modules/appservice/_params.py

# define SET action for plan name
with self.argument_context('appservice plan create') as c:
    c.argument('name',
               local_context_attribute=LocalContextAttribute(name='plan_name', actions=[LocalContextAction.SET], scopes=['appservice', 'webapp', 'functionapp']))

• az webapp create: get resource group name & get plan name & set webapp name

azure-cli/azure/cli/command_modules/appservice/custom.py

# get resource group name from local context by define function argument name as `resource_group_name`
def create_webapp(cmd, resource_group_name, name, plan, runtime=None, startup_file=None,  # pylint: disable=too-many-statements,too-many-branches
                  deployment_container_image_name=None, deployment_source_url=None, deployment_source_branch='master',
                  deployment_local_git=None, docker_registry_server_password=None, docker_registry_server_user=None,
                  multicontainer_config_type=None, multicontainer_config_file=None, tags=None,
                  using_webapp_up=False, language=None):

azure-cli/azure/cli/command_modules/appservice/_params.py

# define SET action for webapp name
# define GET action for plan name
with self.argument_context('webapp create') as c:
    c.argument('name',
                local_context_attribute=LocalContextAttribute(name='web_name', actions=[LocalContextAction.SET], scopes=['webapp']))
    c.argument('plan',
                local_context_attribute=LocalContextAttribute(name='plan_name', actions=[LocalContextAction.GET]))