Skriva en anpassningsfil för en utvecklingsruta
I den här artikeln får du lära dig hur du skapar och testar en anpassningsfil för din utvecklingsruta med hjälp av Visual Studio Code (VS Code) och Dev Home.
Det finns två sätt att använda en anpassningsfil i Microsoft Dev Box. Teamanpassningar tillämpas automatiskt när utvecklare konfigurerar dem i en pool. Enskilda anpassningar tillämpas när en användare skapar en utvecklingsruta.
Den här artikeln hjälper dig att definiera nya uppgifter i anpassningsfilen, tillämpa dem på dina dev-rutor och testa dessa anpassningar direkt i VS Code.
Viktigt!
Dev Box-teamets anpassningsfunktion är för närvarande i förhandsversion. Mer information om förhandsversionens status finns i Kompletterande användningsvillkor för Förhandsversioner av Microsoft Azure. Dokumentet definierar juridiska villkor som gäller för Azure-funktioner som är i betaversion, förhandsversion eller som inte ännu släppts i allmän tillgänglighet.
Förutsättningar
För att slutföra stegen i den här artikeln måste du:
- Ha ett dev center konfigurerat med en dev box-definition, dev box-pool och dev box-projekt så att du kan skapa en utvecklingsruta.
- Vara medlem i säkerhetsgruppen Dev Box-användare för minst ett projekt.
- Ha en katalog kopplad till utvecklingscentret med uppgifter som du kan använda i anpassningsfilen. Om du inte har någon katalog kan du läsa Lägga till och konfigurera en katalog från GitHub eller Azure Repos.
Behörigheter som krävs för att konfigurera anpassningar
Om du vill utföra de åtgärder som krävs för att skapa och tillämpa anpassningar på en utvecklingsruta behöver du följande behörigheter:
| Åtgärd | Behörighet/roll |
|---|---|
| Aktivera kataloger på projektnivå för ett utvecklingscenter. | Plattformstekniker med skrivåtkomst till prenumerationen. |
| Aktivera inställningar för katalogsynkronisering för ett projekt. | Plattformstekniker med skrivåtkomst till prenumerationen. |
| Koppla en katalog till ett projekt. | Projektadministratörs- eller deltagarbehörigheter för projektet. |
| Skapa en anpassningsfil. | Ingen har angetts. Vem som helst kan skapa en anpassningsfil. |
| Använd utvecklarportalen för att ladda upp och tillämpa en YAML-fil när dev box skapas. | Dev Box-användare. |
| Lägg till uppgifter i en katalog. | Behörighet att lägga till på den lagringsplats som är värd för katalogen. |
Vad är en anpassningsfil?
Dev Box-anpassningar använder en YAML-formaterad fil för att ange en lista över uppgifter som ska tillämpas när en utvecklare skapar en utvecklingsruta. Dessa uppgifter kan vara så enkla som att installera ett paket eller så avancerat som att köra en komplex uppsättning skript för att konfigurera en kodbas. Uppgifter identifierar katalogen och anger parametrar som namnet på den programvara som ska installeras. Anpassningsfilen görs sedan tillgänglig för de utvecklare som skapar dev-rutor.
I följande exempel används en winget uppgift för att installera VS Code och en git-clone uppgift för att klona en lagringsplats:
# 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
Det finns två sätt att använda en anpassningsfil: enskilda anpassningar gäller för en enda utvecklingsruta och teamanpassningar gäller för ett helt team.
Enskilda anpassningsfiler
- Innehåller uppgifter som tillämpas när en utvecklare skapar en utvecklingsruta.
- Laddas upp av utvecklaren när en utvecklingsruta skapas.
Teamanpassningsfiler
- Innehåller uppgifter som tillämpas när en utvecklare skapar en utvecklingsruta.
- Delas mellan ett team eller projekt.
- Inkludera ett fält som anger basavbildningen.
- Heter imagedefinition.yaml.
- Laddas upp till lagringsplatsen som är värd för en katalog.
- Används automatiskt när en utvecklare skapar en utvecklingsruta från en konfigurerad pool.
Viktigt!
Bilddefinitioner kan endast använda Dev Box Marketplace-avbildningar som basavbildningar. Använd det här Azure CLI-kommandot för att hämta en lista över avbildningar som utvecklingscentret kan komma åt:
az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"
Skapa en anpassningsfil
Du kan skapa och hantera anpassningsfiler med hjälp av VS Code. Du kan använda Microsoft Dev Box-tillägget i VS Code för att identifiera uppgifterna i den bifogade katalogen och testa anpassningsfilen.
Skapa en utvecklingsruta (eller använd en befintlig utvecklingsruta) för testning.
Installera VS Code i test-utvecklingsrutan och installera sedan Dev Box-tillägget.
Ladda ned en YAML-exempelanpassningsfil från exempellagringsplatsen och öppna den i VS Code.
Identifiera uppgifter som är tillgängliga i katalogen med hjälp av kommandopaletten. Välj Visa>kommandopaletten>Dev Box: Lista tillgängliga uppgifter för den här dev boxen.
Testa anpassningen i VS Code med hjälp av kommandopaletten. Välj Visa>kommandopalettutvecklingsruta>: Tillämpa anpassningsuppgifter.
Anpassningsfilen körs omedelbart och tillämpar de angivna uppgifterna på testutvecklingsrutan. Granska ändringarna och kontrollera VS Code-terminalen om det finns fel eller varningar som genererats under aktivitetskörningen.
När anpassningsfilen körs laddar du upp den till katalogen.
Klona en privat lagringsplats med hjälp av en anpassningsfil
Du kan använda hemligheter från ditt Azure-nyckelvalv i yaml-anpassningar för att klona privata lagringsplatser, eller med alla anpassade uppgifter som du skapar som kräver en åtkomsttoken. I en teamanpassningsfil kan du använda en personlig åtkomsttoken (PAT) som lagras i ett nyckelvalv för att få åtkomst till en privat lagringsplats.
Använda key vault-hemligheter i teamanpassningsfiler
Om du vill klona en privat lagringsplats lagrar du din PAT som en nyckelvalvshemlighet och använder den när du anropar uppgiften i anpassningen git-clone .
Så här konfigurerar du dina nyckelvalvshemligheter för användning i YAML-anpassningar:
- Kontrollera att dev center-projektets hanterade identitet har rollen Key Vault-läsare och rollen Key Vault Secrets User i nyckelvalvet.
- Ge key vault-hemligheterna användarrollen för nyckelvalvets hemlighet till varje användare eller användargrupp som ska kunna använda hemligheten under anpassningen av en utvecklingsruta. Den användare eller grupp som har beviljats rollen måste innehålla den hanterade identiteten för utvecklingscentret, ditt eget användarkonto och alla användare eller grupper som behöver hemligheten under anpassningen av en utvecklingsruta.
Mer information finns i:
- Konfigurera en hanterad identitet för ett utvecklingscenter
- Ge den hanterade identiteten åtkomst till nyckelvalvets hemlighet
Du kan referera till hemligheten i yaml-anpassningen i följande format, som använder git-clone uppgiften som ett exempel:
$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}}'
Använda key vault-hemligheter i enskilda anpassningsfiler
Om du vill klona en privat Azure Repos-lagringsplats från en enskild anpassningsfil behöver du inte konfigurera en hemlighet i Azure Key Vault. I stället kan du använda {{ado}} eller {{ado://your-ado-organization-name}} som en parameter. Den här parametern hämtar en åtkomsttoken åt dig när du skapar en utvecklingsruta. Åtkomsttoken har skrivskyddad behörighet till lagringsplatsen.
Uppgiften git-clone i snabbstartskatalogen använder åtkomsttoken för att klona lagringsplatsen. Här är ett exempel:
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}}'
Utvecklingscentret behöver åtkomst till ditt nyckelvalv. Dev Centers stöder inte tjänsttaggar, så om nyckelvalvet hålls privat måste du tillåta att betrodda Microsoft-tjänster kringgår brandväggen.
Information om hur du tillåter att betrodda Microsoft-tjänster kringgår brandväggen finns i Konfigurera nätverksinställningar för Azure Key Vault.
Anpassa utvecklingsrutan med hjälp av befintliga WinGet-konfigurationsfiler
WinGet-konfigurationen använder en metod för konfiguration som kod för att definiera de unika uppsättningar av program- och konfigurationsinställningar som behövs för att få Windows-miljön i ett kodklart tillstånd. Du kan också använda de här konfigurationsfilerna för att konfigurera en utvecklingsruta med hjälp av en WinGet-uppgift som ingår i snabbstartskatalogen som tillhandahålls av Microsoft.
I följande exempel visas en dev box-anpassningsfil som anropar en befintlig DSC-fil (WinGet Desired State Configuration):
tasks:
- name: winget
parameters:
configure: "projectConfiguration.dsc.yaml"
Mer information finns i WinGet-konfiguration.
Dela en anpassningsfil från en kodlagringsplats
Gör anpassningsfilen tillgänglig för dev box-pooler genom att namnge den imagedefinition.yaml och genom att ladda upp den till den lagringsplats som är värd för katalogen. När du skapar en dev box-pool kan du välja anpassningsfilen från katalogen som ska tillämpas på dev-rutorna i poolen.