Een aanpassingsbestand schrijven voor een ontwikkelaarsvak
In dit artikel leert u hoe u een aanpassingsbestand voor uw ontwikkelvak maakt en test met behulp van Visual Studio Code (VS Code) en Dev Home.
Er zijn twee manieren om een aanpassingsbestand te gebruiken in Microsoft Dev Box. Teamaanpassingen worden automatisch toegepast wanneer ontwikkelaars deze configureren in een pool. Afzonderlijke aanpassingen worden toegepast wanneer een gebruiker een ontwikkelvak maakt.
Dit artikel helpt u bij het definiëren van nieuwe taken in uw aanpassingsbestand, het toepassen ervan op uw ontwikkelvakken en het testen van deze aanpassingen rechtstreeks in VS Code.
Belangrijk
De functie voor aanpassingen van het Dev Box-team is momenteel beschikbaar als preview-versie. Zie de aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews voor meer informatie over de preview-status. In het document worden juridische termen gedefinieerd die van toepassing zijn op Azure-functies die in bèta, in preview of anderszins nog niet beschikbaar zijn voor algemene beschikbaarheid.
Vereisten
Als u de stappen in dit artikel wilt uitvoeren, moet u het volgende doen:
- Een ontwikkelaarscentrum configureren met een dev box-definitie, dev box-pool en dev box-project, zodat u een ontwikkelvak kunt maken.
- Wees lid van de beveiligingsgroep Dev Box Users voor ten minste één project.
- U hebt een catalogus gekoppeld aan het ontwikkelaarscentrum met taken die u in uw aanpassingsbestand kunt gebruiken. Als u geen catalogus hebt, raadpleegt u Een catalogus toevoegen en configureren vanuit GitHub of Azure-opslagplaatsen.
Vereiste machtigingen voor het configureren van aanpassingen
Als u de vereiste acties wilt uitvoeren voor het maken en toepassen van aanpassingen op een ontwikkelvak, hebt u de volgende machtigingen nodig:
| Actie | Machtiging/rol |
|---|---|
| Schakel catalogi op projectniveau in voor een ontwikkelaarscentrum. | Platformengineer met schrijftoegang voor het abonnement. |
| Synchronisatie-instellingen voor catalogus inschakelen voor een project. | Platformengineer met schrijftoegang voor het abonnement. |
| Voeg een catalogus toe aan een project. | Machtigingen voor projectbeheerder of inzender voor het project. |
| Maak een aanpassingsbestand. | Geen opgegeven. Iedereen kan een aanpassingsbestand maken. |
| Gebruik de ontwikkelaarsportal om een YAML-bestand te uploaden en toe te passen tijdens het maken van het ontwikkelvak. | Dev Box-gebruiker. |
| Taken toevoegen aan een catalogus. | Machtiging om toe te voegen aan de opslagplaats die als host fungeert voor de catalogus. |
Wat is een aanpassingsbestand?
Dev Box-aanpassingen maken gebruik van een BESTAND met YAML-indeling om een lijst met taken op te geven die moeten worden toegepast wanneer een ontwikkelaar een ontwikkelaarsvak maakt. Deze taken kunnen net zo eenvoudig zijn als het installeren van een pakket of zo geavanceerd als het uitvoeren van een complexe set scripts om een codebasis in te stellen. Taken identificeren de catalogus en bieden parameters zoals de naam van de software die moet worden geïnstalleerd. Het aanpassingsbestand wordt vervolgens beschikbaar gesteld aan de ontwikkelaars die ontwikkelvakken maken.
In het volgende voorbeeld wordt een winget taak gebruikt om VS Code te installeren en een git-clone taak om een opslagplaats te klonen:
# From https://github.com/microsoft/devcenter-examples
$schema: 1.0
tasks:
- name: winget
parameters:
package: Microsoft.VisualStudioCode
runAsUser: true
- name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://github.com/OrchardCMS/OrchardCore.git
directory: C:\Workspaces
Er zijn twee manieren om een aanpassingsbestand te gebruiken: afzonderlijke aanpassingen zijn van toepassing op één ontwikkelvak en teamaanpassingen zijn van toepassing op een heel team.
Afzonderlijke aanpassingsbestanden
- Bevat taken die worden toegepast wanneer een ontwikkelaar een ontwikkelvak maakt.
- Worden geüpload door de ontwikkelaar tijdens het maken van een ontwikkelvak.
Teamaanpassingsbestanden
- Bevat taken die worden toegepast wanneer een ontwikkelaar een ontwikkelvak maakt.
- Worden gedeeld in een team of project.
- Voeg een veld toe waarmee de basisinstallatiekopieën worden opgegeven.
- Heeft de naam imagedefinition.yaml.
- Worden geüpload naar de opslagplaats die als host fungeert voor een catalogus.
- Worden automatisch gebruikt wanneer een ontwikkelaar een ontwikkelaarsvak maakt op basis van een geconfigureerde pool.
Belangrijk
Definities van installatiekopieën kunnen alleen Dev Box Marketplace-installatiekopieën gebruiken als basisinstallatiekopieën. Gebruik deze Azure CLI-opdracht om een lijst met installatiekopieën op te halen waartoe uw ontwikkelaarscentrum toegang heeft:
az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"
Een aanpassingsbestand maken
U kunt aanpassingsbestanden maken en beheren met behulp van VS Code. U kunt de Microsoft Dev Box-extensie in VS Code gebruiken om de taken in de bijgevoegde catalogus te detecteren en het aanpassingsbestand te testen.
Maak een ontwikkelvak (of gebruik een bestaand ontwikkelvak) om te testen.
Installeer VS Code in het test dev-vak en installeer vervolgens de Dev Box-extensie.
Download een voorbeeld van een YAML-aanpassingsbestand uit de opslagplaats met voorbeelden en open het in VS Code.
Ontdek taken die beschikbaar zijn in de catalogus met behulp van het opdrachtenpalet. Selecteer Het opdrachtpalet van het opdrachtenpalet>weergeven>: lijst met beschikbare taken voor dit dev-vak.
Test aanpassing in VS Code met behulp van het opdrachtenpalet. Selecteer Het opdrachtpalet van het opdrachtenpalet>weergeven>: Pas aanpassingentaken toe.
Het aanpassingsbestand wordt onmiddellijk uitgevoerd en past de opgegeven taken toe op uw testdev box. Controleer de wijzigingen en controleer de VS Code-terminal op eventuele fouten of waarschuwingen die tijdens de taakuitvoering zijn gegenereerd.
Wanneer het aanpassingsbestand wordt uitgevoerd, uploadt u het naar uw catalogus.
Een privéopslagplaats klonen met behulp van een aanpassingsbestand
U kunt geheimen uit uw Azure-sleutelkluis gebruiken in uw YAML-aanpassingen om privéopslagplaatsen te klonen of met een aangepaste taak die u ontwerpt waarvoor een toegangstoken is vereist. In een teamaanpassingsbestand kunt u een persoonlijk toegangstoken (PAT) gebruiken dat is opgeslagen in een sleutelkluis voor toegang tot een persoonlijke opslagplaats.
Key Vault-geheimen gebruiken in teamaanpassingsbestanden
Als u een privéopslagplaats wilt klonen, slaat u uw PAT op als sleutelkluisgeheim en gebruikt u deze wanneer u de git-clone taak in uw aanpassing aanroept.
Uw sleutelkluisgeheimen configureren voor gebruik in uw YAML-aanpassingen:
- Zorg ervoor dat de beheerde identiteit van uw ontwikkelaarscentrumproject de rol Key Vault Reader en de rol Key Vault Secrets User in uw sleutelkluis heeft.
- Verdeel de rol Key Vault Secrets User voor het sleutelkluisgeheim aan elke gebruiker of gebruikersgroep die het geheim moet kunnen gebruiken tijdens het aanpassen van een ontwikkelvak. De gebruiker of groep waaraan de rol is verleend, moet de beheerde identiteit voor het ontwikkelaarscentrum, uw eigen gebruikersaccount en elke gebruiker of groep bevatten die het geheim nodig heeft tijdens het aanpassen van een ontwikkelvak.
Zie voor meer informatie:
- Een beheerde identiteit configureren voor een ontwikkelaarscentrum
- De beheerde identiteit toegang verlenen tot het sleutelkluisgeheim
U kunt verwijzen naar het geheim in uw YAML-aanpassing in de volgende indeling, die de git-clone taak als voorbeeld gebruikt:
$schema: "1.0"
tasks:
name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
directory: C:\Workspaces
pat: '{{KEY_VAULT_SECRET_URI}}'
Key Vault-geheimen gebruiken in afzonderlijke aanpassingsbestanden
Als u een privéopslagplaats voor Azure-opslagplaatsen wilt klonen vanuit een afzonderlijk aanpassingsbestand, hoeft u geen geheim te configureren in Azure Key Vault. In plaats daarvan kunt u deze gebruiken {{ado}} of {{ado://your-ado-organization-name}} als parameter. Met deze parameter wordt namens u een toegangstoken opgehaald wanneer u een ontwikkelvak maakt. Het toegangstoken heeft alleen-lezenmachtigingen voor uw opslagplaats.
De git-clone taak in de snelstartcatalogus maakt gebruik van het toegangstoken om uw opslagplaats te klonen. Hier volgt een voorbeeld:
tasks:
name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
directory: C:\Workspaces
pat: '{{ado://YOUR_ADO_ORG}}'
Uw ontwikkelaarscentrum heeft toegang nodig tot uw sleutelkluis. Dev Centers bieden geen ondersteuning voor servicetags, dus als uw sleutelkluis privé blijft, moet u vertrouwde Microsoft-services toestaan om de firewall te omzeilen.
Zie Azure Key Vault-netwerkinstellingen configureren voor meer informatie over het toestaan van vertrouwde Microsoft-services om de firewall te omzeilen.
Uw ontwikkelvak aanpassen met behulp van bestaande WinGet-configuratiebestanden
WinGet-configuratie maakt gebruik van een configuratie-as-codebenadering voor het definiëren van de unieke sets software- en configuratie-instellingen die nodig zijn om uw Windows-omgeving in een kant-en-klare codestatus te krijgen. U kunt deze configuratiebestanden ook gebruiken om een ontwikkelvak in te stellen met behulp van een WinGet-taak die is opgenomen in de door Microsoft geleverde snelstartcatalogus.
In het volgende voorbeeld ziet u een dev box-aanpassingsbestand dat een bestaand DSC-bestand (WinGet Desired State Configuration) aanroept:
tasks:
- name: winget
parameters:
configure: "projectConfiguration.dsc.yaml"
Zie De WinGet-configuratie voor meer informatie.
Een aanpassingsbestand delen vanuit een codeopslagplaats
Maak uw aanpassingsbestand beschikbaar voor dev box-pools door het bestand imagedefinition.yaml te benoemen en door het te uploaden naar de opslagplaats die als host fungeert voor uw catalogus. Wanneer u een dev box-pool maakt, kunt u het aanpassingsbestand in de catalogus selecteren om toe te passen op de dev-vakken in de pool.