Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
In this quickstart, you create a dev box by using Microsoft Dev Box team customizations. The feature uses an image definition file so that you can create consistently customized dev boxes for your development team and provide a tailored environment for your projects.
Prerequisites
Product | Requirements |
---|---|
Microsoft Dev Box | - Set up a dev center with a dev box pool and a dev box project so you can create a dev box. - Attach a catalog to the dev center with tasks you can use in your image definition file. If you don't have a catalog, see Add and configure a catalog from GitHub or Azure Repos. - Permissions - To create a dev box: Join the Dev Box Users security group for at least one project. - To enable project-level catalogs for a dev center: Platform engineer with write access on the subscription. - To enable catalog sync settings for a project: Platform engineer with write access on the subscription. - To attach a catalog to a project: Dev Center Project Admin or Contributor permissions on the project. - To create a customization file: None specified. Anyone can create a customization file. - To use the developer portal to upload and apply a YAML file during dev box creation: Dev Box User. - To add tasks to a catalog: Permission to add to the repository that hosts the catalog. |
Visual Studio Code | - Install the latest version |
Create an image definition
To create a dev box with customizations, you must create an image definition file. The image definition file is a YAML file that contains the customizations that you want to apply to the dev box. You can use the example image definition file in this quickstart as a starting point.
Enable project-level catalogs
You must enable project-level catalogs at the dev center level before you can add a catalog to a project.
In the Azure portal, go to your dev center.
On the service menu, under Settings, select Dev center settings.
Under Project level catalogs, select Enable catalogs per project, and then select Apply.
Add a catalog to your project
The sections that follow walk you through these tasks:
- Fork the example catalog repository to your GitHub organization.
- Configure sync settings to synchronize the catalog with your project.
- Add your repository as a catalog.
Fork the example catalog repository
Open the example catalog repository.
Select Fork > Create a new fork to fork the repository to your GitHub organization.
Configure catalog sync settings
Switch back to the Azure portal.
In the search box, enter projects. In the list of results, select Projects.
Select the project you want to add the catalog to.
On the left menu, select Settings > Catalogs.
Select Sync settings.
On the Sync settings pane:
- If Image definitions is cleared, select it and select Save.
- If Image definitions is already selected, select Cancel.
Add your repository as a catalog
On the Catalogs page, select Add.
On the Add catalog pane, enter or select the following values:
Field Value Name Enter a name for the catalog. Catalog source Select GitHub. Authentication type Select GitHub app. Select the configure your repositories link.
If you're prompted to authenticate to GitHub, authenticate.
On the Microsoft DevCenter page, select Configure.
Select the GitHub organization that contains the repository you want to add as a catalog. You must be an owner of the organization to install this app.
On the Install Microsoft DevCenter page, select Only select repositories, select the repository that you want to add as a catalog, and then select Save.
You can select multiple repositories to add as catalogs. You must add each repository as a separate catalog, as described in the next section of this quickstart.
Switch back to the Azure portal.
On the Add catalog pane, select Sign in with GitHub.
On the Add catalog pane, enter the following information, and then select Add:
Field Value Repo Select the repository that contains your image definition.
Example: eShopBranch Select the branch.
Example: mainFolder path Select the folder that contains subfolders that hold your image definitions.
Example: .devcenter/catalog/image-definitionsIn the Catalogs pane, verify that your catalog appears. When the connection is successful, the Status column shows Sync successful.
Verify that the image definitions are correctly synced. On the left menu, select Manage > Image definitions. In this example, you see two image definitions:
- backend-dev - This image is a Microsoft Visual Studio + Tools image on Windows 11, suitable for the eShop backend engineering environment.
- frontend-dev - This image is a Microsoft Visual Studio + Tools image on Windows 11, suitable for the eShop frontend engineering environment.
Create a dev box pool for the image definition
To make the customization file, imagedefintion.yaml, accessible for creating dev boxes, you specify it as the image definition for a pool.
To create a dev box pool associated with a project:
In the Azure portal.
In the search box, enter projects. In the list of results, select Projects.
Open the project in which you want to create the dev box pool.
On the left menu, select Manage > Dev box pools
On the Dev box pools page, select Create.
On the Create a dev box pool pane, enter the following values:
Setting Value Name Enter a descriptive name for the pool. The pool name is visible to developers to select when they're creating dev boxes, so include the purpose and region of the pool. The name must be unique within a project.
Example: contoso-frontend-westUSDefinition From the image definition section of the list, select an image definition.
Example: contoso-catalog/frontend-devCompute Select the compute resources for the dev boxes in the pool.
Example: 8 vCPU, 32-GB RAMStorage Select the storage options for the dev boxes in the pool.
Example: 256 GB SSDHibernation Hibernation is supported when the source image and compute size are both hibernation compatible. Network connection 1. Select Deploy to a Microsoft hosted network.
2. Select a deployment region for the dev boxes. Choose a region close to your dev box users for the optimal user experience.
Example: West USLicensing Select this checkbox to confirm that your organization has Azure Hybrid Benefit licenses that you want to apply to the dev boxes in this pool. Select Create.
Verify that the new dev box pool appears in the list. You might need to refresh the screen.
The Azure portal deploys the dev box pool and runs health checks to ensure that the image and network pass the validation criteria for dev boxes.
Create a dev box from the dev box pool
When you create a dev box from a dev box pool, the image definition is applied to the dev box. The dev box is created with the customizations that the image definition file specified.
To create a dev box in the Microsoft Dev Box developer portal:
Sign in to the Microsoft Dev Box developer portal.
Select New > New dev box.
In Add a dev box, enter the following values:
Setting Value Name Enter a name for your dev box. Dev box names must be unique within a project.
Example: contoso-frontend-dev-boxProject The developer portal lists the projects you have access to. Select the project you need from the list. Dev box pool The developer portal lists all the dev box pools for the project you selected. Select the appropriate pool for your work. Choose a dev box pool near to you for the lowest latency. Apply customizations Leave this check box cleared. It's used to apply user customizations. In this article you've configured team customizations. After you make your selections, the page shows the following information:
- Whether hibernation is supported or not.
- A notification that the dev box creation process can take 25 minutes or longer.
Select Create to begin creating your dev box.
To track the progress of creation, use the dev box tile in the developer portal.
Verify that the customizations are applied
Dev Box applies customizations as the final stage of the creation process. Dev Box emails you when the dev box is ready. Then you can check that your customizations are applied.
Wait for the dev box to be created.
In the developer portal, on the dev box tile, select Actions > Customizations.
On the Customization details pane, confirm the customizations that were applied to the dev box.
Clean up resources
Sign in to the developer portal.
For the dev box that you want to delete, on the Actions menu, select Delete.
To confirm the deletion, select Delete.