你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Azure DevCenter client library for .NET - version 1.0.0
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.
Use the client library for Azure DevCenter to:
Create, access, manage, and delete Dev Box resources Create, deploy, manage, and delete Environment resources
Source code | Package (NuGet) | API reference documentation | Product documentation
Install the client library for .NET with NuGet:
dotnet add package Azure.Developer.DevCenter --prerelease
You must have an Azure subscription. In order to take advantage of the C# 8.0 syntax, it is recommended that you compile using the .NET Core SDK 3.0 or higher with a language version 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 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
You can use standard Azure Active Directory Token Credential authentication 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 or DevCenter 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). To use Azure Active Directory authentication, add the Azure Identity package:
dotnet add package Azure.Identity
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.
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 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.
var credential = new DefaultAzureCredential();
var devCenterClient = new DevCenterClient(endpoint, credential);
var devBoxesClient = new DevBoxesClient(endpoint, credential);
var environmentsClient = new DeploymentEnvironmentsClient(endpoint, credential);
Alternatively use DevCenterClient
to create DevBoxesClient
and DeploymentEnvironmentsClient
sharing same endpoint and credential across clients.
devBoxesClient = devCenterClient.GetDevBoxesClient();
environmentsClient = devCenterClient.GetDeploymentEnvironmentsClient();
We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.
Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime
You can familiarize yourself with different APIs using Samples.
DevCenterClient
allows you to list projects and retrieve projects by their name.
string devCenterUri = "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com";
var endpoint = new Uri(devCenterUri);
var credential = new DefaultAzureCredential();
var devCenterClient = new DevCenterClient(endpoint, credential);
List<DevCenterProject> projects = await devCenterClient.GetProjectsAsync().ToEnumerableAsync();
var projectName = projects.FirstOrDefault().Name;
Interaction with DevBox pools is facilitated through the DevBoxesClient
. Pools can be listed for a specific project or fetched individually.
// Create DevBox-es client from existing DevCenter client
var devBoxesClient = devCenterClient.GetDevBoxesClient();
// Grab a pool
List<DevBoxPool> pools = await devBoxesClient.GetPoolsAsync(projectName).ToEnumerableAsync();
var poolName = pools.FirstOrDefault().Name;
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.
var devBoxName = "MyDevBox";
var devBox = new DevBox(devBoxName, poolName);
Operation<DevBox> devBoxCreateOperation = await devBoxesClient.CreateDevBoxAsync(
WaitUntil.Completed,
projectName,
"me",
devBox);
devBox = await devBoxCreateOperation.WaitForCompletionAsync();
Console.WriteLine($"Completed provisioning for dev box with status {devBox.ProvisioningState}.");
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.
RemoteConnection remoteConnection = await devBoxesClient.GetRemoteConnectionAsync(
projectName,
"me",
devBoxName);
Console.WriteLine($"Connect using web URL {remoteConnection.WebUri}.");
Deleting a DevBox is easy. It's much faster operation than creating a new DevBox.
Operation devBoxDeleteOperation = await devBoxesClient.DeleteDevBoxAsync(
WaitUntil.Completed,
projectName,
"me",
devBoxName);
await devBoxDeleteOperation.WaitForCompletionResponseAsync();
Console.WriteLine($"Completed dev box deletion.");
DeploymentEnvironmentsClient
can be used to issue a request to get all catalogs in a project.
// Create deployment environments client from existing DevCenter client
var environmentsClient = devCenterClient.GetDeploymentEnvironmentsClient();
//List all catalogs and grab the first one
//Using foreach, but could also use a List
string catalogName = default;
await foreach (DevCenterCatalog catalog in environmentsClient.GetCatalogsAsync(projectName))
{
catalogName = catalog.Name;
break;
}
Console.WriteLine($"Using catalog {catalogName}");
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.
//List all environment definition for a catalog and grab the first one
string environmentDefinitionName = default;
await foreach (EnvironmentDefinition environmentDefinition in environmentsClient.GetEnvironmentDefinitionsByCatalogAsync(projectName, catalogName))
{
environmentDefinitionName = environmentDefinition.Name;
break;
}
Console.WriteLine($"Using environment definition {environmentDefinitionName}");
Issue a request to get all environment types in a project.
//List all environment types and grab the first one
string environmentTypeName = default;
await foreach (DevCenterEnvironmentType environmentType in environmentsClient.GetEnvironmentTypesAsync(projectName))
{
environmentTypeName = environmentType.Name;
break;
}
Console.WriteLine($"Using environment type {environmentTypeName}");
Issue a request to create an environment using a specific definition item and environment type.
var requestEnvironment = new DevCenterEnvironment
(
"DevEnvironment",
environmentTypeName,
catalogName,
environmentDefinitionName
);
// Deploy the environment
Operation<DevCenterEnvironment> environmentCreateOperation = await environmentsClient.CreateOrUpdateEnvironmentAsync(
WaitUntil.Completed,
projectName,
"me",
requestEnvironment);
DevCenterEnvironment environment = await environmentCreateOperation.WaitForCompletionAsync();
Console.WriteLine($"Completed provisioning for environment with status {environment.ProvisioningState}.");
Issue a request to delete an environment.
Operation environmentDeleteOperation = await environmentsClient.DeleteEnvironmentAsync(
WaitUntil.Completed,
projectName,
"me",
"DevEnvironment");
await environmentDeleteOperation.WaitForCompletionResponseAsync();
Console.WriteLine($"Completed environment deletion.");
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.
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.
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. 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.
See the DevCenter CONTRIBUTING.md for details on building, testing, and contributing to this library.
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.
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.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
For more information on Azure SDK, please refer to this website