Schreiben einer Anpassungsdatei für eine Dev-Box

In diesem Artikel erfahren Sie, wie Sie mithilfe von Visual Studio Code (VS Code) und Dev Home eine Anpassungsdatei für Ihre Dev-Box erstellen und testen.

Es gibt zwei Möglichkeiten, eine Anpassungsdatei in Microsoft Dev Box zu verwenden. Teamanpassungen werden automatisch angewendet, wenn Entwickler sie in einem Pool konfigurieren. Einzelne Anpassungen werden angewendet, wenn ein Benutzer eine Dev-Box erstellt.

Dieser Artikel unterstützt Sie beim Definieren neuer Aufgaben in Ihrer Anpassungsdatei, beim Anwenden auf Ihre Dev-Boxen und beim Testen dieser Anpassungen direkt in VS Code.

Voraussetzungen

Zur Durchführung der in diesem Artikel aufgeführten Schritte müssen Sie:

• Ein Dev Center mit einer Dev-Box-Definition, einem Dev-Box-Pool und einem Dev-Box-Projekt konfiguriert haben, damit Sie eine Dev-Box erstellen können
• Sie müssen Mitglied der Sicherheitsgruppe mit Dev Box-Benutzern für mindestens ein Projekt sein.
• An Dev Center muss ein Katalog mit Aufgaben angefügt sein, die Sie in Ihrer Anpassungsdatei verwenden können. Wenn Sie keinen Katalog besitzen, lesen Sie die Informationen unter Hinzufügen und Konfigurieren eines Katalogs aus GitHub oder Azure Repos.

Erforderliche Berechtigungen zum Konfigurieren von Anpassungen

Um die erforderlichen Aktionen zum Erstellen und Anwenden von Anpassungen auf eine Dev-Box auszuführen, benötigen Sie die folgenden Berechtigungen:

Was ist eine Anpassungsdatei?

Dev Box-Anpassungen nutzen eine Datei im YAML-Format, um eine Liste von Tasks anzugeben, die beim Erstellen einer Dev-Box durch einen Entwickler angewendet werden sollen. Diese Aufgaben können so einfach wie die Installation eines Pakets oder so anspruchsvoll wie das Ausführen einer komplexen Reihe von Skripts zum Einrichten einer Codebasis sein. Aufgaben identifizieren den Katalog und stellen Parameter wie den Namen der zu installierenden Software bereit. Die Anpassungsdatei wird dann den Entwicklern zur Verfügung gestellt, die Dev-Boxen erstellen.

Im folgenden Beispiel wird ein winget-Task zum Installieren von Visual Studio Code und ein git-clone-Task zum Klonen eines Repositorys verwendet:

# 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

Es gibt zwei Möglichkeiten, eine Anpassungsdatei zu verwenden: einzelne Anpassungen, die für eine einzelne Dev-Box gelten, und Teamanpassungen, die für ein ganzes Team gelten.

Einzelne Anpassungsdateien

• Enthalten Aufgaben, die angewendet werden, wenn ein Entwickler eine Dev-Box erstellt.
• Werden während der Erstellung einer Dev-Box vom Entwickler hochgeladen.

Teamanpassungsdateien

• Enthalten Aufgaben, die angewendet werden, wenn ein Entwickler eine Dev-Box erstellt.
• Werden für ein Team oder Projekt freigegeben.
• Enthalten ein Feld, das das Basisimage angibt.
• Haben den Namen imagedefinition.yaml.
• Werden in das Repository hochgeladen, das einen Katalog hostet.
• Werden automatisch verwendet, wenn ein Entwickler eine Dev-Box aus einem konfigurierten Pool erstellt.

az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"

Erstellen einer Anpassungsdatei

Sie können Anpassungsdateien mithilfe von VS Code erstellen und verwalten. Sie können die Microsoft Dev Box-Erweiterung in VS Code verwenden, um die Aufgaben im angefügten Katalog zu ermitteln und die Anpassungsdatei in zu testen.

1. Erstellen Sie eine Dev-Box (oder verwenden Sie eine vorhandene Dev-Box) zum Testen.

2. Installieren Sie VS Code in der Test-Dev-Box und dann die Dev Box-Erweiterung.

3. Laden Sie eine Beispiel-YAML-Anpassungsdatei aus dem Beispielrepository herunter, und öffnen Sie sie in VS Code.

4. Erkunden Sie über die Befehlspalette Tasks, die im Katalog verfügbar sind. Wählen Sie Ansicht>Befehlspalette>Dev-Box: Verfügbare Tasks für diese Dev-Box auflisten aus.

   

5. Testen Sie die Anpassung in VS Code mithilfe der Befehlspalette. Wählen Sie Ansicht>Befehlspalette>Dev-Box: Anpassungstasks anwenden aus.

   

6. Die Anpassungsdatei wird sofort ausgeführt und wendet die angegebenen Tasks auf die Test-Dev-Box an. Sehen Sie sich die Änderungen an, und überprüfen Sie das VS Code-Terminal auf Fehler oder Warnungen, die während der Taskausführung generiert wurden.

7. Wenn die Anpassungsdatei erfolgreich ausgeführt wird, laden Sie sie in Ihren Katalog hoch.

Klonen eines privaten Repositorys mithilfe einer Anpassungsdatei

