This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Dev Box Image Definitions Samples

Image definitions samples based on the Front-end and Back-end engineers roles in a team.

1: Back-End Engineering Development
2: Front-End Engineering Development
3:
4:
5:

1 - Back-End Engineering Development

Configuration Sample for .NET Engineers

Overview

This YAML file defines the base image configuration for backend engineers working on the Identity Provider Project Demo at Contoso, using the Microsoft Dev Box Accelerator. It specifies the tools, environment setup, and project-specific tasks required to provision a consistent, ready-to-code development environment in Azure Dev Box. The configuration ensures that all backend engineers have a standardized, secure, and productive workspace aligned with Contoso’s engineering requirements.

Common Engineering DSC Configuration File: Learn more
Back-End Engineering DSC Configuration File: Learn more.

Configurations

Below is a breakdown of each section and key in the YAML file, with explanations and YAML snippets.

Metadata

$schema: "1.0"
name: identityProvider-backend-engineer
description: "This image definition sets up a development environment for backend engineers."
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2

$schema: Version of the image definition schema.
name: Unique identifier for this image definition.
description: Human-readable summary of the image’s purpose.
image: The Microsoft-provided base image (includes Visual Studio 2022, Windows 11, and M365).

Tasks

Defines the mandatory steps to set up the environment.

Core Environment Setup

- name: ~/powershell
  description: "Configure PowerShell environment and install DSC resources"
  parameters:
    command: |
      Set-ExecutionPolicy -ExecutionPolicy Bypass -Force -Scope Process
      Install-PackageProvider -Name NuGet -Force -Scope AllUsers
      Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted
      Install-Module -Name PSDSCResources -Force -AllowClobber -Scope AllUsers

Installs PowerShell DSC resources for consistent environment configuration.

Common Development Tools

- name: ~/winget
  description: "Import common engineering tools and configurations"
  parameters:
    downloadUrl: "https://raw.githubusercontent.com/Evilazaro/DevExp-DevBox/refs/heads/main/.configuration/devcenter/workloads/common-config.dsc.yaml"
    configurationFile: "c:\\winget\\common-config.dsc.yaml"

Imports a shared configuration file for common tools.

- name: ~/winget
  description: "Install GitHub Desktop for visual Git management"
  parameters:
    package: "GitHub.GitHubDesktop"

Installs GitHub Desktop for source control.

- name: ~/git-clone
  description: "Clone the Identity Provider repository to the local workspace"
  parameters:
    repositoryUrl: https://github.com/Evilazaro/IdentityProvider.git
    directory: Z:\Workspaces

Clones the project repository into the workspace.

Backend Development Environment

- name: ~/winget
  description: "Install specialized backend development tools"
  parameters:
    downloadUrl: "https://raw.githubusercontent.com/Evilazaro/DevExp-DevBox/refs/heads/main/.configuration/devcenter/workloads/common-backend-config.dsc.yaml"
    configurationFile: "c:\\winget\\common-backend-config.dsc.yaml"

Installs backend-specific tools (e.g., database, API, server utilities).

User Tasks

Defines optional tasks that individual engineers can run as needed.

userTasks:
  - name: ~/winget
    description: "Install additional backend-specific tools"
    parameters:
      downloadUrl: "https://raw.githubusercontent.com/Evilazaro/DevExp-DevBox/refs/heads/main/.configuration/devcenter/workloads/common-backend-usertasks-config.dsc.yaml"
      configurationFile: "c:\\winget\\common-backend-usertasks-config.dsc.yaml"

Optional backend tools for specialized scenarios.

Environment Maintenance

- name: ~/powershell
  description: "Update Winget Packages"
  parameters:
    command: |
      # Updates all packages, .NET workloads, restores NuGet, builds, and tests the solution

Keeps all installed tools and packages up to date.
Ensures the .NET solution is restored, built, and tested.

Project Setup

- name: ~/powershell
  description: "Build Identity Provider Solution"
  parameters:
    command: |
      # Restores, builds, and tests the solution to validate the environment

