MDB - customization image definition updates - it2

Author: RoseHJM

articles/dev-box/how-to-write-image-definition-file.md

@@ -83,9 +83,9 @@ To enable the use of project-level catalogs at the dev center level:
 For more information about adding catalogs to projects, see [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
 
 ## Create an image definition file
-You can create and test image definition files by using VS Code.  In addition to using the built-in tasks, you can use the Microsoft Dev Box extension in VS Code to discover the custom tasks available through your dev center.
+You can create and test image definition files by using VS Code. In addition to using the built-in tasks, you can use the Microsoft Dev Box extension in VS Code to discover the custom tasks available through your dev center.
 
-For detailed information about using cutom tasks, see the [schema reference](../reference-dev-box-customizations.md).
+For detailed information about using custom tasks, see the [Customizations schema reference](../reference-dev-box-customizations.md).
 
 1. Create a dev box (or use an existing dev box) for testing.
 1. On the test dev box, install VS Code and then install the Dev Box extension.
@@ -100,12 +100,21 @@ For detailed information about using cutom tasks, see the [schema reference](../
 
 1. The image definition file runs and applies the specified tasks to your test dev box. Inspect the changes and check the VS Code terminal for any errors or warnings generated during the task execution.
 1. When the image definition file runs successfully, upload it to your catalog.
+ 
+### System Tasks and User Tasks 
+
+All tasks in the userTasks section run as the user after the user's first sign-in to the Dev Box. Tasks in the tasks section run as LocalSystem during the Dev Box provisioning stage. Both sections share the same parameters based on the task definitions in your catalog.
+
+### When should I use Run-as-user Tasks? 
+
+Use run-as-user tasks to install software and packages under user context. For example, users often prefer to install Python and Visual Studio Code under user context instead of system-wide. Put WinGet tasks in the userTasks section for better results when they don't work under tasks. 
 
-## Optional: Customize your dev box by using existing WinGet Configuration files
-WinGet configuration uses a config-as-code approach to define the software and settings needed to prepare your Windows environment for coding.
+## Optional: Customize your dev box by using existing Desired State Configuration files
+Desired State Configuration (DSC) is a management platform in PowerShell that enables you to manage your development environment with configuration as code. You can use DSC to define the desired state of your dev box, including software installations, configurations, and settings.
 
-You can also use these configuration files to set up a dev box, by using a WinGet task included in the Microsoft-provided quickstart catalog.
-The following example shows a dev box image definition file that calls an existing WinGet Desired State Configuration (DSC) file:
+You can also use DSC configuration files to set up a dev box, by using a built-in WinGet task.
+
+The following example shows a dev box image definition file that calls an existing WinGet DSC file:
 
 ```yaml
 tasks:
@@ -116,9 +125,71 @@ tasks:
 
 To learn more, see [WinGet configuration](https://aka.ms/winget-configuration).
 
+## Configure catalog sync settings for the project
+
+Configure your project to sync image definitions from the catalog. With this setting, you can use the image definitions in the catalog to create dev box pools.
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+1. In the search box, enter **projects**. In the list of results, select **Projects**.
+1. Open the Dev Box project for which you want to configure catalog sync settings.
+1. Select **Catalogs**.
+1. Select **Sync settings**.
+
+   :::image type="content" source="./media/how-to-write-image-definition-file/customizations-project-sync-settings-small.png" alt-text="Screenshot of the Catalogs pane in the Azure portal, with the button for sync settings highlighted." lightbox="./media/how-to-write-image-definition-file/customizations-project-sync-settings.png":::
+
+1. On the **Sync settings** pane, select **Image definitions**, and then select **Save**.
+
+   :::image type="content" source="./media/how-to-write-image-definition-file/customizations-project-sync-image-definitions.png" alt-text="Screenshot of the pane for sync settings in the Azure portal, with the checkbox for image definitions highlighted." lightbox="./media/how-to-write-image-definition-file/customizations-project-sync-image-definitions.png":::
+
+## Attach a catalog that contains the definition file
+
+Before you can use a customization file as an image definition, you must attach a catalog that contains the definition file to your dev center or project. The catalog can be from GitHub or Azure Repos.
+
+The **Image definitions** pane lists the image definitions that your project can access.
+
+:::image type="content" source="media/how-to-write-image-definition-file/team-customizations-image-definitions-small.png" alt-text="Screenshot of the Azure portal pane that lists accessible image definitions for a project." lightbox="media/how-to-write-image-definition-file/team-customizations-image-definitions.png":::
+
+For more information about attaching catalogs, see [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
+
+## Configure a dev box pool to use an image definition
+
+Make customizations available to your development teams by configuring a dev box pool to use a customization file (imagedefinition.yaml). Store the customization file in a repository linked to a catalog in your dev center or project. Specify this file as the image definition for the pool, and the customizations are applied to new dev boxes.
+
+The following steps show you how to create a dev box pool and specify an image definition:
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+1. In the search box, enter **projects**. In the list of results, select **Projects**.
+1. Open the Dev Box project with which you want to associate the new dev box pool.
+1. Select **Dev box pools**, and then select **Create**.
+1. On the **Create a dev box pool** pane, enter the following values:
+
+   | Setting | Value |
+   |---|---|
+   | **Name** |Enter a name for the pool. The pool name is visible to developers to select when they're creating dev boxes. It must be unique within a project. |
+   | **Definition** | This box lists image definitions from accessible catalogs and dev box definitions. Select an image definition file. |
+   | **Network connection** | Select **Deploy to a Microsoft hosted network**, or use an existing network connection. |
+   |**Enable single sign-on** | Select **Yes** to enable single sign-on for the dev boxes in this pool. Single sign-on must be configured for the organization. For more information, see [Enable single sign-on for dev boxes](https://aka.ms/dev-box/single-sign-on). |
+   | **Dev box Creator Privileges** | Select **Local Administrator** or **Standard User**. |
+   | **Enable Auto-stop** | **Yes** is the default. Select **No** to disable an autostop schedule. You can configure an autostop schedule after the pool is created. |
+   | **Stop time** | Select a time to shut down all the dev boxes in the pool. |
+   | **Time zone** | Select the time zone that the stop time is in. |
+   | **Licensing** | 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. |
+
+   :::image type="content" source="./media/how-to-write-image-definition-file/pool-specify-image-definition.png" alt-text="Screenshot of the pane for creating a dev box pool." lightbox="./media/how-to-write-image-definition-file/pool-specify-image-definition.png":::
+
+1. Select **Create**.
+1. Verify that the new dev box pool appears in the list. You might need to refresh the screen.
+
+### Create a dev box by using the developer portal
+
+To verify that customizations from the image definition file are applied, create a dev box in the Microsoft Dev Box developer portal. Follow the steps in [Quickstart: Create and connect to a dev box by using the Microsoft Dev Box developer portal](quickstart-create-dev-box.md). Then connect to the newly created dev box and verify that the customizations work as you expected.
+
+You can make adjustments to the customization file and create a new dev box to test the changes. When you're happy that the customizations are correct, you can build a reusable image.
+
+
 ## Next step
 
-Now that you have created an image definition file, upload it to a catalog and attach the catalog to a project. The image definition file will be used to configure and create dev boxes for your development teams.
+Now that you have an image definition file, upload it to a catalog and attach the catalog to a project. The image definition file is used to configure and create dev boxes for your development teams.
 
 > [!div class="nextstepaction"]
 > [Configure imaging for Dev Box team customizations](how-to-configure-customization-imaging.md)