office hours discussion new api changes 2025 03 01 preview

specification/devcenter/DevCenter/DevBox/models.tsp

@@ -326,6 +326,10 @@ union DevBoxActionType {
   @doc("The action will stop the Dev Box.")
   Stop: "Stop",
 
+  @doc("The action will delete the Dev Box.")
+  @added(APIVersions.v2025_03_01_preview)
+  Delete: "Delete",
+
   string,
 }
 
@@ -338,6 +342,10 @@ union DevBoxActionSourceType {
   @doc("The action was triggered by a Dev Box schedule.")
   Schedule: "Schedule",
 
+  @doc("The action was triggered by a Dev Box admin.")
+  @added(APIVersions.v2025_03_01_preview)
+  Admin: "Admin",
+
   string,
 }
 
@@ -1048,3 +1056,83 @@ model DevBoxSnapshot {
   @added(APIVersions.v2024_10_01_preview)
   snapshotType: SnapshotType;
 }
+
+@added(APIVersions.v2025_03_01_preview)
+@doc("A Dev Box addon.")
+@resource("addons")
+@parentResource(DevBox)
+@discriminator("type")
+model DevBoxAddOn {
+  @key("devBoxAddOnName")
+  @doc("Name of the dev box addon.")
+  @minLength(3)
+  @maxLength(63)
+  @pattern("^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$")
+  @visibility("read", "create")
+  name: string;
+
+  @doc("The type of the Dev Box addon.")
+  @visibility("read")
+  type: DevBoxAddOnType;
+
+  @doc("Whether the Dev Box addon is enabled or not.")
+  enabled: boolean;
+
+  @doc("""
+    The current action state of the Dev Box addon. This state is based on previous
+    action performed by user.
+    """)
+  @visibility("read")
+  actionState?: string;
+}
+
+@added(APIVersions.v2025_03_01_preview)
+@doc("The types of Dev Box addon.")
+union DevBoxAddOnType {
+  @doc("The Dev Box Tunnel addon.")
+  DevBoxTunnel: "DevBoxTunnel",
+
+  string,
+}
+
+@added(APIVersions.v2025_03_01_preview)
+@doc("The Dev Box Tunnel addon.")
+model DevBoxTunnel extends DevBoxAddOn {
+  @doc("The type of the Dev Box addon.")
+  type: DevBoxAddOnType.DevBoxTunnel;
+
+  @doc("The tunnel status.")
+  @visibility("read")
+  status: DevBoxTunnelStatus;
+
+  @doc("The backing dev tunnel's id.")
+  @visibility("read")
+  devTunnelId: string;
+
+  @doc("The backing dev tunnel cluster id.")
+  @visibility("read")
+  clusterId: string;
+
+  @doc("The code tunnel name.")
+  @visibility("read")
+  codeTunnelName: string;
+
+  @doc("The code tunnel's url.")
+  @visibility("read")
+  codeTunnelUrl: string;
+}
+
+@added(APIVersions.v2025_03_01_preview)
+@doc("The detailed status of Dev Box Tunnel addon.")
+union DevBoxTunnelStatus {
+  @doc("The tunnel is active and can be connected.")
+  Enabled: "Enabled",
+
+  @doc("The tunnel is inactive and can't be connected.")
+  Disabled: "Disabled",
+
+  @doc("The tunnel is suspended due to hibernation or other reasons.")
+  Suspended: "Suspended",
+
+  string,
+}

specification/devcenter/DevCenter/DevBox/parameters.tsp

@@ -39,3 +39,22 @@ model DevBoxNameParameter {
   @path
   devBoxName: string;
 }
+
+@doc("The scheduled delete datetime query parameter.")
+@added(APIVersions.v2025_03_01_preview)
+model DeleteAtQueryParameter {
+  @doc("The scheduled deletion time of the Dev Box, in RFC3339 format.")
+  @query("deleteAt")
+  deleteAt: utcDateTime;
+}
+
+@added(APIVersions.v2025_03_01_preview)
+@doc("The Dev Box addon name path parameter.")
+model DevBoxAddOnNameParameter {
+  @doc("The name of the Dev Box addon.")
+  @maxLength(63)
+  @minLength(3)
+  @pattern("^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$")
+  @path
+  devBoxAddOnName: string;
+}

specification/devcenter/DevCenter/DevBox/routes.tsp