Validates that the environment is ready for development by building and testing the main project.

Examples and Use Cases

Example: Provisioning a Dev Box for a New Engineer

Dev Box Service reads this YAML file.
Base image is provisioned with Visual Studio, Windows 11, and M365.
Tasks run automatically:
- PowerShell DSC resources are installed.
- Common and backend tools are set up via WinGet.
- GitHub Desktop is installed.
- The Identity Provider repository is cloned to Z:\Workspaces.
- All packages are updated, and the solution is built and tested.
User Tasks: The engineer can optionally install additional backend tools as needed.

Use Case: Ensuring Consistency Across Teams

All backend engineers receive the same environment, reducing “works on my machine” issues.
Updates and new tools can be rolled out by updating the YAML or referenced configuration files.

Best Practices

Use Microsoft Base Images: Ensures compatibility and support.
Leverage DSC and WinGet: For idempotent, repeatable environment setup.
Centralize Tool Configurations: Reference shared configuration files for consistency.
Separate Mandatory and Optional Tasks: Keep the base image lean and allow customization.
Automate Updates and Validation: Regularly update packages and validate the build/test pipeline as part of environment setup.
Use Trusted Sources: Only install packages from trusted repositories and URLs.
Document Each Section: Use comments in the YAML to explain the purpose of each task.
Follow Azure Dev Box Best Practices: Such as using the Z: drive for workspaces and scoped execution policies for security.

References:

2 - Front-End Engineering Development

Configuration Sample for .NET Engineers

Overview

This YAML configuration file defines the development environment image for frontend engineers working on the Identity Provider Project Demo at Contoso, leveraging the Microsoft Dev Box Accelerator. The file specifies the base image, core tools, environment setup tasks, and optional user tasks to ensure a consistent, secure, and productive workspace for frontend development. It is designed to automate environment provisioning, reduce onboarding friction, and enforce organizational best practices.

Common Engineering DSC Configuration File: Learn more
Front-End Engineering DSC Configuration File: Learn more.

Configurations

Below is a breakdown of each section and key in the YAML file, with explanations and YAML snippets for clarity.

Metadata & Schema

$schema: "1.0"
name: identityProvider-frontend-engineer
description: "This image definition sets up a development environment for frontend engineers."
image: microsoftvisualstudio_windowsplustools_base-win11-gen2

$schema: Specifies the schema version for validation.
name: Unique identifier for the image definition.
description: Human-readable summary of the environment’s purpose.
image: The Microsoft-provided base image (Windows 11 + dev tools), ensuring compatibility and performance.

Tasks

Defines the installation and configuration steps for the environment. Each task is an object with a name, description, and parameters.

Core Environment Setup

- name: ~/powershell
  description: "Configure PowerShell environment and install DSC resources"
  parameters:
    command: |
      Set-ExecutionPolicy -ExecutionPolicy Bypass -Force -Scope Process
      Install-PackageProvider -Name NuGet -Force -Scope AllUsers
      Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted
      Install-Module -Name PSDSCResources -Force -AllowClobber -Scope AllUsers

Purpose: Ensures PowerShell is ready for automation and installs DSC resources for idempotent configuration.

Common Development Tools

- name: ~/winget
  description: "Import common engineering tools and configurations"
  parameters:
    downloadUrl: "https://raw.githubusercontent.com/Evilazaro/DevExp-DevBox/refs/heads/main/.configuration/devcenter/workloads/common-config.dsc.yaml"
    configurationFile: "c:\\winget\\common-config.dsc.yaml"

Purpose: Imports a shared configuration for tools used across engineering teams.

- name: ~/winget
  description: "Install GitHub Desktop for visual Git management"
  parameters:
    package: "GitHub.GitHubDesktop"

Purpose: Installs GitHub Desktop for GUI-based Git operations.

- name: ~/winget
  description: "Install Visual Studio Code for web development"
  parameters:
    package: "Microsoft.VisualStudioCode"