Sie können Geheimnisse aus Ihrem Azure-Schlüsseltresor in Ihren YAML-Anpassungen verwenden, um private Repositorys zu klonen, oder mit jeder benutzerdefinierten Aufgabe, die Sie verfassen und die ein Zugriffstoken erfordert. In einer Teamanpassungsdatei können Sie ein persönliches Zugriffstoken (Personal Access Token, PAT) verwenden, das in einem Schlüsseltresor gespeichert ist, um auf ein privates Repository zuzugreifen.

Verwenden von Schlüsseltresorgeheimnissen in Teamanpassungsdateien

Um ein privates Repository zu klonen, speichern Sie das PAT als Schlüsseltresorgeheimnis, und verwenden Sie es, wenn Sie die Aufgabe git-clone in Ihrer Anpassung aufrufen.

So konfigurieren Sie Ihre Schlüsseltresorgeheimnisse für die Verwendung in YAML-Anpassungen

1. Stellen Sie sicher, dass die verwaltete Identität Ihres Dev Center-Projekts die Rollen „Leseberechtigter für Schlüsseltresore“ und „Geheimnisbenutzer für Schlüsseltresore“ für Ihren Schlüsseltresor besitzt.
2. Gewähren Sie die Rolle „Geheimnisbenutzer für Schlüsseltresore“ für das Schlüsseltresorgeheimnis jeder benutzenden Person oder Benutzergruppe, die in der Lage sein soll, das Geheimnis während der Anpassung einer Dev-Box zu verwenden. Zu den benutzenden Personen oder Gruppen, denen die Rolle zugewiesen wird, müssen die verwaltete Identität für das Dev Center, Ihr eigenes Benutzerkonto und alle benutzenden Personen oder Gruppen gehören, die das Geheimnis während der Anpassung einer Dev-Box benötigen.

Weitere Informationen finden Sie unter:

• Konfigurieren einer verwalteten Identität für ein Dev Center
• Gewähren des Zugriffs der verwalteten Identität auf das Schlüsseltresorgeheimnis

Sie können in Ihrer YAML-Anpassung in folgendem Format auf das Geheimnis verweisen, wobei die Aufgabe git-clone als Beispiel verwendet wird:

$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}}'

Verwenden von Schlüsseltresorgeheimnissen in einzelnen Anpassungsdateien

Wenn Sie ein privates Azure Repos-Repository aus einer einzelnen Anpassungsdatei klonen möchten, müssen Sie kein Geheimnis in Azure Key Vault konfigurieren. Stattdessen können Sie {{ado}} oder {{ado://your-ado-organization-name}} als Parameter verwenden. Dieser Parameter ruft ein Zugriffstoken in Ihrem Auftrag ab, wenn Sie eine Dev-Box erstellen. Das Zugriffstoken verfügt über die Berechtigung „Nur lesen“ für Ihr Repository.

Die Aufgabe git-clone im Schnellstartkatalog verwendet das Zugriffstoken, um Ihr Repository zu klonen. Hier sehen Sie ein Beispiel:

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}}'

Dev Center benötigt Zugriff auf Ihren Schlüsseltresor. Dev Center unterstützen keine Diensttags. Wenn Ihr Schlüsseltresor privat ist, müssen Sie vertrauenswürdigen Microsoft-Diensten also erlauben, die Firewall zu umgehen.

Wie Sie vertrauenswürdigen Microsoft-Diensten erlauben, die Firewall zu umgehen, erfahren Sie unter Konfigurieren von Azure Key Vault-Netzwerkeinstellungen.

Anpassen Ihrer Dev-Box mithilfe vorhandener WinGet-Konfigurationsdateien

Eine WinGet-Konfiguration verwendet einen Config-as-Code-Ansatz (Konfiguration als Code), um die eindeutigen Software- und Konfigurationseinstellungen zu definieren, die erforderlich sind, um Ihre Windows-Umgebung in einen programmierbereiten Zustand zu versetzen. Sie können diese Konfigurationsdateien auch zum Einrichten einer Dev-Box verwenden, indem Sie eine WinGet-Aufgabe verwenden, die in dem von Microsoft bereitgestellten Schnellstartkatalog enthalten ist.

Das folgende Beispiel zeigt eine Dev-Box-Anpassungsdatei, die eine vorhandene WinGet-DSC-Datei (Desired State Configuration, Konfiguration des gewünschten Zustands) aufruft.

tasks:
    - name: winget
      parameters:
          configure: "projectConfiguration.dsc.yaml"

Weitere Informationen finden Sie unter WinGet-Konfiguration.

Freigeben einer Anpassungsdatei aus einem Coderepository

Stellen Sie Ihre Anpassungsdatei für Dev-Box-Pools zur Verfügung, indem Sie sie „imagedefinition.yaml“ nennen und in das Repository hochladen, das den Katalog hostet. Wenn Sie einen Dev-Box-Pool erstellen, können Sie die Anpassungsdatei aus dem Katalog auswählen, die auf die Dev-Boxen im Pool angewendet werden soll.

Zugehöriger Inhalt

• Microsoft Dev Box-Teamanpassungen
• Konfigurieren der Imageerstellung für Dev Box-Teamanpassungen
• Hinzufügen und Konfigurieren eines Katalogs aus GitHub oder Azure Repos