devcenter microsoft.dev center 2024 05 01 preview (#27863)

* Adds base for updating Microsoft.DevCenter from version preview/2023-10-01-preview to version 2024-05-01-preview

* Updates readme

* Updates API version in new specs and examples

* add new changes for 2024-05-01-preview

* run prettier and fix

* Add directive to supress HostParametersValidation lintdiff errors

* fix  ntegerTypeMustHaveFormat lintdiff error

* add suppression for OperationIdNounVerb

* Add new API changes in TypeSpec

* Generate the swagger from TypeSpec

* fix tag name

* Fix package tag for real

* Add missing examples to TypeSpec folder

* Recompile

* Few more fixes

* Some more fixes

* Fix validateCustomizationTasksAction route to be LRO

* Fix issues with examples. Remove a couple of old ones. Add two missing ones

* Run linter

* Validate Customization group route changes

* Fix another example with accept header/param

* Update visbility since the name can be used in post actions

* Needs to be CREATE visibility per documentation

* Rename timeout to timeoutInSeconds

* Merge latest with main, fix package-lock issue, run npx tsv devcenter

* Update comment as per PR suggestions

* Change route

* Remove regionality from supporting documents link, use Azure.Core.Foundations.Error object instead of our own

* Configure param with query parameter traits

* Add a missing space

* Fix header, should actually be in response

* Fix warnings due to missing doc descriptions

* Run linter

* use dayton's wording for tasks include parameter

* Remove unncessary statusCode in response object

* Remove unnecessary @action decorator since the action name is already included in the route

---------

Co-authored-by: Sneha Nagendra <[email protected]>
Co-authored-by: Arber Hila <[email protected]>
Co-authored-by: Arber Hila <[email protected]>

Author: 4 people

specification/devcenter/DevCenter/DevBox/models.tsp

@@ -187,6 +187,78 @@ union ScheduledFrequency {
   string,
 }
 
+@doc("Type of the parameter.")
+@added(APIVersions.v2024_05_01_preview)
+union CustomizationTaskDefinitionParameterType {
+  @doc("The parameter accepts a string value.")
+  string: "string",
+
+  @doc("The parameter accepts a number value.")
+  number: "number",
+
+  @doc("The parameter accepts a boolean value.")
+  boolean: "boolean",
+
+  string,
+}
+
+@doc("What account to run the task as.")
+@added(APIVersions.v2024_05_01_preview)
+union CustomizationTaskExecutionAccount {
+  @doc("The SYSTEM account.")
+  System: "System",
+
+  @doc("The account of the signed in user.")
+  User: "User",
+
+  string,
+}
+
+@doc("Status of a customization task.")
+@added(APIVersions.v2024_05_01_preview)
+union CustomizationTaskStatus {
+  @doc("The task has not yet started.")
+  NotStarted: "NotStarted",
+
+  @doc("The task is currently executing.")
+  Running: "Running",
+
+  @doc("The task successfully executed.")
+  Succeeded: "Succeeded",
+
+  @doc("The task reference is not valid.")
+  FailedValidation: "FailedValidation",
+
+  @doc("he task was skipped.")
+  Skipped: "Skipped",
+
+  @doc("The task timed out.")
+  TimedOut: "TimedOut",
+
+  @doc("The task failed to execute.")
+  Failed: "Failed",
+
+  @doc("The task is awaiting the User Account Control (UAC) prompt to be approved. (See more at: https://learn.microsoft.com/windows/security/application-security/application-control/user-account-control/)")
+  WaitingForUserInputUac: "WaitingForUserInputUac",
+
+  @doc("The task is awaiting the user to connect to the Dev Box to execute.")
+  WaitingForUserSession: "WaitingForUserSession",
+
+  string,
+}
+
+@doc("Status of validating a list of customization tasks.")
+@added(APIVersions.v2024_05_01_preview)
+union CustomizationTaskListValidationStatus {
+  @doc("Validation succeeded.")
+  Succeeded: "Succeeded",
+
+  @doc("Validation failed.")
+  Failed: "Failed",
+
+  string,
+}
+
 @doc("The power states of a Dev Box.")
 union PowerState {
   @doc("The Dev Box power state is not known.")
@@ -207,6 +279,36 @@ union PowerState {
   string,
 }
 
+@doc("Status of validating a list of customization tasks.")
+@added(APIVersions.v2024_05_01_preview)
+union ListCustomizationGroupsIncludeProperty {
+  @doc("Include list of tasks in the response.")
+  tasks: "tasks",
+
+  string,
+}
+
+@doc("Status of a customization group.")
+@added(APIVersions.v2024_05_01_preview)
+union CustomizationGroupStatus {
+  @doc("The customization group has not yet started.")
+  NotStarted: "NotStarted",
+
+  @doc("The customization group is currently executing.")
+  Running: "Running",
+
+  @doc("All tasks in the customization group successfully executed.")
+  Succeeded: "Succeeded",
+
+  @doc("At least one task in the customization group failed.")
+  Failed: "Failed",
+
+  @doc("At least one task in the customization group failed validation.")
+  ValidationFailed: "ValidationFailed",
+
+  string,
+}
+
 @doc("The type of action which will take place on a Dev Box.")
 union DevBoxActionType {
   @doc("The action will stop the Dev Box.")
@@ -537,6 +639,10 @@ model RemoteConnection {
 
   @doc("Link to open a Remote Desktop session.")
   rdpConnectionUrl?: url;
+
+  @added(APIVersions.v2024_05_01_preview)
+  @doc("Link to open a remote desktop session via a dev box's underlying Cloud PC (This will default to Windows App).")
+  cloudPcConnectionUrl?: url;
 }
 
 @doc("An action which will take place on a Dev Box.")
@@ -682,3 +788,168 @@ model DevBoxRepairOperationResult {
   @doc("The result message associated with the repair operation.")
   message?: string;
 }
+
+@doc("The Customization Task list result.")
+model CustomizationTaskDefinitionResult
+  is Azure.Core.Page<CustomizationTaskDefinition>;
+
+@doc("Represents a task to be used in customizing a Dev Box.")
+@added(APIVersions.v2024_05_01_preview)
+@resource("customizationTasks")
+@parentResource(Catalog)
+model CustomizationTaskDefinition {
+  @doc("Full name of the task: {catalogName}/{taskName}.")
+  @key("taskName")
+  @visibility("read")
+  name: string;
+
+  @doc("Name of the catalog that the task belongs to.")
+  @visibility("read")
+  catalogName: string;
+
+  @doc("The unique URI of the customization task.")
+  @visibility("read")
+  uri?: url;
+
+  @doc("Description of the task.")
+  description?: string;
+
+  @doc("Parameters for the task.")
+  parameters?: Record<CustomizationTaskDefinitionParameter>;
+}
+
+@doc("Parameters for a customization task.")
+@added(APIVersions.v2024_05_01_preview)
+model CustomizationTaskDefinitionParameter {
+  @doc("Description of the parameter.")
+  description?: string;
+
+  @doc("Type of the parameter.")
+  type: CustomizationTaskDefinitionParameterType;
+
+  @doc("Whether or not the parameter is required.")
+  @visibility("read")
+  required?: boolean;
+
+  @doc("Default value for the parameter.")
+  default?: string;
+
+  @doc("Allowed values for the parameter.")
+  allowed?: string[];
+}
+
+@doc("Represents a list of tasks to apply to a Dev Box")
+@added(APIVersions.v2024_05_01_preview)
+model CustomizationTaskList {
+  @doc("Tasks to apply.")
+  tasks?: CustomizationTask[];
+}
+
+@doc("A customization task to run on a Dev Box.")
+@resource("customizationTasks")
+@parentResource(Catalog)
+@added(APIVersions.v2024_05_01_preview)
+model CustomizationTask {
+  @doc("Name of the task.")
+  @key("taskName")
+  @visibility("read", "create")
+  name: string;
+
+  @doc("Parameters for the task.")
+  parameters?: Record<string>;
+
+  @doc("Display name to help differentiate multiple instances of the same task.")
+  displayName?: string;
+
+  @doc("Timeout, in seconds. Overrides any timeout provided on the task definition.")
+  timeoutInSeconds?: int32;
+
+  @doc("What account to run the task as.")
+  runAs?: CustomizationTaskExecutionAccount;
+
+  @doc("ID of the task instance.")
+  @visibility("read")
+  id?: string;
+
+  @doc("The unique URI for retrieving the task logs.")
+  @visibility("read")
+  logUri?: string;
+
+  @doc("Status of the task.")
+  @visibility("read")
+  status?: CustomizationTaskStatus;
+
+  @doc("Start time of the task.")
+  @visibility("read")
+  startTime?: utcDateTime;
+
+  @doc("End time of the task.")
+  @visibility("read")
+  endTime?: utcDateTime;
+}
+
+@doc("The operation result of validating a list of customization tasks.")
+@added(APIVersions.v2024_05_01_preview)
+model CustomizationTaskListValidationOperationResult {
+  ...OperationStatus;
+
+  @doc("Outcome of validation.")
+  result?: CustomizationTaskListValidationResult;
+}
+
+@doc("The result of validating a list of customization tasks.")
+@added(APIVersions.v2024_05_01_preview)
+model CustomizationTaskListValidationResult {
+  @doc("Outcome of validation.")
+  validationResult: CustomizationTaskListValidationStatus;
+
+  @doc("List of validation errors. Absent if no errors.")
+  errors?: CustomizationTaskListValidationError[];
+}
+
+@doc("All of the validation errors for a customization task.")
+@added(APIVersions.v2024_05_01_preview)
+model CustomizationTaskListValidationError {
+  @doc("The customization task that the error is about.")
+  target: CustomizationTask;
+
+  @doc("List of validation errors for the task.")
+  details: Azure.Core.Foundations.Error[];
+}
+
+@doc("Represents a list of tasks to apply to a Dev Box.")
+@resource("customizationGroups")
+@parentResource(DevBox)
+@added(APIVersions.v2024_05_01_preview)
+model CustomizationGroup {
+  @doc("""
+  Tasks to apply. Note by default tasks are excluded from the response when
+  listing customization groups. To include them, use the `include=tasks` query
+  parameter.
+  """)
+  tasks?: CustomizationTask[];
+
+  @doc("The unique URI of the customization group.")
+  @visibility("read")
+  uri?: string;
+
+  @doc("Name of the customization group.")
+  @key("customizationGroupName")
+  @minLength(3)
+  @maxLength(63)
+  @pattern("^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$")
+  @visibility("read")
+  name: string;
+
+  @doc("Status of the customization group.")
+  @visibility("read")
+  status?: CustomizationGroupStatus;
+
+  @doc("Start time of the customization group.")
+  @visibility("read")
+  startTime?: utcDateTime;
+
+  @doc("End time of the customization group.")
+  @visibility("read")
+  endTime?: utcDateTime;
+}