Purpose: Installs VS Code, the primary IDE for frontend development.

- name: ~/git-clone
  description: "Clone the Identity Provider repository to the local workspace"
  parameters:
    repositoryUrl: https://github.com/Evilazaro/IdentityProvider.git
    directory: Z:\Workspaces

Purpose: Pre-clones the project repository for immediate access.

User-Specific Tasks (`userTasks`)

Tasks that can be customized or run by individual developers.

Optional Frontend Tools

- name: ~/winget
  description: "Install additional frontend-specific tools"
  parameters:
    downloadUrl: "https://raw.githubusercontent.com/Evilazaro/DevExp-DevBox/refs/heads/main/.configuration/devcenter/workloads/common-frontend-usertasks-config.dsc.yaml"
    configurationFile: "c:\\winget\\common-frontend-usertasks-config.dsc.yaml"

Purpose: Allows engineers to install specialized frontend tools as needed.

Environment Maintenance

- name: ~/powershell
  description: "Update Winget Packages"
  parameters:
    command: |
      # Updates all packages, Node.js, npm, and frontend CLIs; restores .NET dependencies

Purpose: Keeps all tools and dependencies up to date, ensuring security and compatibility.

Project Setup

- name: ~/powershell
  description: "Build Identity Provider Frontend Components"
  parameters:
    command: |
      # Installs dependencies, builds the frontend, and runs unit tests

Purpose: Validates that the environment is ready for development by building and testing the frontend.

3. Examples and Use Cases

Example: New Engineer Onboarding

Scenario: A new frontend engineer joins the Identity Provider project.

Action: The engineer provisions a Dev Box using this image definition.
Result: The Dev Box is automatically configured with all required tools (VS Code, GitHub Desktop), project code is cloned, and the environment is validated by building and testing the frontend—all with minimal manual setup.

Example: Keeping Environments Consistent

Scenario: The engineering team wants to ensure all members use the same versions of tools and dependencies.

Action: Updates are made to the shared configuration files referenced in the YAML.
Result: All new Dev Boxes and environment refreshes use the updated configurations, reducing “works on my machine” issues.

Best Practices

Use Microsoft Base Images: Always start from official Microsoft images for security, support, and compatibility.
Automate Environment Setup: Use PowerShell DSC and WinGet to automate tool installation and configuration, ensuring repeatability.
Centralize Common Configurations: Reference shared configuration files for tools to maintain consistency across teams.
Separate Mandatory and Optional Tasks: Use userTasks for tools that are not required by everyone, keeping the base image lean.
Keep Everything Updated: Include maintenance scripts to regularly update packages and dependencies.
Validate Setup: Automate build and test steps to ensure the environment is ready for development immediately after provisioning.
Follow Security Best Practices: Use scoped execution policy changes and trusted repositories to minimize security risks.
Document Each Step: Comment each section and task for clarity and maintainability.

References

3 -

4 -

Overview

This document provides comprehensive documentation for the PowerShell Desired State Configuration (DSC) YAML file: common-config.dsc.yaml. This configuration is designed to automate the setup of a standardized development environment for .NET engineers, with a strong focus on Azure development workflows. It provisions essential tools, runtimes, and storage optimizations to ensure a productive and performant developer experience on Windows 10/11.

Storage Configuration

Dev Drive

YAML Configuration:

- resource: Disk
  id: DevDrive1
  directives:
    module: StorageDsc
    allowPrerelease: true
    description: Configure Dev Drive with ReFS format
  settings:
    DiskId: "0" # First available disk (verify this matches your environment)
    DiskIdType: "Number"
    DriveLetter: "Z" # Standard letter for development drives
    FSLabel: "Dev Drive 1"
    DevDrive: true # Enables Windows Dev Drive optimizations
    AllowDestructive: true # Warning: Will format existing disk if present
    FSFormat: "ReFS" # Required for Dev Drive functionality
    Size: "50Gb" # Recommended minimum size for development workloads

