Share via

Aanbevolen procedures voor Bicep

  • Artikel

In dit artikel worden procedures aanbevolen die u moet volgen bij het ontwikkelen van uw Bicep-bestanden. Deze procedures maken uw Bicep-bestand gemakkelijker te begrijpen en te gebruiken.

Training en bronnen

Zie Uw Bicep-code structuren voor samenwerking als u liever meer wilt weten over aanbevolen procedures voor Bicep via stapsgewijze instructies.

Parameters

  • Gebruik goede naamgeving voor parameterdeclaraties. Goede namen maken uw sjablonen gemakkelijk te lezen en te begrijpen. Zorg ervoor dat u duidelijke, beschrijvende namen gebruikt en consistent bent in uw naamgeving.

  • Denk goed na over de parameters die uw sjabloon gebruikt. Probeer parameters te gebruiken voor instellingen die tussen implementaties veranderen. Variabelen en in code vastgelegde waarden kunnen worden gebruikt voor instellingen die niet veranderen tussen implementaties.

  • Houd rekening met de standaardwaarden die u gebruikt. Zorg ervoor dat de standaardwaarden veilig zijn voor iedereen om te implementeren. U kunt bijvoorbeeld goedkope prijscategorieën en SKU's gebruiken, zodat iemand die de sjabloon in een testomgeving implementeert, niet onnodig hoge kosten met zich meebrengt.

  • Gebruik de @allowed decorator spaarzaam. Als u deze decorator te breed gebruikt, kunt u geldige implementaties blokkeren. Als Azure-services SKU's en grootten toevoegen, is uw lijst met toegestane items mogelijk niet up-to-date. Het toestaan van alleen Premium v3-SKU's kan bijvoorbeeld zinvol zijn in productie, maar voorkomt dat u dezelfde sjabloon gebruikt in niet-productieomgevingen.

  • Het is een goede gewoonte om beschrijvingen op te geven voor uw parameters. Probeer de beschrijvingen nuttig te maken en geef belangrijke informatie op over wat de sjabloon nodig heeft voor de parameterwaarden.

    U kunt ook opmerkingen gebruiken // om notities toe te voegen in uw Bicep-bestanden.

  • U kunt parameterdeclaraties overal in het sjabloonbestand plaatsen, hoewel het meestal een goed idee is om ze bovenaan het bestand te plaatsen, zodat uw Bicep-code gemakkelijk te lezen is.

  • Het is een goede gewoonte om de minimale en maximale tekenlengte op te geven voor parameters die naamgeving bepalen. Met deze beperkingen voorkomt u later fouten tijdens de implementatie.

Zie Parameters in Bicep voor meer informatie over Bicep-parameters.

Variabelen

  • Wanneer u een variabele definieert, is het gegevenstype niet nodig. Variabelen afleiden het type uit de oplossingswaarde.

  • U kunt Bicep-functies gebruiken om een variabele te maken.

  • Nadat een variabele is gedefinieerd in uw Bicep-bestand, verwijst u naar de waarde met behulp van de naam van de variabele.

Zie Variabelen in Bicep voor meer informatie over Bicep-variabelen.

Namen

  • Gebruik kleine kameel hoofdletters voor namen, zoals myVariableName of myResource.

  • De functie uniqueString() is handig voor het maken van unieke resourcenamen. Wanneer u dezelfde parameters opgeeft, wordt elke keer dezelfde tekenreeks geretourneerd. Het doorgeven van de resourcegroep-id betekent dat de tekenreeks hetzelfde is voor elke implementatie in dezelfde resourcegroep, maar anders wanneer u implementeert in verschillende resourcegroepen of abonnementen.

  • Het is een goede gewoonte om sjabloonexpressies te gebruiken om resourcenamen te maken, zoals in dit voorbeeld:

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

    Het gebruik van sjabloonexpressies om resourcenamen te maken, biedt verschillende voordelen:

    • Tekenreeksen die door worden gegenereerd uniqueString() , zijn niet zinvol. Het is handig om een sjabloonexpressie te gebruiken om een naam te maken die zinvolle informatie bevat, zoals een korte beschrijving van de naam van het project of de omgeving, evenals een willekeurig onderdeel, zodat de naam waarschijnlijk uniek is.

    • De uniqueString() functie garandeert geen globaal unieke namen. Door extra tekst toe te voegen aan uw resourcenamen, verkleint u de kans dat een bestaande resourcenaam opnieuw wordt gebruikt.

    • Soms maakt de uniqueString() functie tekenreeksen die beginnen met een getal. Sommige Azure-resources, zoals opslagaccounts, staan niet toe dat hun namen beginnen met getallen. Deze vereiste betekent dat het een goed idee is om tekenreeksinterpolatie te gebruiken om resourcenamen te maken. U kunt een voorvoegsel toevoegen aan de unieke tekenreeks.

    • Veel Azure-resourcetypen hebben regels over de toegestane tekens en de lengte van hun namen. Het insluiten van het maken van resourcenamen in de sjabloon betekent dat iedereen die de sjabloon gebruikt, zich niet hoeft te herinneren deze regels zelf te volgen.

  • Vermijd het gebruik in name een symbolische naam. De symbolische naam vertegenwoordigt de resource, niet de naam van de resource. Bijvoorbeeld, in plaats van de volgende syntaxis:

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

    Gebruiken:

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

  • Vermijd het onderscheiden van variabelen en parameters door het gebruik van achtervoegsels.

