De structuur van uw Bicep-bestand plannen

Voltooid

Bicep biedt u de flexibiliteit om te bepalen hoe u uw code moet structuren. In deze les leert u hoe u uw Bicep-code kunt structureren en hoe belangrijk een consistente stijl en duidelijke, begrijpelijke Bicep-code is.

Welke bestelling moet uw Bicep-code volgen?

Uw Bicep-sjablonen kunnen veel elementen bevatten, waaronder parameters, variabelen, resources, modules, uitvoer en een targetScope voor de hele sjabloon. Bicep dwingt geen order af om uw elementen te volgen. Het is echter belangrijk om rekening te houden met de volgorde van uw elementen om ervoor te zorgen dat uw sjabloon duidelijk en begrijpelijk is.

Er zijn twee hoofdmethoden voor het ordenen van uw code:

• Elementen groeperen op elementtype
• Elementen groeperen op resource

U en uw team moeten het erover eens zijn en deze consistent gebruiken.

Elementen groeperen op elementtype

U kunt alle elementen van hetzelfde type groeperen. Al uw parameters zouden zich op één plaats bevinden, meestal boven aan het bestand. Variabelen komen hierna, gevolgd door resources en modules, en uitvoer bevindt zich onderaan. U hebt bijvoorbeeld een Bicep-bestand dat een Azure SQL-database en een opslagaccount implementeert.

Wanneer u de elementen groeperen op type, kunnen deze er als volgt uitzien:

Tip

Als u deze conventie volgt, kunt u het targetScope beste bovenaan het bestand plaatsen.

Deze volgorde is logisch wanneer u gewend bent aan andere infrastructuur als codetalen (bijvoorbeeld de taal in Azure Resource Manager-sjablonen). Het kan uw sjabloon ook gemakkelijk te begrijpen maken, omdat het duidelijk is waar u naar specifieke typen elementen moet zoeken. In langere sjablonen kan het echter lastig zijn om tussen de elementen te navigeren en te springen.

U moet nog steeds bepalen hoe u de elementen in deze categorieën kunt orden. Het is een goed idee om gerelateerde parameters samen te groeperen. Alle parameters die betrekking hebben op een opslagaccount horen bijvoorbeeld bij elkaar en daarbinnen horen de SKU-parameters van het opslagaccount bij elkaar.

Op dezelfde manier kunt u gerelateerde resources groeperen. Dit helpt iedereen die uw sjabloon gebruikt om er snel doorheen te navigeren en om inzicht te hebben in de belangrijke onderdelen van de sjabloon.

Soms maakt u een sjabloon waarmee een primaire resource wordt geïmplementeerd met meerdere secundaire ondersteunende resources. U kunt bijvoorbeeld een sjabloon maken om een website te implementeren die wordt gehost op Azure-app Service. De primaire resource is de App Service-app. Secundaire resources in dezelfde sjabloon kunnen het App Service-plan, het opslagaccount, het Application Insights-exemplaar en andere omvatten. Wanneer u een sjabloon als deze hebt, is het een goed idee om de primaire resource of resources boven aan de resourcesectie van de sjabloon te plaatsen, zodat iedereen die de sjabloon opent, snel het doel van de sjabloon kan identificeren en de belangrijke resources kan vinden.

Elementen groeperen op resource

U kunt uw elementen ook groeperen op basis van het type resources dat u implementeert. Als u verdergaat met het voorgaande voorbeeld, kunt u alle parameters, variabelen, resources en uitvoer groeperen die betrekking hebben op de Azure SQL-databasebronnen. Vervolgens kunt u de parameters, variabelen, resources en uitvoer voor het opslagaccount toevoegen, zoals hier wordt weergegeven:

Door te groeperen op resource kunt u uw sjabloon gemakkelijker lezen, omdat alle elementen die u nodig hebt voor een specifieke resource zich op één plaats bevinden. Het maakt het echter moeilijker om snel te controleren hoe specifieke elementtypen worden gedeclareerd wanneer u bijvoorbeeld al uw parameters wilt controleren.

U moet ook rekening houden met het afhandelen van parameters en variabelen die gebruikelijk zijn voor meerdere resources, zoals een environmentType parameter wanneer u een configuratietoewijzing gebruikt. Algemene parameters en variabelen moeten samen worden geplaatst, meestal bovenaan het Bicep-bestand.

Tip

