Pisanie pliku dostosowywania dla pola deweloperskiego
Z tego artykułu dowiesz się, jak utworzyć i przetestować plik dostosowywania dla pola deweloperskiego przy użyciu programu Visual Studio Code (VS Code) i Strona główna deweloperów.
Istnieją dwa sposoby używania pliku dostosowywania w usłudze Microsoft Dev Box. Dostosowania zespołu są stosowane automatycznie, gdy deweloperzy konfigurują je w puli. Poszczególne dostosowania są stosowane, gdy użytkownik tworzy pole deweloperskie.
Ten artykuł ułatwia definiowanie nowych zadań w pliku dostosowywania, stosowanie ich do pól deweloperskich i testowanie tych dostosowań bezpośrednio w programie VS Code.
Ważne
Funkcja dostosowywania zespołu usługi Dev Box jest obecnie dostępna w wersji zapoznawczej. Aby uzyskać więcej informacji na temat stanu wersji zapoznawczej, zobacz Dodatkowe warunki użytkowania dla wersji zapoznawczych platformy Microsoft Azure. Dokument definiuje postanowienia prawne, które dotyczą funkcji platformy Azure, które są w wersji beta, w wersji zapoznawczej lub w inny sposób nie zostały jeszcze wydane do ogólnej dostępności.
Wymagania wstępne
Aby wykonać kroki opisane w tym artykule, należy wykonać następujące czynności:
- Mieć centrum deweloperskie skonfigurowane z definicją pola deweloperskiego, pulą usługi Dev Box i projektem usługi Dev Box, aby można było utworzyć pole deweloperskie.
- Być członkiem grupy zabezpieczeń Dev Box Users dla co najmniej jednego projektu.
- Katalog dołączony do centrum deweloperów z zadaniami, których można użyć w pliku dostosowywania. Jeśli nie masz wykazu, zobacz Dodawanie i konfigurowanie wykazu z repozytoriów GitHub lub Azure Repos.
Uprawnienia wymagane do konfigurowania dostosowań
Aby wykonać wymagane akcje tworzenia i stosowania dostosowań w polu deweloperskim, potrzebne są następujące uprawnienia:
| Akcja | Uprawnienie/rola |
|---|---|
| Włącz katalogi na poziomie projektu dla centrum deweloperów. | Inżynier platformy z dostępem do zapisu w subskrypcji. |
| Włącz ustawienia synchronizacji katalogu dla projektu. | Inżynier platformy z dostępem do zapisu w subskrypcji. |
| Dołączanie wykazu do projektu. | Uprawnienia administratora lub współautora projektu. |
| Utwórz plik dostosowywania. | Nie określono żadnego. Każdy może utworzyć plik dostosowywania. |
| Użyj portalu dla deweloperów, aby przekazać i zastosować plik YAML podczas tworzenia pola deweloperskiego. | Użytkownik usługi Dev Box. |
| Dodawanie zadań do wykazu. | Uprawnienie do dodawania do repozytorium hostujące wykaz. |
Co to jest plik dostosowywania?
Dostosowania usługi Dev Box używają pliku w formacie YAML, aby określić listę zadań, które mają być stosowane, gdy deweloper tworzy pole deweloperskie. Te zadania mogą być tak proste, jak instalowanie pakietu lub tak zaawansowane, jak uruchamianie złożonego zestawu skryptów w celu skonfigurowania bazy kodu. Zadania identyfikują katalog i podaj parametry, takie jak nazwa oprogramowania do zainstalowania. Plik dostosowywania jest następnie udostępniany deweloperom, którzy tworzą pola deweloperskie.
W poniższym przykładzie winget użyto zadania do zainstalowania programu VS Code i git-clone zadania klonowania repozytorium:
# 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
Istnieją dwa sposoby użycia pliku dostosowywania: poszczególne dostosowania mają zastosowanie do pojedynczego pola deweloperskiego, a dostosowania zespołu mają zastosowanie do całego zespołu.
Pojedyncze pliki dostosowywania
- Zawierają zadania, które są stosowane, gdy deweloper tworzy pole deweloperskie.
- Są przekazywane przez dewelopera podczas tworzenia pola deweloperskiego.
Pliki dostosowywania zespołu
- Zawierają zadania, które są stosowane, gdy deweloper tworzy pole deweloperskie.
- Są współużytkowane przez zespół lub projekt.
- Dołącz pole określające obraz podstawowy.
- Nazwa to imagedefinition.yaml.
- Są przekazywane do repozytorium hostujące wykaz.
- Są używane automatycznie, gdy deweloper tworzy pole deweloperskie ze skonfigurowanej puli.
Ważne
Definicje obrazów mogą używać tylko obrazów platformy Handlowej usługi Dev Box jako obrazów podstawowych. Aby uzyskać listę obrazów, do których centrum deweloperów ma dostęp, użyj tego polecenia interfejsu wiersza polecenia platformy Azure:
az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"
Tworzenie pliku dostosowywania
Pliki dostosowywania można tworzyć i zarządzać nimi przy użyciu programu VS Code. Rozszerzenie Microsoft Dev Box w programie VS Code umożliwia odnajdywanie zadań w dołączonym wykazie i testowanie pliku dostosowywania.
Utwórz pole deweloperskie (lub użyj istniejącego pola deweloperskiego) do testowania.
W polu deweloperskim testowym zainstaluj program VS Code, a następnie zainstaluj rozszerzenie Dev Box.
Pobierz przykładowy plik dostosowywania YAML z repozytorium przykładów i otwórz go w programie VS Code.
Odnajdywanie zadań dostępnych w wykazie przy użyciu palety poleceń. Wybierz pozycję Wyświetl>pole deweloperskie palety>poleceń: wyświetl listę dostępnych zadań dla tego pola deweloperskiego.
Testowanie dostosowywania w programie VS Code przy użyciu palety poleceń. Wybierz pozycję Wyświetl>pole deweloperskie palety>poleceń: Zastosuj zadania dostosowywania.
Plik dostosowywania jest uruchamiany natychmiast i stosuje określone zadania do testowego pola deweloperskiego. Sprawdź zmiany i sprawdź terminal programu VS Code pod kątem błędów lub ostrzeżeń wygenerowanych podczas wykonywania zadania.
Po pomyślnym uruchomieniu pliku dostosowywania przekaż go do katalogu.
Klonowanie prywatnego repozytorium przy użyciu pliku dostosowywania
Możesz użyć wpisów tajnych z magazynu kluczy platformy Azure w dostosowaniach YAML, aby sklonować repozytoria prywatne lub za pomocą dowolnego niestandardowego zadania, które wymaga tokenu dostępu. W pliku dostosowywania zespołu można użyć osobistego tokenu dostępu przechowywanego w magazynie kluczy, aby uzyskać dostęp do repozytorium prywatnego.
Używanie wpisów tajnych magazynu kluczy w plikach dostosowywania zespołu
Aby sklonować repozytorium prywatne, zapisz swój identyfikator dostępu jako wpis tajny magazynu kluczy i użyj go podczas wywoływania zadania w dostosowywaniu git-clone .
Aby skonfigurować wpisy tajne magazynu kluczy do użycia w dostosowaniach YAML:
- Upewnij się, że tożsamość zarządzana projektu centrum deweloperskiego ma rolę Czytelnik usługi Key Vault i rolę Użytkownik wpisów tajnych usługi Key Vault w magazynie kluczy.
- Udziel roli Użytkownik wpisów tajnych usługi Key Vault dla wpisu tajnego magazynu kluczy dla każdego użytkownika lub grupy użytkowników, która powinna mieć możliwość korzystania z wpisu tajnego podczas dostosowywania pola deweloperskiego. Użytkownik lub grupa, któremu udzielono roli, musi zawierać tożsamość zarządzaną centrum deweloperów, własne konto użytkownika oraz dowolny użytkownik lub grupę, która wymaga wpisu tajnego podczas dostosowywania pola deweloperskiego.
Aby uzyskać więcej informacji, zobacz:
- Konfigurowanie tożsamości zarządzanej dla centrum deweloperów
- Udzielanie tożsamości zarządzanej dostępu do wpisu tajnego magazynu kluczy
Wpis tajny można odwołać w dostosowywaniu YAML w następującym formacie, który używa zadania jako przykładu git-clone :
$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}}'
Używanie wpisów tajnych magazynu kluczy w pojedynczych plikach dostosowywania
Jeśli chcesz sklonować prywatne repozytorium usługi Azure Repos z pojedynczego pliku dostosowywania, nie musisz konfigurować wpisu tajnego w usłudze Azure Key Vault. Zamiast tego można użyć parametru {{ado}} lub {{ado://your-ado-organization-name}} jako parametru. Ten parametr pobiera token dostępu w Twoim imieniu podczas tworzenia pola deweloperskiego. Token dostępu ma uprawnienia tylko do odczytu do repozytorium.
Zadanie git-clone w wykazie szybkiego startu używa tokenu dostępu do klonowania repozytorium. Oto przykład:
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}}'
Centrum deweloperskie wymaga dostępu do magazynu kluczy. Centra deweloperów nie obsługują tagów usług, więc jeśli magazyn kluczy jest przechowywany jako prywatny, musisz zezwolić na obejście zapory przez zaufane usługi firmy Microsoft.
Aby dowiedzieć się, jak zezwolić zaufanym usługi firmy Microsoft na obejście zapory, zobacz Konfigurowanie ustawień sieci usługi Azure Key Vault.
Dostosowywanie pola deweloperskiego przy użyciu istniejących plików konfiguracji WinGet
Konfiguracja winGet przyjmuje podejście konfiguracji jako kodu do definiowania unikatowych zestawów ustawień oprogramowania i konfiguracji potrzebnych do uzyskania środowiska systemu Windows w stanie gotowości do kodu. Możesz również użyć tych plików konfiguracji, aby skonfigurować pole deweloperskie przy użyciu zadania WinGet zawartego w wykazie szybkiego startu dostarczonego przez firmę Microsoft.
W poniższym przykładzie pokazano plik dostosowywania pola deweloperskiego, który wywołuje istniejący plik WinGet Desired State Configuration (DSC):
tasks:
- name: winget
parameters:
configure: "projectConfiguration.dsc.yaml"
Aby dowiedzieć się więcej, zobacz Konfiguracja winGet.
Udostępnianie pliku dostosowywania z repozytorium kodu
Udostępnij plik dostosowywania pulom pól deweloperskich, nazywając go imagedefinition.yaml i przekazując go do repozytorium hostujące katalog. Podczas tworzenia puli usługi Dev Box możesz wybrać plik dostosowywania z katalogu, aby zastosować je do pól deweloperskich w puli.