Azure.Developer.DevCenter 1.0.0

Azure DevCenter 的 .NET 客户端库

DevCenter 客户端库提供访问和管理 Microsoft Dev Box 和 Azure 部署环境资源的权限。该 SDK 可以在 Azure 中管理开发机器和环境。

使用 Azure DevCenter 客户端库：

创建、访问、管理和删除 Dev Box 资源 创建、部署、管理和删除 环境 资源

源代码 | 包（NuGet） | API 参考文档 | 产品文档

入门指南

安装软件包

使用 NuGet 安装 .NET 客户端库

dotnet add package Azure.Developer.DevCenter --prerelease

先决条件

您必须拥有一个 Azure 订阅。要利用 C# 8.0 语法，建议您使用 .NET Core SDK 3.0 或更高版本，并使用 语言版本 latest 来编译。您也可以使用 .NET Core SDK 2.1.x，通过语言版本 preview 来编译。

在您能够创建开发盒之前，必须配置 DevCenter、项目、网络连接、开发盒定义和池。

在您能够创建环境之前，必须配置 DevCenter、项目、目录和环境类型。

验证客户端身份

您可以使用标准的 Azure Active Directory 令牌凭证身份验证 来访问客户端。与此资源交互的标识必须在此交互的项目资源上有至少读取权限。管理开发盒的标识必须拥有针对开发盒场景的 DevCenter 项目管理员 或 DevCenter 开发盒用户 角色。这些角色可以直接分配到项目，或者从更广泛的范围（如资源组或订阅）继承。要使用 Azure Active Directory 身份验证，请添加 Azure Identity 包

dotnet add package Azure.Identity

您还需要注册一个新的 AAD 应用程序，或在本地或在具有托管标识的环境中运行。如果使用应用程序，请设置 AAD 应用的客户端 ID、租户 ID 和客户端秘密的值作为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET。

关键概念

库使用三个主要的客户端。`DevCenterClient` 提供了与项目和跨项目列出资源交互的常见 API 访问。`DevBoxesClient` 作用域限定在一个项目内，并提供对池和开发盒等开发盒资源的访问。`DeploymentEnvironmentsClient` 作用域限定在一个项目内，并提供对环境定义、环境类型和环境等环境资源访问。

根据您的场景使用这些客户端与 DevCenter 资源进行交互。

var credential = new DefaultAzureCredential();

var devCenterClient = new DevCenterClient(endpoint, credential);
var devBoxesClient = new DevBoxesClient(endpoint, credential);
var environmentsClient = new DeploymentEnvironmentsClient(endpoint, credential);

或者使用 `DevCenterClient` 创建具有相同端点和凭证的 `DevBoxesClient` 和 `DeploymentEnvironmentsClient`。

devBoxesClient = devCenterClient.GetDevBoxesClient();
environmentsClient = devCenterClient.GetDeploymentEnvironmentsClient();

线程安全性

我们保证所有客户端实例方法是线程安全的，并且彼此独立（指南）。这确保了重用客户端实例的建议总是安全的，即使在多线程情况下也是。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理错误 | 诊断 | 模拟 | 客户端生命周期

示例

您可以使用 示例 熟悉不同的 API。

获取开发中心中的所有项目

DevCenterClient 允许您列出项目和通过其名称检索项目。

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;

列出可用的 Dev Box 池

通过 DevBoxesClient 来便利地与 DevBox 池交互。可以为特定项目列出池或单独获取池。

// 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;

配置 Dev Box

要创建新的 DevBox，在内容中提供池名并指定所需的 DevBox 名称。该操作执行成功后，DevBox 应该会出现在门户中。

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}.");

连接到您的 Dev Box

一旦配置了 DevBox，就可以使用 RDP 连接字符串连接到它。下面是一个示例代码，展示了如何获取连接字符串。

RemoteConnection remoteConnection = await devBoxesClient.GetRemoteConnectionAsync(
    projectName,
    "me",
    devBoxName);

Console.WriteLine($"Connect using web URL {remoteConnection.WebUri}.");

删除 Dev Box

删除 DevBox 是一件易事。它比创建新的 DevBox 快得多。

Operation devBoxDeleteOperation = await devBoxesClient.DeleteDevBoxAsync(
    WaitUntil.Completed,
    projectName,
    "me",
    devBoxName);
await devBoxDeleteOperation.WaitForCompletionResponseAsync();
Console.WriteLine($"Completed dev box deletion.");

获取项目目录

DeploymentEnvironmentsClient 可以用来发送请求以获取项目中的所有目录。

// 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}");

获取项目中某个目录的所有环境定义

环境定义是项目相关联的目录的一部分。如果您在结果中看不到预期的环境定义，请确保您已将更改推送到目录存储库并同步了目录。

//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}");

获取项目中所有环境类型

发送请求以获取项目中的所有环境类型。

//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}");

创建环境

使用特定定义项和环境类型发送创建环境的请求。

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}.");

删除环境

发送请求以删除环境。

Operation environmentDeleteOperation = await environmentsClient.DeleteEnvironmentAsync(
    WaitUntil.Completed,
    projectName,
    "me",
    "DevEnvironment");
await environmentDeleteOperation.WaitForCompletionResponseAsync();
Console.WriteLine($"Completed environment deletion.");

故障排除

由于其他资源的问题或您在 Azure 中的配置问题，在 Dev Box 配置过程中可能会出现错误。如果您在_devbox_上配置失败，可以查看操作错误或 errorDetails 属性，这将显示更多关于问题和如何解决它们的信息。在尝试创建 Dev Box 之前，请确保您的 Pool、网络连接和 Dev Box 定义资源均处于良好状态。它们配置的问题将阻止成功创建您的 Dev Box。

由于模板、参数或其他资源配置问题，在环境部署期间可能会出现错误。您可以查看操作错误，这将为您提供更多有关问题和如何解决它们的信息。请确保您的项目环境类型的身份对目标订阅有正确的权限，您正在传递模板所需的所有参数，并且所有参数都是有效的。

贡献

有关构建、测试和为该库做出贡献的详细信息，请参阅 DevCenter CONTRIBUTING.md。

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），并声明您有权，实际上确实授予我们使用您贡献的权利。有关详细信息，请访问 cla.microsoft.com。

当您提交拉取请求时，CLA-bot 将自动确定您是否需要提供 CLA 并适当地标记 PR（例如，标签、注释）。只需遵循 bot 提供的说明即可。您只需要在整个使用我们的 CLA 的存储库中做这一次。

此项目已采用 Microsoft Open Source Code of Conduct。有关更多信息，请参阅 Code of Conduct FAQ 或通过 [email protected] 联系以获取任何额外的问题或评论。

下一步

有关Azure SDK的更多信息，请参阅此网站