Overweeg of het zinvoler is om modules te maken voor groepen gerelateerde resources en vervolgens een eenvoudigere sjabloon te gebruiken om de modules te combineren. We behandelen Bicep-modules in meer detail in de Bicep-leertrajecten.

Hoe kan witruimte helpen bij het maken van structuur?

Lege regels of witruimte kunnen u helpen bij het toevoegen van een visuele structuur aan uw sjabloon. Door zorgvuldig witruimte te gebruiken, kunt u de secties van uw Bicep-code logisch groeperen, wat op zijn beurt kan helpen de relaties tussen resources te verduidelijken. U kunt dit doen door een lege regel toe te voegen tussen hoofdsecties, ongeacht de gewenste groeperingsstijl.

Hoe definieert u verschillende vergelijkbare resources?

Met Bicep kunt u lussen gebruiken om vergelijkbare resources uit één definitie te implementeren. Door het for trefwoord te gebruiken om resourcelussen te definiëren, kunt u uw Bicep-code schoner maken en onnodige duplicatie van resourcedefinities verminderen. Wanneer u in de toekomst de definitie van uw resources moet wijzigen, werkt u slechts één locatie bij. Wanneer Azure Resource Manager uw resources implementeert, worden standaard alle resources tegelijk in de lus geïmplementeerd, zodat uw implementatie zo efficiënt mogelijk is.

Zoek naar plaatsen waar u meerdere resources definieert die identiek zijn of die weinig verschillen hebben in hun eigenschappen. Voeg vervolgens een variabele toe om de resources weer te geven die u wilt maken, samen met de eigenschappen die verschillen van de andere resources. In het volgende voorbeeld wordt een lus gebruikt om een set Azure Cosmos DB-containers te definiëren, die elk een eigen naam en partitiesleutel hebben:

var cosmosDBContainerDefinitions = [
  {
    name: 'customers'
    partitionKey: '/customerId'
  }
  {
    name: 'orders'
    partitionKey: '/orderId'
  }
  {
    name: 'products'
    partitionKey: '/productId'
  }
]

resource cosmosDBContainers 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = [for cosmosDBContainerDefinition in cosmosDBContainerDefinitions: {
  parent: cosmosDBDatabase
  name: cosmosDBContainerDefinition.name
  properties: {
    resource: {
      id: cosmosDBContainerDefinition.name
      partitionKey: {
        kind: 'Hash'
        paths: [
          cosmosDBContainerDefinition.partitionKey
        ]
      }
    }
    options: {}
  }
}]

Hoe implementeert u resources alleen in bepaalde omgevingen?

Soms definieert u resources die alleen moeten worden geïmplementeerd in specifieke omgevingen of onder bepaalde omstandigheden. Met behulp van het if trefwoord kunt u resources selectief implementeren op basis van een parameterwaarde, een configuratietoewijzingsvariabele of een andere voorwaarde. In het volgende voorbeeld wordt een configuratietoewijzing gebruikt om logboekregistratiebronnen te implementeren voor productieomgevingen, maar niet voor testomgevingen:

