Metodtips för Bicep

  • Artikel

Den här artikeln rekommenderar metoder att följa när du utvecklar dina Bicep-filer. Dessa metoder gör din Bicep-fil enklare att förstå och använda.

Träningsresurser

Om du hellre vill lära dig mer om metodtips för Bicep via stegvis vägledning kan du läsa Structure your Bicep code for collaboration (Strukturera din Bicep-kod för samarbete).

Parametrar

  • Använd bra namngivning för parameterdeklarationer. Bra namn gör dina mallar lätta att läsa och förstå. Se till att du använder tydliga, beskrivande namn och vara konsekvent i din namngivning.

  • Tänk noga på de parametrar som mallen använder. Försök att använda parametrar för inställningar som ändras mellan distributioner. Variabler och hårdkodade värden kan användas för inställningar som inte ändras mellan distributioner.

  • Tänk på de standardvärden som du använder. Kontrollera att standardvärdena är säkra för alla att distribuera. Överväg till exempel att använda prisnivåer och SKU:er till låg kostnad så att någon som distribuerar mallen till en testmiljö inte medför en stor kostnad i onödan.

  • Använd dekoratören @allowed sparsamt. Om du använder den här dekoratören för brett kan du blockera giltiga distributioner. När Azure-tjänster lägger till SKU:er och storlekar är listan över tillåtna kanske inte uppdaterad. Att till exempel bara tillåta Premium v3-SKU:er kan vara meningsfullt i produktion, men det hindrar dig från att använda samma mall i icke-produktionsmiljöer.

  • Det är en bra idé att ange beskrivningar för dina parametrar. Försök att göra beskrivningarna användbara och ange viktig information om vad mallen behöver för att parametervärdena ska vara.

    Du kan också använda // kommentarer för att lägga till anteckningar i dina Bicep-filer.

  • Du kan placera parameterdeklarationer var som helst i mallfilen, även om det vanligtvis är en bra idé att placera dem överst i filen så att din Bicep-kod är lätt att läsa.

  • Det är en bra idé att ange minsta och högsta teckenlängd för parametrar som styr namngivning. De här begränsningarna hjälper dig att undvika fel senare under distributionen.

Mer information om Bicep-parametrar finns i Parametrar i Bicep.

Variabler

  • När du definierar en variabel behövs inte datatypen . Variabler härleder typen från matchningsvärdet.

  • Du kan använda Bicep-funktioner för att skapa en variabel.

  • När en variabel har definierats i Bicep-filen refererar du till värdet med variabelns namn.

Mer information om Bicep-variabler finns i Variabler i Bicep.

Namn

  • Använd gemener för namn, till exempel myVariableName eller myResource.

  • Funktionen uniqueString() är användbar för att skapa unika resursnamn. När du anger samma parametrar returneras samma sträng varje gång. Om du skickar in resursgrupps-ID:t innebär det att strängen är samma för varje distribution till samma resursgrupp, men olika när du distribuerar till olika resursgrupper eller prenumerationer.

  • Det är en bra idé att använda malluttryck för att skapa resursnamn, som i det här exemplet:

    param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'

    Om du använder malluttryck för att skapa resursnamn får du flera fördelar:

    • Strängar som genereras av uniqueString() är inte meningsfulla. Det är bra att använda ett malluttryck för att skapa ett namn som innehåller meningsfull information, till exempel en kort beskrivning av projekt- eller miljönamnet, samt en slumpmässig komponent för att göra namnet mer sannolikt att vara unikt.

    • Funktionen uniqueString() garanterar inte globalt unika namn. Genom att lägga till ytterligare text i resursnamnen minskar du sannolikheten för att återanvända ett befintligt resursnamn.

    • uniqueString() Ibland skapar funktionen strängar som börjar med ett tal. Vissa Azure-resurser, till exempel lagringskonton, tillåter inte att deras namn börjar med siffror. Det här kravet innebär att det är en bra idé att använda stränginterpolation för att skapa resursnamn. Du kan lägga till ett prefix i den unika strängen.

    • Många Azure-resurstyper har regler om tillåtna tecken och längden på deras namn. Att bädda in skapandet av resursnamn i mallen innebär att alla som använder mallen inte behöver komma ihåg att själva följa dessa regler.

  • Undvik att använda name i ett symboliskt namn. Det symboliska namnet representerar resursen, inte resursens namn. I stället för följande syntax:

    resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {

    Använda:

    resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {

  • Undvik att skilja variabler och parametrar genom att använda suffix.

Resursdefinitioner

  • I stället för att bädda in komplexa uttryck direkt i resursegenskaper använder du variabler för att innehålla uttrycken. Den här metoden gör Bicep-filen enklare att läsa och förstå. Det förhindrar att dina resursdefinitioner blir röriga med logik.

  • Försök att använda resursegenskaper som utdata i stället för att göra antaganden om hur resurser kommer att bete sig. Om du till exempel behöver mata ut URL:en till en App Service app använder du egenskapen defaultHostname för appen i stället för att skapa en sträng för URL:en själv. Ibland är dessa antaganden inte korrekta i olika miljöer, eller så ändrar resurserna hur de fungerar. Det är säkrare att låta resursen berätta om sina egna egenskaper.

  • Det är en bra idé att använda en ny API-version för varje resurs. Nya funktioner i Azure-tjänster är ibland bara tillgängliga i nyare API-versioner.

  • Undvik att använda funktionerna reference och resourceId i Bicep-filen när det är möjligt. Du kan komma åt valfri resurs i Bicep med det symboliska namnet. Om du till exempel definierar ett lagringskonto med det symboliska namnet toyDesignDocumentsStorageAccount kan du komma åt dess resurs-ID med hjälp av uttrycket toyDesignDocumentsStorageAccount.id. Genom att använda det symboliska namnet skapar du ett implicit beroende mellan resurser.

  • Använd implicita beroenden framför explicita beroenden. Även om resursegenskapen dependsOn gör att du kan deklarera ett explicit beroende mellan resurser, är det vanligtvis möjligt att använda den andra resursens egenskaper med dess symboliska namn. Den här metoden skapar ett implicit beroende mellan de två resurserna och gör det möjligt för Bicep att hantera själva relationen.

  • Om resursen inte distribueras i Bicep-filen kan du fortfarande få en symbolisk referens till resursen med hjälp av nyckelordet existing .

Underordnade resurser

  • Undvik att kapsla för många lager djupt. För mycket kapsling gör din Bicep-kod svårare att läsa och arbeta med.

  • Undvik att skapa resursnamn för underordnade resurser. Du förlorar de fördelar som Bicep ger när det förstår relationerna mellan dina resurser. Använd egenskapen eller kapslingen parent i stället.

Utdata

  • Se till att du inte skapar utdata för känsliga data. Utdatavärden kan nås av alla som har åtkomst till distributionshistoriken. De är inte lämpliga för att hantera hemligheter.

  • I stället för att skicka egenskapsvärden via utdata använder du det befintliga nyckelordet för att leta upp egenskaper för resurser som redan finns. Det är bästa praxis att söka efter nycklar från andra resurser på det här sättet i stället för att skicka runt dem via utdata. Du får alltid de senaste data.

Mer information om Bicep-utdata finns i Utdata i Bicep.

Klientomfattningar

Du kan inte skapa principer eller rolltilldelningar i klientomfånget. Men om du behöver bevilja åtkomst eller tillämpa principer i hela organisationen kan du distribuera dessa resurser till rothanteringsgruppen.

Nästa steg