Explanation:
Configures a Windows Dev Drive using the ReFS file system, optimized for development workloads. Dev Drive provides improved performance for source control operations, build processes, and large solution files—especially beneficial for Azure microservice architectures. The configuration ensures the drive is formatted and mounted as Z:, with Dev Drive optimizations enabled.

Official Documentation:

Source Control Tools

Git

YAML Configuration:

- resource: Microsoft.WinGet.DSC/WinGetPackage
  id: Git.Git
  directives:
    allowPrerelease: true
    description: Install Git version control system
  settings:
    id: Git.Git

Explanation:
Installs Git, the essential distributed version control system for source code management. Git is foundational for Azure DevOps, GitHub integration, and infrastructure-as-code workflows. It is also required for Azure Bicep, GitOps, and optimized for performance when used with Dev Drive.

Official Documentation:

GitHub CLI

YAML Configuration:

- resource: Microsoft.WinGet.DSC/WinGetPackage
  id: GitHub.cli
  directives:
    allowPrerelease: true
    description: Install GitHub command-line interface
  settings:
    id: GitHub.cli
  dependsOn:
    - Git.Git # Requires Git for full functionality

Explanation:
Installs the GitHub CLI (gh), enabling command-line management of GitHub repositories, issues, pull requests, and GitHub Actions. This tool streamlines Azure DevOps integration and automates workflows for Azure deployments. It depends on Git for core functionality.

Official Documentation:

Development Runtimes

.NET SDK 9

YAML Configuration:

- resource: Microsoft.WinGet.DSC/WinGetPackage
  id: Microsoft.DotNet.SDK.9
  directives:
    allowPrerelease: true
    description: Install .NET 9 SDK for application development
  settings:
    id: Microsoft.DotNet.SDK.9

Explanation:
Installs the .NET 9 SDK, which is central to Azure development. It provides tools for building, testing, and deploying applications targeting Azure services, including Azure Functions, Web Apps, and containerized workloads. The SDK includes Azure-specific templates and middleware.

Official Documentation:

.NET Runtime 9

YAML Configuration:

- resource: Microsoft.WinGet.DSC/WinGetPackage
  id: Microsoft.DotNet.Runtime.9
  directives:
    allowPrerelease: true
    description: Install .NET 9 Runtime
  settings:
    id: Microsoft.DotNet.Runtime.9
  dependsOn:
    - Microsoft.DotNet.SDK.9 # Runtime is included in SDK, but explicit dependency ensures correct order

Explanation:
Installs the .NET 9 Runtime, required for running .NET applications and Azure tooling. This ensures compatibility with Azure PowerShell, Azure Functions Core Tools, and local emulators. Explicit installation guarantees availability for tools that require the runtime directly.

Official Documentation:

Node.js

YAML Configuration:

- resource: Microsoft.WinGet.DSC/WinGetPackage
  id: OpenJS.NodeJS
  directives:
    allowPrerelease: true
    description: Install Node.js JavaScript runtime
  settings:
    id: OpenJS.NodeJS

Explanation:
Installs Node.js, a JavaScript runtime essential for modern web development and many Azure scenarios. Node.js is required for Azure Static Web Apps, Azure Functions (JavaScript/TypeScript), and npm-based Azure SDKs. It also supports local development and testing of Azure App Service Node.js apps.

Official Documentation:

Development Tools

Visual Studio Code

YAML Configuration:

- resource: Microsoft.WinGet.DSC/WinGetPackage
  id: Microsoft.VisualStudioCode
  directives:
    allowPrerelease: true
    description: Install Visual Studio Code editor
  settings:
    id: Microsoft.VisualStudioCode

Explanation:
Installs Visual Studio Code (VS Code), Microsoft’s recommended editor for Azure development. VS Code offers deep integration with Azure services through extensions, supports ARM/Bicep authoring, and provides tools for local Azure Functions and App Service development.

Official Documentation:

Best Practices

