Funções definidas pelo usuário no Bicep

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 linguagem versão 2.0.

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

Limitações

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

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

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:

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

A partir da CLI Bicep versão 0.30.X, 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 referenciar uma variável:

var greetingPrefix = 'Hello'

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

output message string = greet('Azure')

O resultado 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 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 o 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')

O resultado do exemplo anterior é:

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

Usar decoradores

Decoradores são escritos no formato @expression e são inseridos acima de 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ê 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 denominada description, você deverá adicionar o namespace sys ao usar o decorador de descrição.

Descrição

Para adicionar uma explicação, adicione uma descrição à declaração da 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.

Exportação

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 que deseje 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 rastrear 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

• Para saber mais sobre a estrutura e sintaxe de um arquivo Bicep, confira Noções básicas de estrutura e sintaxe de arquivos Bicep.
• Para obter uma lista das funções Bicep disponíveis, consulte Funções Bicep.