var environmentConfigurationMap = {
  Production: {
    enableLogging: true
  }
  Test: {
    enableLogging: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = if (environmentConfigurationMap[environmentType].enableLogging) {
  name: logAnalyticsWorkspaceName
  location: location
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = if (environmentConfigurationMap[environmentType].enableLogging) {
  scope: cosmosDBAccount
  name: cosmosDBAccountDiagnosticSettingsName
  properties: {
    workspaceId: logAnalyticsWorkspace.id
    // ...
  }
}

Hoe kunt u afhankelijkheden tussen uw resources uitdrukken?

In een complexe Bicep-sjabloon moet u afhankelijkheden tussen uw resources uitdrukken. Wanneer Bicep de afhankelijkheden tussen uw resources begrijpt, worden deze in de juiste volgorde geïmplementeerd.

Met Bicep kunt u expliciet een afhankelijkheid opgeven met behulp van de dependsOn eigenschap. In de meeste gevallen is het echter mogelijk om Bicep automatisch afhankelijkheden te laten detecteren. Wanneer u de symbolische naam van de ene resource binnen een eigenschap van een andere resource gebruikt, detecteert Bicep de relatie. Het is beter om Bicep deze zelf te laten beheren wanneer u dat kunt. Als u de sjabloon wijzigt, zorgt Bicep ervoor dat de afhankelijkheden altijd juist zijn en voegt u geen onnodige code toe waardoor uw sjabloon lastiger en moeilijker te lezen is.

Hoe drukt u relaties tussen bovenliggende en onderliggende items uit?

Azure Resource Manager en Bicep hebben het concept van onderliggende resources, wat alleen zinvol is wanneer ze binnen de context van hun bovenliggende resource worden geïmplementeerd. Een Azure SQL-database is bijvoorbeeld een onderliggend element van een SQL Server-exemplaar. Er zijn verschillende manieren om onderliggende resources te definiëren, maar in de meeste gevallen is het een goed idee om de parent eigenschap te gebruiken. Dit helpt Bicep de relatie te begrijpen, zodat deze validatie kan bieden in Visual Studio Code en de relatie duidelijk maakt voor iedereen die de sjabloon leest.

Hoe stelt u resource-eigenschappen in?

U moet de waarden voor resource-eigenschappen in uw Bicep-bestanden opgeven. Het is een goed idee om attent te zijn wanneer u hardcoderingswaarden in uw resourcedefinities gebruikt. Als u weet dat de waarden niet veranderen, is het mogelijk beter om ze hard te coderen dan het gebruik van een andere parameter waarmee uw sjabloon moeilijker kan worden getest en ermee kan worden gewerkt. Als de waarden kunnen veranderen, kunt u deze echter definiëren als parameters of variabelen om uw Bicep-code dynamischer en herbruikbaarder te maken.

Wanneer u hardcodewaarden uitvoert, is het goed om ervoor te zorgen dat ze begrijpelijk zijn voor anderen. Als een eigenschap bijvoorbeeld moet worden ingesteld op een specifieke waarde voor de resource om zich correct te gedragen voor uw oplossing, kunt u overwegen een goed benoemde variabele te maken die een uitleg geeft en vervolgens de waarde toewijst met behulp van de variabele. Voor situaties waarin de naam van een variabele niet het hele verhaal vertelt, kunt u overwegen een opmerking toe te voegen. Verderop in deze module vindt u meer informatie over opmerkingen.

Als u voor sommige resource-eigenschappen automatisch waarden wilt maken, moet u complexe expressies maken die functies en tekenreeksinterpolatie bevatten. Uw Bicep-code is meestal duidelijker wanneer u variabelen declareert en ernaar verwijst in de resourcecodeblokken.

Tip

Wanneer u uitvoer maakt, kunt u resource-eigenschappen gebruiken, waar u dat ook kunt. Vermijd het opnemen van uw eigen veronderstellingen over de werking van resources, omdat deze veronderstellingen na verloop van tijd kunnen veranderen.

Als u bijvoorbeeld de URL van een App Service-app moet uitvoeren, vermijdt u het maken van een URL:

output hostname string = '${app.name}.azurewebsites.net'

De voorgaande benadering wordt verbroken als App Service de manier wijzigt waarop hostnamen worden toegewezen aan apps of als u implementeert in Azure-omgevingen die gebruikmaken van verschillende URL's.

Gebruik in plaats daarvan de defaultHostname eigenschap van de app-resource:

output hostname string = app.properties.defaultHostname

Hoe gebruikt u versiebeheer effectief?

Met versiebeheersystemen zoals Git kunt u uw werk vereenvoudigen wanneer u code herstructureert.

Omdat versiebeheersystemen zijn ontworpen om de wijzigingen in uw bestanden bij te houden, kunt u deze gebruiken om eenvoudig terug te keren naar een oudere versie van uw code als u een fout maakt. Het is een goed idee om uw werk vaak vast te leggen, zodat u terug kunt gaan naar het exacte tijdstip dat u nodig hebt.

Met versiebeheer kunt u ook oude code uit uw Bicep-bestanden verwijderen. Wat gebeurt er als uw Bicep-code een resourcedefinitie bevat die u niet meer nodig hebt? Mogelijk hebt u de definitie in de toekomst opnieuw nodig en is het verleidelijk om de definitie uit te voeren en in het bestand te bewaren. Maar als u het bestand alleen overzichtelijk houdt, is het voor anderen lastig om te begrijpen waarom de uitgecommentarieerde resources er nog steeds zijn.

Een andere overweging is dat iemand per ongeluk opmerkingen bij de definitie kan opheffen, met onvoorspelbare of mogelijk negatieve resultaten. Wanneer u een versiebeheersysteem gebruikt, kunt u gewoon de oude resourcedefinitie verwijderen. Als u de definitie later opnieuw nodig hebt, kunt u deze ophalen uit de bestandsgeschiedenis.