Use Descriptive Comments: Each component in the YAML is well-commented, explaining its purpose and relevance to Azure development.
Explicit Dependencies: Where necessary, dependsOn is used to ensure correct installation order (e.g., GitHub CLI depends on Git).
Secure Installations: All tools are installed via WinGet, ensuring verified and secure sources.
Optimized Storage: Dev Drive is configured for maximum performance, especially for large Azure repositories and build workloads.
Modular Configuration: Each tool or runtime is defined as a separate resource, making the configuration easy to maintain and extend.
Documentation Links: Official documentation is provided for each component, enabling quick access to further information.
YAML Formatting: Use of consistent indentation and structure for readability and maintainability.

For further customization, consider adding Azure CLI, Azure Functions Core Tools, and specific VS Code extensions in separate configuration files to tailor the environment for specialized Azure scenarios.

5 -

Overview

The common-frontend-usertasks-config.dsc.yaml file is a PowerShell Desired State Configuration (DSC) YAML file designed to automate the setup of a comprehensive Azure frontend development environment for .NET engineers. This configuration ensures that essential tools, SDKs, and Visual Studio Code extensions are installed and kept up to date, providing a consistent and productive environment for frontend development targeting Azure services. The configuration leverages best practices for cross-platform development, automation, and security.

Component Details

Postman API Platform

YAML Configuration

- resource: Microsoft.WinGet.DSC/WinGetPackage
  id: Postman.Postman
  directives:
    description: Install Postman API platform for designing, testing and documenting APIs
    allowPrerelease: true
  settings:
    id: Postman.Postman

Explanation

This component uses the WinGet DSC resource to install the official Postman application. Postman is a widely used tool for API design, testing, and documentation, making it essential for frontend engineers working with Azure APIs and services. By automating its installation, the configuration ensures all developers have a consistent toolset for API integration and testing.

Purpose: Enables API testing, documentation, and automation for frontend-to-backend integration.
Why WinGet: Ensures installation of the official, verified package directly from the Microsoft package repository.

Official Documentation Link

.NET Workload Update

YAML Configuration

- resource: PSDscResources/Script
  id: Dotnet.WorkloadUpdate
  directives:
    description: Update all installed .NET workloads
    securityContext: elevated # Requires admin rights to update .NET workloads
  settings:
    SetScript: |
      try {
          # Set execution policy for current process
          Set-ExecutionPolicy Bypass -Scope Process -Force -ErrorAction SilentlyContinue            
          
          # Ensure path is properly set
          $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
          
          # Check if dotnet command exists before attempting updates
          if (Get-Command dotnet -ErrorAction SilentlyContinue) {
              Write-Verbose "Updating .NET workloads - this may take several minutes..." -Verbose
              
              # Update all workloads and ignore failures from sources that might be temporarily unavailable
              dotnet workload update --ignore-failed-sources
              
              Write-Verbose ".NET workloads updated successfully" -Verbose
          } else {
              Write-Warning "dotnet command not found. .NET SDK may not be installed."
          }
      } catch {
          Write-Error "Failed to update .NET workloads: $_"
      }      
    GetScript: return $false
    TestScript: return $false

Explanation

This component uses the Script resource from PSDscResources to ensure all installed .NET workloads are updated to the latest versions. This is critical for maintaining compatibility with Azure services, security, and accessing the latest features for frontend development (e.g., Blazor, MAUI, ASP.NET Core, Azure Static Web Apps tools).

Purpose: Keeps .NET workloads current, reducing compatibility issues and security risks.
Automation: Uses PowerShell scripting to automate updates, following Azure automation best practices for non-interactive execution.

Official Documentation Link

Visual Studio Code Extensions

YAML Configuration

