在您的 Bicep 檔案中，您可以建立自己的函式。 這些函式可在您的 Bicep 檔案中使用。 使用者定義函式與 Bicep 檔案中自動可用的標準 Bicep 函式是分開的。 當您在 Bicep 檔案中需要重複使用複雜的運算式時，請建立自己的函式。 使用使用者定義函式會自動啟用語言版本 2.0 程式碼產生。
需要 Bicep CLI 版本 0.26.X (含) 以上版本才能使用此功能。
限制
定義使用者函式時有一些限制：
定義函式
使用 func 陳述式可定義使用者定義函式。
@<decorator>(<argument>)
func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>
下列範例示範如何定義與使用使用者定義函式：
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')
前述範例的輸出為：
| 名稱 | 類型 | 值 |
|---|---|---|
| azureUrl | 繩子 | https://microsoft.com/azure |
| greetingArray | Array | [“Hi Evie！”，“Hi Casper！”] |
| greetingObject | 物體 | {“hello”：“Hi John！”} |
| nameArray | Array | [“John”] |
| addNameArray | Array | [“Mary”，“Bob”，“John”] |
您可以彈性地叫用使用者定義函數內的另一個使用者定義函式。 在前述範例中，透過 sayHelloString 的函式定義，您可以重新定義 sayHelloObject 函式如下：
func sayHelloObject(name string) object => {
hello: sayHelloString(name)
}
使用者定義函式支援使用使用者定義資料型別。 例如：
@minValue(0)
type positiveInt = int
func typedArg(input string[]) positiveInt => length(input)
param inArray array = [
'Bicep'
'ARM'
'Terraform'
]
output elements positiveInt = typedArg(inArray)
前述範例的輸出為：
| 名稱 | 類型 | 值 |
|---|---|---|
| 項目 | positiveInt | 3 |
從 Bicep CLI 0.30.X 版起，使用者定義函式可以存取相同 Bicep 檔案中定義的變數。 下列範例示範使用者定義函式如何參考變數：
var greetingPrefix = 'Hello'
func greet(name string) string => '${greetingPrefix}, ${name}!'
output message string = greet('Azure')
前述範例的輸出為：
| 名稱 | 類型 | 值 |
|---|---|---|
| 訊息 | 繩子 | 您好，Azure！ |
從 Bicep CLI 0.31.X 版開始，從其他 Bicep 檔案匯入的變數可以在使用者定義函式中使用，就像在本機定義的變數一樣。
假設您有名為 shared.bicep 的 Bicep 檔案，可匯出變數：
// shared.bicep
@export()
var sharedPrefix = 'Contoso'
您可以將此變數匯入主要 Bicep 檔案，並在使用者定義函式內使用它：
import shared from './shared.bicep'
func makeResourceName(suffix string) string => '${shared.sharedPrefix}-${suffix}'
output resourceName string = makeResourceName('storage')
前述範例的輸出為：
| 名稱 | 類型 | 值 |
|---|---|---|
| 資源名稱 | 繩子 | Contoso-storage |
如需匯入變數的詳細資訊，請參閱 匯出變數、類型和函式。
使用裝飾項目
裝飾項目的撰寫格式為 @expression，並放置於函式宣告的上方。 下表顯示可用於函式的裝飾項目。
| 裝飾項目 | 論點 | 描述 |
|---|---|---|
| 描述 | 字串 | 提供函式的描述。 |
| 匯出 | 沒有 | 表示該函式可供其他 Bicep 檔案匯入。 |
| 中繼資料 | 物件 | 套用至函式的自訂屬性。 可包含相當於描述裝飾項目的描述屬性。 |
裝飾項目位於 sys 命名空間中。 如果您需要將裝飾項目與其他同名項目區分，請在裝飾項目前加上 sys。 例如，如果您的 Bicep 檔案中包含名為 description 的變數，使用描述裝飾項目時必須加上 sys 命名空間。
描述
若要添加說明，請在函式宣告中加上 描述。 例如：
@description('The say hello function.')
func sayHelloString(name string) string => 'Hi ${name}!'
說明文字可使用 Markdown 格式。
出口
使用 @export() 可將函式與其他 Bicep 檔案共用。 欲了解更多資訊，請參閱匯出變數、型別與函式。
中繼資料
如果您想套用自訂屬性到使用者定義函式，請新增中繼資料裝飾項目。 在中繼資料中，定義具有自訂名稱和值的物件。 您為中繼資料定義的物件可以包含任意名稱與型別的屬性。
您可能會使用此裝飾項目來追蹤函式相關資訊，而這些資訊不適合加到描述中。
@description('Configuration values that are applied when the application starts.')
@metadata({
source: 'database'
contact: 'Web team'
})
type settings object
當您提供的 @metadata() 裝飾項目與其他裝飾項目有屬性衝突時，其他裝飾項目會優先於 @metadata() 裝飾項目。 因此，@metadata() 中的衝突屬性是多餘的，將會被替換。 欲了解更多資訊，請參閱無衝突的中繼資料。
後續步驟
- 若要了解 Bicep 檔案結構與語法，請參閱了解 Bicep 檔案的結構與語法。
- 可用 Bicep 函式列表請參閱 Bicep 函式。