Partilhar via

Funções definidas pelo usuário no Bicep

  • Artigo

Dentro do seu arquivo Bicep, você pode criar suas próprias funções. Essas funções estão disponíveis para uso em seus arquivos Bicep. As funções definidas pelo usuário são separadas das funções padrão do Bicep que estão automaticamente disponíveis em seus arquivos Bicep. Crie suas próprias funções quando você tiver expressões complicadas que são usadas repetidamente em seus arquivos Bicep. O uso de funções definidas pelo usuário habilita automaticamente a geração de código da versão 2.0 do idioma.

A CLI do Bicep versão 0.26.X ou superior é necessária para usar esse recurso.

Limitações

Existem algumas restrições ao definir uma função de utilizador:

  • A função não pode acessar variáveis.
  • A função só pode usar parâmetros que são definidos na função.
  • A função não pode usar a função de referência ou qualquer uma das funções de lista .
  • Os parâmetros para a função não podem ter valores padrão.

Definir funções

Use a instrução para definir funções definidas pelo func usuário.

@<decorator>(<argument>)
func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>

Exemplos

Os exemplos a seguir mostram como definir e usar funções definidas pelo usuário:

func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'

func sayHelloString(name string) string => 'Hi ${name}!'

func sayHelloObject(name string) object => {
  hello: 'Hi ${name}!'
}

func nameArray(name string) array => [
  name
]

func addNameArray(name string) array => [
  'Mary'
  'Bob'
  name
]

output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')
output greetingArray array = map(['Evie', 'Casper'], name => sayHelloString(name))
output greetingObject object = sayHelloObject('John')
output nameArray array = nameArray('John')
output addNameArray array = addNameArray('John')

Os resultados dos exemplos anteriores são:

Nome Tipo valor
azureUrl String https://microsoft.com/azure
greetingArray Matriz ["Olá Evie!","Olá Casper!"]
greetingObject Object {"Olá":"Olá João!"}
nomeArray Matriz ["João"]
addNameArray Matriz ["Maria","Bob","João"]

Com a CLI do Bicep versão 0.23.X ou superior, você tem a flexibilidade de invocar outra função definida pelo usuário dentro de uma função definida pelo usuário. No exemplo anterior, com a definição de função de sayHelloString, você pode redefinir a sayHelloObject função como:

func sayHelloObject(name string) object => {
  hello: sayHelloString(name)
}

Suporte a funções definidas pelo usuário usando tipos de dados definidos pelo usuário. Por exemplo:

@minValue(0)
type positiveInt = int

func typedArg(input string[]) positiveInt => length(input)

param inArray array = [
  'Bicep'
  'ARM'
  'Terraform'
]

output elements positiveInt = typedArg(inArray)

A saída do exemplo anterior é:

Nome Tipo valor
elementos positivoInt 3

Use decoradores

Os decoradores são escritos no formato @expression e são colocados acima das declarações de função. A tabela a seguir mostra os decoradores disponíveis para funções.

Decorador Argumento Description
descrição string Forneça descrições para a função.
exportação nenhum Indica que a função está disponível para importação por outro arquivo Bicep.
metadados objeto Propriedades personalizadas a serem aplicadas à função. Pode incluir uma propriedade description equivalente ao decorador de descrição.

Os decoradores estão no namespace sys. Se você precisa diferenciar um decorador de outro item com o mesmo nome, prefacie o decorador com sys. Por exemplo, se o arquivo Bicep incluir uma variável chamada description, você deverá adicionar o namespace sys ao usar o decorador de descrição .

Description

Para adicionar explicação, adicione uma descrição à declaração de função. Por exemplo:

@description('The say hello function.')
func sayHelloString(name string) string => 'Hi ${name}!'

O texto formatado com marcação pode ser usado para o texto de descrição.

Exportar

Use @export() para compartilhar a função com outros arquivos Bicep. Para obter mais informações, consulte Exportar variáveis, tipos e funções.

Metadados

Se você tiver propriedades personalizadas que deseja aplicar a uma função definida pelo usuário, adicione um decorador de metadados. Dentro dos metadados, defina um objeto com os nomes e valores personalizados. O objeto definido para os metadados pode conter propriedades de qualquer nome e tipo.

Você pode usar esse decorador para rastrear informações sobre a função que não faz sentido adicionar à descrição.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
type settings object

Quando você fornece a um @metadata() decorador uma propriedade que entra em conflito com outro decorador, esse decorador sempre tem precedência sobre qualquer coisa no @metadata() decorador. Assim, a propriedade conflitante dentro do @metadata() valor é redundante e será substituída. Para obter mais informações, consulte Sem metadados conflitantes.

Próximos passos