Use containers for build and debug with Visual Studio Code

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

If you use Visual Studio Code for application development, you can set up your project so that it builds inside a container. You can then build and debug directly in the container. This topic assumes you have created a project with Visual Studio Code so that the .vscode directory exists and has the two files launch.json and settings.json.

This topic discusses using containers locally; Use GitHub Codespaces for build and debug describes the use of GitHub Codespaces to edit, build, deploy, and debug your Azure Sphere apps.

Set up the .devcontainer folder

In your project's top-level directory, create a folder named .devcontainer. In this folder, create a file named devcontainer.json with the following content:

{
    "name": "Azure Sphere Blink",
    "runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined"],
    "build": {
    "dockerfile": "Dockerfile",
    "target": "dev"
    },

    // Use 'settings' to set *default* container specific settings.json values on container create.
    // You can edit these settings after create using File > Preferences > Settings > Remote.
    "settings": {
            "terminal.integrated.shell.linux": "/bin/bash"
    },

    // Use 'appPort' to create a container with published ports. If the port isn't working, be sure
    // your server accepts connections from all interfaces (0.0.0.0 or '*'), not just localhost.
    // "appPort": [],

    // Uncomment the next line to run commands after the container is created.
    // "postCreateCommand": "gcc -v",

    // Comment out the next line if you want to run as root instead
    "remoteUser": "vscode",

    // Add the IDs of extensions you want installed when the container is created in the array below.
    "extensions": [
    "ms-vscode.cpptools",
    "ms-vscode.azure-sphere-tools",
    "ms-vscode.azure-sphere-tools-ui"
    ]
}

Next, create a file named Dockerfile in the .devcontainer folder with the following contents:

FROM mcr.microsoft.com/azurespheresdk:latest AS dev

FROM dev AS build
COPY ./ /src/
WORKDIR /out
RUN cmake -G "Ninja" -DCMAKE_TOOLCHAIN_FILE="/opt/azurespheresdk/CMakeFiles/AzureSphereToolchain.cmake" \
    -DAZURE_SPHERE_TARGET_API_SET="latest-lts" -DCMAKE_BUILD_TYPE="Release" "/src"
ENTRYPOINT [ "ninja" ]

The initial FROM line specifies the standard Azure Sphere Docker image as the base development container, and the second says to use that base container as the build environment. The COPY line copies the contents of the repository into the container's /src/ directory. The WORKDIR specifies the build directory. The RUN command provides the CMake command to generate the build files. Finally, the ENTRYPOINT specifies that ninja should be invoked to actually build the application.

Build and debug the project

Open the project folder in Visual Studio Code. Visual Studio Code detects the new files and opens a message box saying "Folder contains a Dev Container configuration file. Reopen to folder to develop in a container." Select the Reopen in Container button to reopen the folder in the container created by the .devcontainer/Dockerfile file. The title bar in Visual Studio Code changes to show that you are editing in a container. If you open the Extensions tab in the left nav bar, you see both the extensions installed locally and those installed in the container.

Press F5 to build your project and begin debugging. Your application builds and sideloads to your device as usual. If you have set a breakpoint in your code, the app runs until the breakpoint is reached. You can use the usual debugging commands to walk through your code. See the Debugging topic in the Visual Studio Code documentation for more details.

When you are finished debugging, press Shift+F5 or the Stop icon. To close the container, use the Close Remote Connection command from the Remote menu on the Visual Studio Code toolbar.