Resourcedefinities

  • In plaats van complexe expressies rechtstreeks in te sluiten in resource-eigenschappen, gebruikt u variabelen om de expressies te bevatten. Deze benadering maakt uw Bicep-bestand gemakkelijker te lezen en te begrijpen. Hiermee voorkomt u dat uw resourcedefinities met logica rommelig worden.

  • Probeer resource-eigenschappen te gebruiken als uitvoer, in plaats van aannames te maken over hoe resources zich gedragen. Als u bijvoorbeeld de URL naar een App Service-app wilt uitvoeren, gebruikt u de eigenschap defaultHostname van de app in plaats van zelf een tekenreeks voor de URL te maken. Soms zijn deze veronderstellingen niet juist in verschillende omgevingen of veranderen de resources de manier waarop ze werken. Het is veiliger om de resource zijn eigen eigenschappen te laten weten.

  • Het is een goed idee om voor elke resource een recente API-versie te gebruiken. Nieuwe functies in Azure-services zijn soms alleen beschikbaar in nieuwere API-versies.

  • Vermijd, indien mogelijk, het gebruik van de functies reference en resourceId in uw Bicep-bestand. U kunt toegang krijgen tot elke resource in Bicep met behulp van de symbolische naam. Als u bijvoorbeeld een opslagaccount definieert met de symbolische naam toyDesignDocumentsStorageAccount, hebt u toegang tot de resource-id met behulp van de expressie toyDesignDocumentsStorageAccount.id. Door de symbolische naam te gebruiken, maakt u een impliciete afhankelijkheid tussen resources.

  • Gebruik liever impliciete afhankelijkheden dan expliciete afhankelijkheden. Hoewel u met de dependsOn resourceeigenschap een expliciete afhankelijkheid tussen resources kunt declareren, is het meestal mogelijk om de eigenschappen van de andere resource te gebruiken met behulp van de symbolische naam. Met deze benadering wordt een impliciete afhankelijkheid tussen de twee resources gemaakt en kan Bicep de relatie zelf beheren.

  • Als de resource niet is geïmplementeerd in het Bicep-bestand, kunt u nog steeds een symbolische verwijzing naar de resource krijgen met behulp van het existing trefwoord.

Onderliggende resources

  • Vermijd het nesten van te veel lagen diep. Te veel nesten maakt uw Bicep-code moeilijker om te lezen en ermee te werken.

  • Vermijd het samenstellen van resourcenamen voor onderliggende resources. U verliest de voordelen die Bicep biedt wanneer het de relaties tussen uw resources begrijpt. Gebruik in plaats daarvan de parent eigenschap of nesting.

Uitvoerwaarden

  • Zorg ervoor dat u geen uitvoer maakt voor gevoelige gegevens. Uitvoerwaarden zijn toegankelijk voor iedereen die toegang heeft tot de implementatiegeschiedenis. Ze zijn niet geschikt voor het verwerken van geheimen.

  • In plaats van eigenschapswaarden door te geven via uitvoer, gebruikt u het bestaande trefwoord om eigenschappen op te zoeken van resources die al bestaan. Het is een best practice om sleutels uit andere resources op deze manier op te zoeken in plaats van ze door te geven via uitvoer. U krijgt altijd de meest recente gegevens.

Zie Uitvoer in Bicep voor meer informatie over Bicep-uitvoer.

Tenantbereiken

U kunt geen beleid of roltoewijzingen maken binnen het tenantbereik. Als u echter toegang wilt verlenen of beleidsregels wilt toepassen in uw hele organisatie, kunt u deze resources implementeren in de hoofdbeheergroep.

Volgende stappen