Devcenter dataplane SDK v2023-04-01, integration tests, and samples

sdk/devcenter/Azure.Developer.DevCenter/CHANGELOG.md

@@ -1,14 +1,15 @@
 # Release History
 
-## 1.0.0-beta.3 (Unreleased)
-
-### Features Added
+## 1.0.0 (Unreleased)
+This release updates the Azure DevCenter library to use the 2023-04-01 GA API.
 
 ### Breaking Changes
 
-### Bugs Fixed
-
-### Other Changes
+ - `EnvironmentsClient` renamed to `DeploymentEnvironmentsClient`
+ - `DevBoxesClient` and `DeploymentEnvironmentsClient` no longer accepts project as a constructor parameter
+ - `DeploymentEnvironmentsClient` now works with "environment definitions" instead of "catalog items"
+ - Creating a new environment requires passing `environmentDefinitionName` instead of `catalogItemName`
+ - Creating a new environment requires passing an additional parameter `catalogName`
 
 ## 1.0.0-beta.2 (2023-02-07)
 This release updates the Azure DevCenter library to use the 2022-11-11-preview API.

sdk/devcenter/Azure.Developer.DevCenter/README.md

@@ -22,7 +22,7 @@ dotnet add package Azure.Developer.DevCenter --prerelease
 
 You must have an [Azure subscription](https://azure.microsoft.com/free/dotnet/). In order to take advantage of the C# 8.0 syntax, it is recommended that you compile using the [.NET Core SDK](https://dotnet.microsoft.com/download) 3.0 or higher with a [language version](https://docs.microsoft.com/dotnet/csharp/language-reference/configure-language-version#override-a-default) of `latest`.  It is also possible to compile with the .NET Core SDK 2.1.x using a language version of `preview`.
 
-You must have [configured](https://learn.microsoft.com/azure/dev-box/quickstart-configure-dev-box-service) a DevCenter, Project, Network Connection, Dev Box Definition, and Pool before you can create Dev Boxes
+You must have [configured](https://learn.microsoft.com/azure/dev-box/quickstart-configure-dev-box-service) a DevCenter, Project, Network Connection, Dev Box Definition, and Pool before you can create Dev Boxes 
 
 You must have configured a DevCenter, Project, Catalog, and Environment Type before you can create Environments
 
@@ -36,19 +36,22 @@ To use Azure Active Directory authentication, add the Azure Identity package:
 You will also need to register a new AAD application, or run locally or in an environment with a managed identity.
 If using an application, set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.
 
-```
-Uri endpoint = new Uri("<dev-center-uri>");
-var client = new DevCenterClient(endpoint, new DefaultAzureCredential());
-```
-
 ## Key concepts
 
 The library uses three main clients. The `DevCenterClient` provides access to common APIs for interacting with projects and listing resources across projects.
 The `DevBoxesClient` is scoped to a single project, and provides access to Dev Box resources such as Pools and Dev Boxes.
-The `EnvironmentsClient` is scoped to a single project, and provides access to Environments resources such as Catalog Items, Environment Types, and Environments.
+The `DeploymentEnvironmentsClient` is scoped to a single project, and provides access to Environments resources such as Environment Definitions, Environment Types, and Environments.
 
 Use these clients to interact with DevCenter resources based on your scenario.
 
+```C# Snippet:Azure_DevCenter_CreateClients_Scenario
+var credential = new DefaultAzureCredential();
+
+var devCenterClient = new DevCenterClient(endpoint, credential);
+var devBoxesClient = new DevBoxesClient(endpoint, credential);
+var environmentsClient = new DeploymentEnvironmentsClient(endpoint, credential);
+```
+
 ### Thread safety
 
 We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
@@ -68,99 +71,156 @@ We guarantee that all client instance methods are thread-safe and independent of
 
 You can familiarize yourself with different APIs using [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/devcenter/Azure.Developer.DevCenter/samples).
 
-### Build a client and get projects
+### Get all projects in a dev center
+
+`DevCenterClient` allows you to list projects and retrieve projects by their name.
+
 ```C# Snippet:Azure_DevCenter_GetProjects_Scenario
-var credential = new DefaultAzureCredential();
-var devCenterClient = new DevCenterClient(endpoint, credential);
 string targetProjectName = null;
-await foreach (BinaryData data in devCenterClient.GetProjectsAsync(filter: null, maxCount: 1, context: new()))
+await foreach (BinaryData data in devCenterClient.GetProjectsAsync())
 {
     JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement;
     targetProjectName = result.GetProperty("name").ToString();
 }
 ```
 
 ### List available Dev Box Pools
+
+Interaction with DevBox pools is facilitated through the `DevBoxesClient`. Pools can be listed for a specific project or fetched individually.
+
 ```C# Snippet:Azure_DevCenter_GetPools_Scenario
-var devBoxesClient = new DevBoxesClient(endpoint, targetProjectName, credential);
 string targetPoolName = null;
-await foreach (BinaryData data in devBoxesClient.GetPoolsAsync(filter: null, maxCount: 1, context: new()))
+await foreach (BinaryData data in devBoxesClient.GetPoolsAsync(targetProjectName))
 {
     JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement;
     targetPoolName = result.GetProperty("name").ToString();
 }
 ```
 
 ### Provision a Dev Box
+
+To create a new DevBox, provide the pool name in the content and specify the desired DevBox name. Upon successful execution of this operation, a DevBox should appear in the portal.
+
 ```C# Snippet:Azure_DevCenter_CreateDevBox_Scenario
 var content = new
 {
     poolName = targetPoolName,
 };
 
-Operation<BinaryData> devBoxCreateOperation = await devBoxesClient.CreateDevBoxAsync(WaitUntil.Completed, "me", "MyDevBox", RequestContent.Create(content));
+Operation<BinaryData> devBoxCreateOperation = await devBoxesClient.CreateDevBoxAsync(
+    WaitUntil.Completed,
+    targetProjectName,
+    "me",
+    "MyDevBox",
+    RequestContent.Create(content));
+
 BinaryData devBoxData = await devBoxCreateOperation.WaitForCompletionAsync();
 JsonElement devBox = JsonDocument.Parse(devBoxData.ToStream()).RootElement;
 Console.WriteLine($"Completed provisioning for dev box with status {devBox.GetProperty("provisioningState")}.");
 ```
 
 ### Connect to your Dev Box
+
+Once a DevBox is provisioned, you can connect to it using an RDP connection string. Below is a sample code that demonstrates how to retrieve it.
+
 ```C# Snippet:Azure_DevCenter_ConnectToDevBox_Scenario
-Response remoteConnectionResponse = await devBoxesClient.GetRemoteConnectionAsync("me", "MyDevBox", new());
+Response remoteConnectionResponse = await devBoxesClient.GetRemoteConnectionAsync(
+    targetProjectName,
+    "me",
+    "MyDevBox");
 JsonElement remoteConnectionData = JsonDocument.Parse(remoteConnectionResponse.ContentStream).RootElement;
 Console.WriteLine($"Connect using web URL {remoteConnectionData.GetProperty("webUrl")}.");
 ```
 
 ### Delete the Dev Box
+
+Deleting a DevBox is easy. It's much faster operation than creating a new DevBox. 
+
 ```C# Snippet:Azure_DevCenter_DeleteDevBox_Scenario
-Operation devBoxDeleteOperation = await devBoxesClient.DeleteDevBoxAsync(WaitUntil.Completed, "me", "MyDevBox");
+Operation devBoxDeleteOperation = await devBoxesClient.DeleteDevBoxAsync(
+    WaitUntil.Completed,
+    targetProjectName,
+    "me",
+    "MyDevBox");
 await devBoxDeleteOperation.WaitForCompletionResponseAsync();
 Console.WriteLine($"Completed dev box deletion.");
 ```
 
-### Get Catalog Items
+## Get project catalogs
+
+`DeploymentEnvironmentsClient` can be used to issue a request to get all catalogs in a project.
 
-```C# Snippet:Azure_DevCenter_GetCatalogItems_Scenario
-var environmentsClient = new EnvironmentsClient(endpoint, projectName, credential);
-string catalogItemName = null;
-await foreach (BinaryData data in environmentsClient.GetCatalogItemsAsync(maxCount: 1, context: new()))
+```C# Snippet:Azure_DevCenter_GetCatalogs_Scenario
+string catalogName = null;
+
+await foreach (BinaryData data in environmentsClient.GetCatalogsAsync(projectName))
 {
     JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement;
-    catalogItemName = result.GetProperty("name").ToString();
+    catalogName = result.GetProperty("name").ToString();
 }
 ```
 
-### Get Environment Types
+## Get all environment definitions in a project for a catalog
+
+Environment definitions are a part of the catalog associated with your project. If you don't see the expected environment definitions in the results, please ensure that you have pushed your changes to the catalog repository and synchronized the catalog.
+
+```C# Snippet:Azure_DevCenter_GetEnvironmentDefinitionsFromCatalog_Scenario
+string environmentDefinitionName = null;
+await foreach (BinaryData data in environmentsClient.GetEnvironmentDefinitionsByCatalogAsync(projectName, catalogName, maxCount: 1, context: new()))
+{
+    JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement;
+    environmentDefinitionName = result.GetProperty("name").ToString();
+}
+```
+
+## Get all environment types in a project
+
+Issue a request to get all environment types in a project.
 
 ```C# Snippet:Azure_DevCenter_GetEnvironmentTypes_Scenario
 string environmentTypeName = null;
-await foreach (BinaryData data in environmentsClient.GetEnvironmentTypesAsync(maxCount: 1, context: new()))
+await foreach (BinaryData data in environmentsClient.GetEnvironmentTypesAsync(projectName))
 {
     JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement;
     environmentTypeName = result.GetProperty("name").ToString();
 }
 ```
 
-### Create an Environment
+## Create an environment
+
+Issue a request to create an environment using a specific definition item and environment type.
 
 ```C# Snippet:Azure_DevCenter_CreateEnvironment_Scenario
 var content = new
 {
+    catalogName = catalogName,
     environmentType = environmentTypeName,
-    catalogItemName = catalogItemName,
+    environmentDefinitionName = environmentDefinitionName,
 };
 
 // Deploy the environment
-Operation<BinaryData> environmentCreateOperation = await environmentsClient.CreateOrUpdateEnvironmentAsync(WaitUntil.Completed, "me", "DevEnvironment", RequestContent.Create(content));
+Operation<BinaryData> environmentCreateOperation = await environmentsClient.CreateOrUpdateEnvironmentAsync(
+    WaitUntil.Completed,
+    projectName,
+    "me",
+    "DevEnvironment",
+    RequestContent.Create(content));
+
 BinaryData environmentData = await environmentCreateOperation.WaitForCompletionAsync();
 JsonElement environment = JsonDocument.Parse(environmentData.ToStream()).RootElement;
 Console.WriteLine($"Completed provisioning for environment with status {environment.GetProperty("provisioningState")}.");
 ```
 
-### Delete an Environment
+## Delete an environment
+
+Issue a request to delete an environment.
 
 ```C# Snippet:Azure_DevCenter_DeleteEnvironment_Scenario
-Operation environmentDeleteOperation = await environmentsClient.DeleteEnvironmentAsync(WaitUntil.Completed, projectName, "DevEnvironment");
+Operation environmentDeleteOperation = await environmentsClient.DeleteEnvironmentAsync(
+    WaitUntil.Completed,
+    projectName,
+    "me",
+    "DevEnvironment");
 await environmentDeleteOperation.WaitForCompletionResponseAsync();
 Console.WriteLine($"Completed environment deletion.");
 ```