@@ -452,4 +452,108 @@ interface DevBoxes {
     {},
     OperationStatus
   >;
+
+  @doc("Creates an action to schedule the deletion of a Dev Box")
+  @added(APIVersions.v2025_03_01_preview)
+  @action("scheduledDelete")
+  scheduledDeleteAction is StandardResourceOperations.ResourceAction<
+    DevBox,
+    {
+      ...DeleteAtQueryParameter;
+    },
+    DevBoxAction
+  >;
+
+  @doc("Lists addons for this Dev Box.")
+  @added(APIVersions.v2025_03_01_preview)
+  listDevBoxAddons is StandardResourceOperations.ResourceList<DevBoxAddOn>;
+
+  @doc("Gets a Dev Box addon by Dev Box addon id.")
+  @added(APIVersions.v2025_03_01_preview)
+  getDevBoxAddons is StandardResourceOperations.ResourceRead<DevBoxAddOn>;
+
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "Standard operations produce wrong swagger"
+  @added(APIVersions.v2025_03_01_preview)
+  @doc("Creates a Dev Box addon.")
+  @finalOperation(DevBoxes.getDevBoxAddons)
+  @pollingOperation(OperationStatuses.get)
+  @route("/projects/{projectName}/users/{userId}/devboxes/{devBoxName}/addons/{devBoxAddOnName}")
+  @put
+  createDevBoxAddOn is Azure.Core.Foundations.Operation<
+    {
+      ...ProjectNameParameter;
+      ...UserIdParameter;
+      ...DevBoxNameParameter;
+      ...DevBoxAddOnNameParameter;
+
+      @doc("Represents the body request of a Dev Box addon creation.")
+      @bodyRoot
+      body: DevBoxAddOn;
+    },
+    DevBoxAddOn | {
+      @statusCode statusCode: 201;
+
+      @header("Location")
+      location: string;
+
+      @pollingLocation
+      @header("Operation-Location")
+      operationLocation: string;
+
+      @added(APIVersions.v2025_03_01_preview)
+      @bodyRoot
+      body?: DevBoxAddOn;
+    }
+  >;
+
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "Standard operations produce wrong swagger"
+  @added(APIVersions.v2025_03_01_preview)
+  @doc("Deletes a Dev Box addon.")
+  @pollingOperation(OperationStatuses.get)
+  @route("/projects/{projectName}/users/{userId}/devboxes/{devBoxName}/addons/{devBoxAddOnName}")
+  @delete
+  deleteDevBoxAddOn is Azure.Core.Foundations.Operation<
+    {
+      ...ProjectNameParameter;
+      ...UserIdParameter;
+      ...DevBoxNameParameter;
+      ...DevBoxAddOnNameParameter;
+    },
+    {
+      @statusCode statusCode: 202;
+
+      @header("Location")
+      location: string;
+
+      @pollingLocation
+      @header("Operation-Location")
+      operationLocation: string;
+
+      @bodyRoot body: OperationStatus;
+    } | {
+      @statusCode statusCode: 204;
+    }
+  >;
+
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "Standard operations produce wrong swagger"
+  @added(APIVersions.v2025_03_01_preview)
+  @doc("Enable a Dev Box addon.")
+  @pollingOperation(OperationStatuses.get)
+  @action("enable")
+  enableDevBoxAddOn is DevCenterOps.LongRunningResourceAction<
+    DevBoxAddOn,
+    {},
+    OperationStatus
+  >;
+
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "Standard operations produce wrong swagger"
+  @added(APIVersions.v2025_03_01_preview)
+  @doc("Disable a Dev Box addon.")
+  @pollingOperation(OperationStatuses.get)
+  @action("disable")
+  disableDevBoxAddOn is DevCenterOps.LongRunningResourceAction<
+    DevBoxAddOn,
+    {},
+    OperationStatus
+  >;
 }

specification/devcenter/DevCenter/examples/2025-03-01-preview/DevBoxes_CaptureSnapshot.json

@@ -0,0 +1,25 @@
+{
+  "title": "Attempts to capture the manual snapshot for the Dev Box.",
+  "operationId": "DevBoxes_CaptureSnapshot",
+  "parameters": {
+    "api-version": "2025-03-01-preview",
+    "endpoint": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com",
+    "projectName": "myProject",
+    "userId": "me",
+    "devBoxName": "MyDevBox"
+  },
+  "responses": {
+    "202": {
+      "headers": {
+        "Location": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/operationstatuses/786a823c-8037-48ab-89b8-8599901e67d0",
+        "Operation-Location": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/operationstatuses/786a823c-8037-48ab-89b8-8599901e67d0"
+      },
+      "body": {
+        "id": "/projects/myProject/operationstatuses/786a823c-8037-48ab-89b8-8599901e67d0",
+        "name": "786a823c-8037-48ab-89b8-8599901e67d0",
+        "status": "Running",
+        "startTime": "2023-02-01T12:43:54.122Z"
+      }
+    }
+  }
+}

specification/devcenter/DevCenter/examples/2025-03-01-preview/DevBoxes_CreateCustomizationGroup.json

