Funções definidas pelo usuário no Bicep

  • Artigo

Dentro de seu arquivo Bicep, você pode criar suas próprias funções. Essas funções estão disponíveis para uso em seu arquivos Bicep. As funções definidas pelo usuário são separadas das funções de Bicep padrão que estão automaticamente disponíveis nos seus arquivos Bicep. Crie suas próprias funções quando tiver expressões complicadas que são usadas repetidamente em seus arquivos do 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

Há algumas restrições ao definir uma função de usuário:

  • A função não pode acessar variáveis.
  • A função só pode usar os 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 func para definir funções definidas pelo 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')

As saídas dos exemplos anteriores são:

Nome Tipo Valor
azureUrl String https://microsoft.com/azure
greetingArray Array ["Hi Evie!","Hi Casper!"]
greetingObject Objeto {"hello":"Hi John!"}
nameArray Array ["John"]
addNameArray Array ["Mary","Bob","John"]

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 em uma função definida pelo usuário. No exemplo anterior, com a definição de função de sayHelloString, você pode redefinir a função sayHelloObject como:

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

As funções definidas pelo usuário dão suporte ao uso de 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)

O resultado do exemplo anterior é:

Nome Tipo Valor
elementos positiveInt 3

Usar 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 Argument Descrição
descrição string Fornece descrições para a função.
exportar 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 de descrição que seja equivalente ao decorador da descrição.

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

Descrição

Para adicionar uma 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 em Markdown pode ser usado para o texto da descrição.

Export

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

Metadados

Se você tiver propriedades personalizadas às quais 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 os valores personalizados. O objeto que você define para os metadados pode conter propriedades de qualquer nome e tipo.

Você pode usar esse decorador para acompanhar informações sobre a função que não precisem ser adicionadas à descrição.

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

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

Próximas etapas