- resource: PSDscResources/Script
  id: Microsoft.VisualStudioCode.Extensions
  directives:
    description: Install VS Code Extensions for Azure frontend development
    securityContext: elevated # Requires admin rights to install extensions for all users
    allowPrerelease: true # Allow prerelease versions when needed for latest features
  settings:
    SetScript: |
      try {
          # Set execution policy to bypass for automation
          Set-ExecutionPolicy Bypass -Scope Process -Force
          
          # Ensure VS Code CLI is in PATH
          $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
          
          Write-Verbose "Installing VS Code extensions for Azure frontend development..." -Verbose
          
          # PowerShell extension for Azure automation scripts and DevOps
          code --install-extension ms-vscode.powershell
          
          # WSL integration for cross-platform development targeting Linux environments
          code --install-extension ms-vscode-remote.remote-wsl
          
          # C# extension for backend integration and full-stack development
          code --install-extension ms-dotnettools.csdevkit
          
          # TypeScript with latest features for modern web development
          code --install-extension ms-vscode.vscode-typescript-next
          
          # YAML support for deployment configurations and GitHub Actions
          code --install-extension redhat.vscode-yaml
          
          # Bicep for Azure infrastructure as code deployments
          code --install-extension ms-azuretools.vscode-bicep
          
          # Azure Tools pack for comprehensive Azure service integration
          code --install-extension ms-vscode.vscode-node-azure-pack
          
          # Azure CLI tools for command-line Azure management
          code --install-extension ms-vscode.azurecli
          
          # GitHub integration for repository management
          code --install-extension GitHub.remotehub
          
          # GitHub Pull Request integration for code reviews
          code --install-extension GitHub.vscode-pull-request-github

          # Postman extension for API testing and documentation
          code --install-extension Postman.postman-for-vscode
          
          Write-Verbose "VS Code extensions installed successfully" -Verbose
      } catch {
          Write-Error "Failed to install VS Code extensions: $_"
      }      
    GetScript: return $false
    TestScript: return $false

Explanation

This component installs a curated set of Visual Studio Code extensions essential for Azure frontend development. The extensions cover PowerShell scripting, WSL integration, C#, TypeScript, YAML, Bicep (Azure IaC), Azure CLI, and GitHub integration, ensuring developers have all the tools needed for modern, cloud-focused workflows.

Purpose: Standardizes the development environment, boosts productivity, and ensures seamless integration with Azure services and DevOps practices.
Automation: Uses the VS Code CLI to install extensions, ensuring repeatability and consistency across developer machines.

Official Documentation Link

Best Practices

Automation: Use DSC and scripting to automate environment setup, reducing manual errors and onboarding time.
Idempotency: Although some scripts are not fully idempotent, they are structured for easy extension to check and enforce desired state.
Security: Run installation scripts with the minimum required privileges and use official sources for all tools.
Cross-Platform: Support both Windows and WSL2 for a flexible, modern development experience.
Documentation: Comment each section and provide links to official documentation for further reference.
Consistency: Standardize toolsets and extensions to ensure all developers have a uniform environment.

Dev Box Image Definitions Samples

1 - Back-End Engineering Development

Overview

Configurations

Metadata

Tasks

Core Environment Setup

Common Development Tools

Backend Development Environment

User Tasks

Environment Maintenance

Project Setup

Examples and Use Cases

Example: Provisioning a Dev Box for a New Engineer

Use Case: Ensuring Consistency Across Teams

Best Practices

2 - Front-End Engineering Development

Overview

Configurations

Metadata & Schema

Tasks

Core Environment Setup

Common Development Tools

User-Specific Tasks (userTasks)

Optional Frontend Tools

Environment Maintenance

Project Setup

3. Examples and Use Cases

Example: New Engineer Onboarding

Example: Keeping Environments Consistent

Best Practices

3 -

4 -

Overview

Table of Contents

Storage Configuration

Dev Drive

Source Control Tools

Git

GitHub CLI

Development Runtimes

.NET SDK 9

.NET Runtime 9

Node.js

Development Tools

Visual Studio Code

Best Practices

5 -

Overview

Table of Contents

Component Details

Postman API Platform

YAML Configuration

Explanation

Official Documentation Link

.NET Workload Update

YAML Configuration

Explanation

Official Documentation Link

Visual Studio Code Extensions

YAML Configuration

Explanation

Official Documentation Link

Best Practices

References

User-Specific Tasks (`userTasks`)