Funções definidas pelo usuário no Bicep

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 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>

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:

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 é:

A partir da versão 0.30.X da CLI do Bicep, as funções definidas pelo usuário podem acessar variáveis definidas no mesmo arquivo Bicep. O exemplo a seguir demonstra como uma função definida pelo usuário pode fazer referência a uma variável:

var greetingPrefix = 'Hello'

func greet(name string) string => '${greetingPrefix}, ${name}!'

output message string = greet('Azure')

A saída do exemplo anterior é:

A partir da CLI do Bicep versão 0.31.X, as variáveis importadas de outros arquivos Bicep são acessíveis dentro de suas funções definidas pelo usuário, assim como as variáveis definidas localmente.

Suponha que você tenha um arquivo Bicep chamado shared.bicep que exporta uma variável:

// shared.bicep
@export()
var sharedPrefix = 'Contoso'

Você pode importar essa variável para seu arquivo Bicep principal e usá-la dentro de uma função definida pelo usuário:

import shared from './shared.bicep'

func makeResourceName(suffix string) string => '${shared.sharedPrefix}-${suffix}'

output resourceName string = makeResourceName('storage')

A saída do exemplo anterior é:

Para obter mais informações sobre como importar variáveis, consulte Exportar variáveis, tipos e funções.

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.

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 .

Descrição

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

• Para saber mais sobre a estrutura e a sintaxe do arquivo Bicep, consulte Compreender a estrutura e a sintaxe dos arquivos Bicep.
• Para obter uma lista das funções Bicep disponíveis, consulte Funções Bicep.