@@ -0,0 +1,57 @@
+{
+  "title": "Applies customizations to the Dev Box.",
+  "operationId": "DevBoxes_CreateCustomizationGroup",
+  "parameters": {
+    "api-version": "2025-03-01-preview",
+    "endpoint": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/",
+    "projectName": "myProject",
+    "userId": "me",
+    "devBoxName": "MyDevBox",
+    "customizationGroupName": "Provisioning",
+    "body": {
+      "tasks": [
+        {
+          "name": "catalogName/choco",
+          "displayName": "Install VS Code",
+          "parameters": {
+            "packageName": "vscode",
+            "packageVersion": "1.0.0"
+          }
+        },
+        {
+          "name": "catalogName/write-to-file",
+          "runAs": "User"
+        }
+      ]
+    }
+  },
+  "responses": {
+    "200": {
+      "body": {
+        "name": "Provisioning",
+        "uri": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/users/b08e39b4-2ac6-4465-a35e-48322efb0f98/devboxes/MyDevBox/customizationgroups/Provisioning",
+        "tasks": [
+          {
+            "id": "a9202018-fb6a-4007-8b52-26d7c6d1c1fb",
+            "name": "catalogName/choco",
+            "displayName": "Install VS Code",
+            "status": "NotStarted",
+            "parameters": {
+              "packageName": "vscode",
+              "packageVersion": "1.0.0"
+            },
+            "logUri": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/users/b08e39b4-2ac6-4465-a35e-48322efb0f98/devboxes/MyDevBox/customizationgroups/Provisioning/logs/a9202018-fb6a-4007-8b52-26d7c6d1c1fb"
+          },
+          {
+            "id": "91835dc0-ef5a-4f58-9e3a-099aea8481f4",
+            "name": "catalogName/write-to-file",
+            "runAs": "User",
+            "status": "NotStarted",
+            "logUri": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/users/b08e39b4-2ac6-4465-a35e-48322efb0f98/devboxes/MyDevBox/customizationgroups/Provisioning/logs/91835dc0-ef5a-4f58-9e3a-099aea8481f4"
+          }
+        ],
+        "status": "NotStarted"
+      }
+    }
+  }
+}

specification/devcenter/DevCenter/examples/2025-03-01-preview/DevBoxes_CreateDevBox.json

@@ -0,0 +1,74 @@
+{
+  "title": "Creates or replaces a Dev Box.",
+  "operationId": "DevBoxes_CreateDevBox",
+  "parameters": {
+    "api-version": "2025-03-01-preview",
+    "endpoint": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com",
+    "projectName": "myProject",
+    "userId": "me",
+    "devBoxName": "MyDevBox",
+    "body": {
+      "poolName": "LargeDevWorkStationPool"
+    }
+  },
+  "responses": {
+    "200": {
+      "body": {
+        "uri": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/users/b08e39b4-2ac6-4465-a35e-48322efb0f98/devboxes/MyDevBox",
+        "name": "MyDevBox",
+        "provisioningState": "Succeeded",
+        "projectName": "ContosoProject",
+        "poolName": "LargeDevWorkStationPool",
+        "location": "centralus",
+        "osType": "Windows",
+        "user": "b08e39b4-2ac6-4465-a35e-48322efb0f98",
+        "hardwareProfile": {
+          "vCPUs": 8,
+          "memoryGB": 32
+        },
+        "storageProfile": {
+          "osDisk": {
+            "diskSizeGB": 1024
+          }
+        },
+        "hibernateSupport": "Enabled",
+        "imageReference": {
+          "name": "DevImage",
+          "version": "1.0.0",
+          "publishedDate": "2022-03-01T00:13:23.323Z"
+        }
+      }
+    },
+    "201": {
+      "headers": {
+        "Location": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/operationstatuses/786a823c-8037-48ab-89b8-8599901e67d0",
+        "Operation-Location": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/operationstatuses/786a823c-8037-48ab-89b8-8599901e67d0"
+      },
+      "body": {
+        "uri": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/users/b08e39b4-2ac6-4465-a35e-48322efb0f98/devboxes/MyDevBox",
+        "name": "MyDevBox",
+        "provisioningState": "Creating",
+        "projectName": "ContosoProject",
+        "poolName": "LargeDevWorkStationPool",
+        "location": "centralus",
+        "osType": "Windows",
+        "user": "b08e39b4-2ac6-4465-a35e-48322efb0f98",
+        "hardwareProfile": {
+          "vCPUs": 8,
+          "memoryGB": 32
+        },
+        "storageProfile": {
+          "osDisk": {
+            "diskSizeGB": 1024
+          }
+        },
+        "hibernateSupport": "Enabled",
+        "imageReference": {
+          "name": "DevImage",
+          "version": "1.0.0",
+          "publishedDate": "2022-03-01T00:13:23.323Z"
+        }
+      }
+    }
+  }
+}