|
| 1 | +# Azure DevCenter client library for .NET |
| 2 | + |
| 3 | +The DevCenter client library provides access to manage resources for Microsoft Dev Box and Azure Deployment Environments. This SDK enables managing developer machines and environments in Azure. |
| 4 | + |
| 5 | +Use the client library for Azure DevCenter to: |
| 6 | +> Create, access, manage, and delete [Dev Box](https://learn.microsoft.com/azure/dev-box) resources |
| 7 | +> Create, deploy, manage, and delete [Environment](https://learn.microsoft.com/azure/deployment-environments) resources |
| 8 | +
|
| 9 | + [Source code](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/devcenter/Azure.Developer.DevCenter/src) | [Package (NuGet)](https://www.nuget.org/packages/) | [API reference documentation](https://azure.github.io/azure-sdk-for-net) | [Product documentation](https://docs.microsoft.com/azure) |
| 10 | + |
| 11 | +## Getting started |
| 12 | + |
| 13 | +### Install the package |
| 14 | + |
| 15 | +Install the client library for .NET with [NuGet](https://www.nuget.org/ ): |
| 16 | + |
| 17 | +```dotnetcli |
| 18 | +dotnet add package Azure.Developer.DevCenter --prerelease |
| 19 | +``` |
| 20 | + |
| 21 | +### Prerequisites |
| 22 | + |
| 23 | +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`. |
| 24 | + |
| 25 | +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 |
| 26 | + |
| 27 | +You must have configured a DevCenter, Project, Catalog, and Environment Type before you can create Environments |
| 28 | + |
| 29 | +### Authenticate the client |
| 30 | + |
| 31 | +You can use standard Azure Active Directory [Token Credential authentication](https://learn.microsoft.com/dotnet/api/azure.core.tokencredential) to access the client. The identity interacting with all resources must have a minimum of Read access on the Project resources it is interacting with. The identity managing Dev Boxes must have the [DevCenter Project Admin](https://learn.microsoft.com/azure/dev-box/how-to-project-admin) or [DevCenter Dev Box User](https://learn.microsoft.com/azure/dev-box/how-to-dev-box-user) roles for Dev Box scenarios. These roles can be assigned directly to the project, or inherited from a broader scope (such as the resource group or subscription). |
| 32 | +To use Azure Active Directory authentication, add the Azure Identity package: |
| 33 | + |
| 34 | +`dotnet add package Azure.Identity` |
| 35 | + |
| 36 | +You will also need to register a new AAD application, or run locally or in an environment with a managed identity. |
| 37 | +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. |
| 38 | + |
| 39 | +``` |
| 40 | +string tenantId = "<tenant-id>"; |
| 41 | +string devCenterName = "<dev-center-name>"; |
| 42 | +var client = new DevCenterClient( |
| 43 | + tenantId, |
| 44 | + devCenterName, |
| 45 | + new DefaultAzureCredential()); |
| 46 | +``` |
| 47 | + |
| 48 | +## Key concepts |
| 49 | + |
| 50 | +The library uses three main clients. The `DevCenterClient` provides access to common APIs for interacting with projects and listing resources across projects. |
| 51 | +The `DevBoxesClient` is scoped to a single project, and provides access to Dev Box resources such as Pools and Dev Boxes. |
| 52 | +The `EnvironmentsClient` is scoped to a single project, and provides access to Environments resources such as Catalog Items, Environment Types, and Environments. |
| 53 | + |
| 54 | +Use these clients to interact with DevCenter resources based on your scenario. |
| 55 | + |
| 56 | +### Thread safety |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +### Additional concepts |
| 61 | +<!-- CLIENT COMMON BAR --> |
| 62 | +[Client options](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#configuring-service-clients-using-clientoptions) | |
| 63 | +[Accessing the response](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#accessing-http-response-details-using-responset) | |
| 64 | +[Long-running operations](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#consuming-long-running-operations-using-operationt) | |
| 65 | +[Handling failures](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#reporting-errors-requestfailedexception) | |
| 66 | +[Diagnostics](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md) | |
| 67 | +[Mocking](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#mocking) | |
| 68 | +[Client lifetime](https://devblogs.microsoft.com/azure-sdk/lifetime-management-and-thread-safety-guarantees-of-azure-sdk-net-clients/) |
| 69 | +<!-- CLIENT COMMON BAR --> |
| 70 | + |
| 71 | +## Examples |
| 72 | + |
| 73 | +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). |
| 74 | + |
| 75 | +### Build a client and get projects |
| 76 | +```C# Snippet:Azure_DevCenter_GetProjects_Scenario |
| 77 | +var credential = new DefaultAzureCredential(); |
| 78 | +var devCenterClient = new DevCenterClient(tenantId, devCenterName, credential); |
| 79 | +string targetProjectName = null; |
| 80 | +await foreach (BinaryData data in devCenterClient.GetProjectsAsync(filter: null, maxCount: 1)) |
| 81 | +{ |
| 82 | + JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement; |
| 83 | + targetProjectName = result.GetProperty("name").ToString(); |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +### List available Dev Box Pools |
| 88 | +```C# Snippet:Azure_DevCenter_GetPools_Scenario |
| 89 | +var devBoxesClient = new DevBoxesClient(tenantId, devCenterName, targetProjectName, credential); |
| 90 | +string targetPoolName = null; |
| 91 | +await foreach (BinaryData data in devBoxesClient.GetPoolsAsync(filter: null, maxCount: 1)) |
| 92 | +{ |
| 93 | + JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement; |
| 94 | + targetPoolName = result.GetProperty("name").ToString(); |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +### Provision a Dev Box |
| 99 | +```C# Snippet:Azure_DevCenter_CreateDevBox_Scenario |
| 100 | +var content = new |
| 101 | +{ |
| 102 | + poolName = targetPoolName, |
| 103 | +}; |
| 104 | + |
| 105 | +Operation<BinaryData> devBoxCreateOperation = await devBoxesClient.CreateDevBoxAsync(WaitUntil.Completed, "MyDevBox", RequestContent.Create(content)); |
| 106 | +BinaryData devBoxData = await devBoxCreateOperation.WaitForCompletionAsync(); |
| 107 | +JsonElement devBox = JsonDocument.Parse(devBoxData.ToStream()).RootElement; |
| 108 | +Console.WriteLine($"Completed provisioning for dev box with status {devBox.GetProperty("provisioningState")}."); |
| 109 | +``` |
| 110 | + |
| 111 | +### Connect to your Dev Box |
| 112 | +```C# Snippet:Azure_DevCenter_ConnectToDevBox_Scenario |
| 113 | +Response remoteConnectionResponse = await devBoxesClient.GetRemoteConnectionAsync("MyDevBox"); |
| 114 | +JsonElement remoteConnectionData = JsonDocument.Parse(remoteConnectionResponse.ContentStream).RootElement; |
| 115 | +Console.WriteLine($"Connect using web URL {remoteConnectionData.GetProperty("webUrl")}."); |
| 116 | +``` |
| 117 | + |
| 118 | +### Delete the Dev Box |
| 119 | +```C# Snippet:Azure_DevCenter_DeleteDevBox_Scenario |
| 120 | +Operation devBoxDeleteOperation = await devBoxesClient.DeleteDevBoxAsync(WaitUntil.Completed, "MyDevBox"); |
| 121 | +await devBoxDeleteOperation.WaitForCompletionResponseAsync(); |
| 122 | +Console.WriteLine($"Completed dev box deletion."); |
| 123 | +``` |
| 124 | + |
| 125 | +### Get Catalog Items |
| 126 | + |
| 127 | +```C# Snippet:Azure_DevCenter_GetCatalogItems_Scenario |
| 128 | +var environmentsClient = new EnvironmentsClient(tenantId, devCenterName, projectName, credential); |
| 129 | +string catalogItemName = null; |
| 130 | +await foreach (BinaryData data in environmentsClient.GetCatalogItemsAsync(maxCount: 1)) |
| 131 | +{ |
| 132 | + JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement; |
| 133 | + catalogItemName = result.GetProperty("name").ToString(); |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +### Get Environment Types |
| 138 | + |
| 139 | +```C# Snippet:Azure_DevCenter_GetEnvironmentTypes_Scenario |
| 140 | +string environmentTypeName = null; |
| 141 | +await foreach (BinaryData data in environmentsClient.GetEnvironmentTypesAsync(maxCount: 1)) |
| 142 | +{ |
| 143 | + JsonElement result = JsonDocument.Parse(data.ToStream()).RootElement; |
| 144 | + environmentTypeName = result.GetProperty("name").ToString(); |
| 145 | +} |
| 146 | +``` |
| 147 | + |
| 148 | +### Create an Environment |
| 149 | + |
| 150 | +```C# Snippet:Azure_DevCenter_CreateEnvironment_Scenario |
| 151 | +var content = new |
| 152 | +{ |
| 153 | + environmentType = environmentTypeName, |
| 154 | + catalogItemName = catalogItemName, |
| 155 | +}; |
| 156 | + |
| 157 | +// Deploy the environment |
| 158 | +Operation<BinaryData> environmentCreateOperation = await environmentsClient.CreateOrUpdateEnvironmentAsync(WaitUntil.Completed, "DevEnvironment", RequestContent.Create(content)); |
| 159 | +BinaryData environmentData = await environmentCreateOperation.WaitForCompletionAsync(); |
| 160 | +JsonElement environment = JsonDocument.Parse(environmentData.ToStream()).RootElement; |
| 161 | +Console.WriteLine($"Completed provisioning for environment with status {environment.GetProperty("provisioningState")}."); |
| 162 | +``` |
| 163 | + |
| 164 | +### Delete an Environment |
| 165 | + |
| 166 | +```C# Snippet:Azure_DevCenter_DeleteEnvironment_Scenario |
| 167 | +Operation environmentDeleteOperation = await environmentsClient.DeleteEnvironmentAsync(WaitUntil.Completed, projectName, "DevEnvironment"); |
| 168 | +await environmentDeleteOperation.WaitForCompletionResponseAsync(); |
| 169 | +Console.WriteLine($"Completed environment deletion."); |
| 170 | +``` |
| 171 | + |
| 172 | +## Troubleshooting |
| 173 | + |
| 174 | +Errors may occur during Dev Box provisioning due to problems with other resources or your Azure configuration. You can view the operation error or the `errorDetails` property on the Dev Box if provisioning fails, which will show more information about the problem and how to resolve it. |
| 175 | +Ensure that your Pool, Network Connection, and Dev Box Definition resources are all in a healthy state before attempting to create a Dev Box. Problems with their configurations will prevent successful creation of your Dev Box. |
| 176 | + |
| 177 | +Errors may occur during Environment deployment due to problems with your template, parameters, or the configuration of other resources. You can view the operation error, which will provide more information about the problem and how to resolve it. |
| 178 | +Ensure that your Project Environment Type's identity has the correct permissions to the target subscription, that you are passing all parameters which are required by the template, and that all parameters are valid. |
| 179 | + |
| 180 | +## Contributing |
| 181 | + |
| 182 | +See the [DevCenter CONTRIBUTING.md][azdevcenter_contrib] for details on building, testing, and contributing to this library. |
| 183 | + |
| 184 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla]. |
| 185 | + |
| 186 | +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. |
| 187 | + |
| 188 | +This project has adopted the [Microsoft Open Source Code of Conduct ][code_of_conduct]. For more information see the [Code of Conduct FAQ ][code_of_conduct_faq] or contact [[email protected]][email_opencode] with any additional questions or comments. |
| 189 | + |
| 190 | +<!-- LINKS --> |
| 191 | +[azdevcenter_contrib]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/devcenter/CONTRIBUTING.md |
| 192 | +[style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization |
| 193 | +[style-guide-cloud]: https://aka.ms/azsdk/cloud-style-guide |
| 194 | +[cla]: https://cla.microsoft.com |
| 195 | +[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ |
| 196 | +[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 197 | +[email_opencode]: mailto:[email protected] |
| 198 | + |
| 199 | + |
| 200 | + |
| 201 | +## Next steps |
| 202 | + |
| 203 | +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) |
0 commit comments