интеграция .NET AspireAzure Key Vault

2025-06-18

Включает: интеграция хостинга — и — Client Интеграция

Azure Key Vault — это облачная служба для безопасного хранения и доступа к секретам. Интеграция .NET AspireAzure Key Vault позволяет вам подключаться к экземплярам Azure Key Vault из ваших .NET приложений.

Хостинг-интеграция

Модели интеграции Azure Key Vault моделируют ресурс Key Vault как тип AzureKeyVaultResource. Чтобы получить доступ к этому типу и API для их использования в хосте приложения проекта, установите пакет NuGet 📦Aspire.Hosting.Azure.KeyVault:

.NET интерфейс командной строки
СсылкаНаПакет

dotnet add package Aspire.Hosting.Azure.KeyVault

<PackageReference Include="Aspire.Hosting.Azure.KeyVault"
                  Version="*" />

Дополнительные сведения см. в dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Добавьте ресурс Azure Key Vault

В проекте хоста приложения вызовите AddAzureKeyVault в экземпляре билдера, чтобы добавить ресурс Azure Key Vault.

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddAzureKeyVault("key-vault");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyVault);

// After adding all resources, run the app...

Метод WithReference настраивает подключение в ExampleProject с именем "key-vault".

Это важно

По умолчанию AddAzureKeyVault настраивает встроенную роль администратора Key Vault.

Подсказка

При вызове AddAzureKeyVaultон неявно вызывает AddAzureProvisioning, что добавляет поддержку для генерации ресурсов Azure динамически во время запуска приложения. Приложение должно конфигурировать соответствующую подписку и местоположение. Дополнительные сведения см. в разделе Локальная подготовка: Конфигурация.

Созданный автоматически процессом Bicep

Если вы не знакомы с Bicep, это предметно-ориентированный язык для описания ресурсов Azure. При использовании .NET.NET Aspire вам не нужно писать Bicep вручную, служебные API автоматически создают Bicep для вас. При публикации приложения сгенерированный файл Bicep выводится рядом с файлом манифеста. Когда вы добавляете ресурс Azure Key Vault, создается следующий Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: take('keyvault-${uniqueString(resourceGroup().id)}', 24)
  location: location
  properties: {
    tenantId: tenant().tenantId
    sku: {
      family: 'A'
      name: 'standard'
    }
    enableRbacAuthorization: true
  }
  tags: {
    'aspire-resource-name': 'key-vault'
  }
}

output vaultUri string = key_vault.properties.vaultUri

output name string = key_vault.name

Предшествующий Bicep — это модуль, который предоставляет Azure Key Vault ресурс. Кроме того, в отдельном модуле создаются назначения ролей для ресурса Azure.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param key_vault_outputs_name string

param principalType string

param principalId string

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: key_vault_outputs_name
}

resource key_vault_KeyVaultSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
    principalType: principalType
  }
  scope: key_vault
}

Созданный Bicep является отправной точкой и находится под влиянием изменений инфраструктуры подготовки в C#. Настройки, внесённые непосредственно в файл Bicep, будут перезаписаны, поэтому внесите изменения через API C# для управления, чтобы убедиться, что они отражаются в генерируемых файлах.

Настройка инфраструктуры подготовки

Все .NET AspireAzure ресурсы — это подклассы типа AzureProvisioningResource. Этот тип позволяет настраивать созданный Bicep, предоставляя удобный API для конфигурации ресурсов Azure с помощью API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Например, можно настроить sku, RBAC, tagsи многое другое. В следующем примере показано, как настроить ресурс Azure Key Vault:

builder.AddAzureKeyVault("key-vault")
    .ConfigureInfrastructure(infra =>
    {
        var keyVault = infra.GetProvisionableResources()
                            .OfType<KeyVaultService>()
                            .Single();

        keyVault.Properties.Sku = new()
        {
            Family = KeyVaultSkuFamily.A,
            Name = KeyVaultSkuName.Premium,
        };
        keyVault.Properties.EnableRbacAuthorization = true;
        keyVault.Tags.Add("ExampleKey", "Example value");
    });

Предыдущий код:

Связывает вызов с API ConfigureInfrastructure:
- Параметр infra является экземпляром типа AzureResourceInfrastructure.
- Ресурсы, подлежащие предоставлению, извлекаются путем вызова метода GetProvisionableResources().
- Получен один KeyVaultService ресурс.
- Свойству Sku присваивается новый экземпляр KeyVaultSku.
- Для свойства KeyVaultProperties.EnableRbacAuthorization задано значение true.
- Тег добавляется в ресурс с ключом ExampleKey и значением Example value.

Существует множество дополнительных параметров конфигурации для настройки ресурса Key Vault. Дополнительные сведения см. в разделах Azure.Provisioning.KeyVault и Azure. Настройка параметров.

Подключение к существующему экземпляру Azure Key Vault

Возможно, у вас есть существующий Azure экземпляр AI Key Vault, к которому вы хотите подключиться. Вы можете создать цепочку вызовов, чтобы указать, что AzureKeyVaultResource является существующим ресурсом:

var builder = DistributedApplication.CreateBuilder(args);

var existingKeyVaultName = builder.AddParameter("existingKeyVaultName");
var existingKeyVaultResourceGroup = builder.AddParameter("existingKeyVaultResourceGroup");

var keyvault = builder.AddAzureKeyVault("ke-yvault")
                    .AsExisting(existingKeyVaultName, existingKeyVaultResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyvault);

// After adding all resources, run the app...

Это важно

При вызове методов RunAsExisting, PublishAsExisting или AsExisting для работы с ресурсами, которые уже присутствуют в подписке Azure, необходимо добавить определенные значения конфигурации в конфигурацию приложения, чтобы .NET Aspire могли их обнаружить. Необходимые значения конфигурации включают SubscriptionId, AllowResourceGroupCreation, ResourceGroup и Location. Если вы их не настроите, на панели мониторинга .NET.NET Aspire отображаются ошибки "Отсутствует конфигурация". Дополнительные сведения о настройке см. в разделе "Конфигурация".

Дополнительные сведения о том, как использовать Azure Key Vault существующие ресурсы, см. в разделе "Использование существующих Azure ресурсов".

Примечание.

Кроме того, вместо представления Azure Key Vault ресурса можно добавить строку подключения к узлу приложения. Этот подход слабо типизированный и не работает с назначениями ролей или настройками инфраструктуры. Дополнительные сведения см. в статье Добавление существующих ресурсов Azure со строками подключения.

интеграция Client

Чтобы приступить к работе с интеграцией клиента , установите пакет NuGet ..Security.KeyVault в проект приложения, использующий клиент .

.NET интерфейс командной строки
СсылкаНаПакет

dotnet add package Aspire.Azure.Security.KeyVault

<PackageReference Include="Aspire.Azure.Security.KeyVault"
                  Version="*" />

Интеграция клиента предоставляет два способа доступа к секретам из Azure Key Vault:

Добавьте секреты в конфигурацию приложения с помощью IConfiguration или шаблона IOptions<T>.
Используйте SecretClient для получения секретов по запросу.

Добавление секретов в конфигурацию

В файле Program.cs проекта, использующего клиент, вызовите метод расширения AddAzureKeyVaultSecrets на IConfiguration, чтобы добавить секреты в конфигурацию вашего приложения. Метод принимает параметр имени подключения.

builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault");

Примечание.

Имя API AddAzureKeyVaultSecrets вызвало немного путаницы. Метод используется для настройки SecretClient на основе заданного имени подключения и не используется для добавления секретов в конфигурацию.

Подсказка

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Azure Key Vault в проект узла приложения. Дополнительные сведения см. в разделе Добавление Azure Key Vault ресурса.

Затем можно получить значение конфигурации на основе секретных данных через стандартные API-интерфейсы IConfiguration или даже путем привязки к строго типизированным классам с шаблоном параметров . Чтобы получить секрет из примера класса службы, зарегистрированного в контейнере внедрения зависимостей, рассмотрите следующие фрагменты кода:

Получите экземпляр `IConfiguration`

public class ExampleService(IConfiguration configuration)
{
    // Use configuration...
    private string _secretValue = configuration["SecretKey"];
}

Предполагается, что в предыдущем примере вы также зарегистрировали экземпляр IConfiguration для внедрения зависимостей. Дополнительные сведения см. в статье внедрение зависимостей в .NET.

Получите экземпляр `IOptions<T>`

public class ExampleService(IOptions<SecretOptions> options)
{
    // Use options...
    private string _secretValue = options.Value.SecretKey;
}

В предыдущем примере предполагается, что вы настроили класс SecretOptions для использования с шаблоном параметров. Дополнительные сведения см. в разделе "Шаблон параметров " в .NET.

Дополнительные параметры API AddAzureKeyVaultSecrets доступны при необходимости для следующих сценариев:

Action<AzureSecurityKeyVaultSettings>? configureSettings: чтобы настроить некоторые или все параметры непосредственно.
Action<SecretClientOptions>? configureClientOptions: настроить SecretClientOptions в строке.
AzureKeyVaultConfigurationOptions? options: для настройки встроенного AzureKeyVaultConfigurationOptions.

Добавить секретного клиента Azure

Кроме того, можно использовать SecretClient непосредственно для получения секретов по запросу. Для этого требуется немного другой API регистрации.

В файле Program.cs проекта, используемого клиентом, вызовите расширение AddAzureKeyVaultClient в экземпляре IHostApplicationBuilder, чтобы зарегистрировать SecretClient для использования с помощью контейнера внедрения зависимостей.

builder.AddAzureKeyVaultClient(connectionName: "key-vault");

Подсказка

После добавления SecretClient в билдер, можно получить экземпляр SecretClient при помощи внедрения зависимостей. Например, чтобы получить клиент из примера службы, определите его как параметр конструктора и убедитесь, что класс ExampleService зарегистрирован в контейнере внедрения зависимостей:

public class ExampleService(SecretClient client)
{
    // Use client...
}

Дополнительные сведения о внедрении зависимостей смотрите в .NET внедрение зависимостей.

Добавить клиента с ключом Azure Key Vault

Могут возникнуть ситуации, когда вам может понадобиться зарегистрировать несколько экземпляров SecretClient с различными именами подключений. Чтобы зарегистрировать клиентов с ключом Azure Key Vault, вызовите метод AddKeyedAzureKeyVaultClient.

builder.AddKeyedAzureKeyVaultClient(name: "feature-toggles");
builder.AddKeyedAzureKeyVaultClient(name: "admin-portal");

Затем можно получить объекты SecretClient с помощью инъекции зависимостей. Например, чтобы получить клиента из примера сервиса:

public class ExampleService(
    [FromKeyedServices("feature-toggles")] SecretClient featureTogglesClient,
    [FromKeyedServices("admin-portal")] SecretClient adminPortalClient)
{
    // Use clients...
}

Для получения дополнительной информации о ключевых службах см. раздел .NET внедрение зависимостей: Ключевые службы.

Конфигурация

Интеграция .NET AspireAzure Key Vault предоставляет несколько вариантов настройки SecretClient на основе требований и соглашений проекта.

Использование поставщиков конфигураций

Интеграция .NET AspireAzure Key Vault поддерживает Microsoft.Extensions.Configuration. Он загружает AzureSecurityKeyVaultSettings из appsettings.json или других файлов конфигурации с помощью ключа Aspire:Azure:Security:KeyVault.

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Полная схема интеграции клиента Azure Key VaultJSON см. в Aspire.Azure.Security.KeyVault/ConfigurationSchema.json.

Если вы настроили конфигурации в разделе Aspire:Azure:Security:KeyVault файла appsettings.json, можно просто вызвать метод AddAzureKeyVaultSecrets без передачи параметров.

Использование встроенных делегатов

Вы также можете передать делегат Action<AzureSecurityKeyVaultSettings> для настройки некоторых или всех встроенных параметров, например, чтобы задать AzureSecurityKeyVaultSettings.VaultUri:

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureSettings: settings => settings.VaultUri = new Uri("KEY_VAULT_URI"));

Вы также можете настроить SecretClientOptions с помощью делегата Action<SecretClientOptions>, который является необязательным параметром метода AddAzureKeyVaultSecrets. Например, чтобы задать идентификатор KeyClientOptions.DisableChallengeResourceVerification для идентификации клиента:

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureClientOptions: options => options.DisableChallengeResourceVerification = true))

Параметры конфигурации

Следующие настраиваемые параметры предоставляются через класс AzureSecurityKeyVaultSettings:

Имя	Описание
AzureSecurityKeyVaultSettings.Credential	Учетные данные, используемые для аутентификации в Azure Key Vault.
AzureSecurityKeyVaultSettings.DisableHealthChecks	Логическое значение, указывающее, отключена ли проверка работоспособности ключевого хранилища.
AzureSecurityKeyVaultSettings.DisableTracing	Логическое значение, указывающее, отключена ли трассировка OpenTelemetry или нет.
AzureSecurityKeyVaultSettings.VaultUri	URI хранилища, используемого клиентом. Отображается как DNS-имя на портале Azure.

Client проверка состояния интеграции

По умолчанию в интеграциях клиентов .NET.NET Aspire проверки работоспособности включены для всех служб. Аналогичным образом, многие .NET.NET Aspireхостинговые интеграции также включают в себя конечные точки проверки работоспособности. Дополнительные сведения см. в следующем разделе:

.NET проверки работоспособности приложения на C#
проверка состояния в ASP.NET Core

Интеграция .NET AspireAzure Key Vault включает следующие проверки работоспособности:

Добавляет проверку работоспособности AzureKeyVaultSecretsHealthCheck, которая пытается подключиться к Key Vault и выполнить его запрос.
Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные проверки работоспособности должны пройти, чтобы приложение считалось готовым к приему трафика.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации ведения журналов, трассировки и метрики, которые иногда называются основами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция .NET AspireAzure Key Vault использует следующие категории журналов:

Azure.Core
Azure.Identity

Отслеживание

Интеграция .NET AspireAzure Key Vault будет выполнять следующие операции трассировки с помощью OpenTelemetry:

Azure.Security.KeyVault.Secrets.SecretClient

Метрика

Интеграция .NET AspireAzure Key Vault в настоящее время не поддерживает метрики по умолчанию из-за ограничений пакета SDK Azure.

См. также

Azure Key Vault документы
Видео : общие сведения о Azure Key Vault и .NET Aspire
Обзор интеграции
Обзор интеграции
.NET Aspire GitHub репо

Поделиться через

интеграция .NET AspireAzure Key Vault

Хостинг-интеграция

Добавьте ресурс Azure Key Vault

Созданный автоматически процессом Bicep

Настройка инфраструктуры подготовки

Подключение к существующему экземпляру Azure Key Vault

интеграция Client

Добавление секретов в конфигурацию

Получите экземпляр IConfiguration

Получите экземпляр IOptions<T>

Добавить секретного клиента Azure

Добавить клиента с ключом Azure Key Vault

Конфигурация

Использование поставщиков конфигураций

Использование встроенных делегатов

Параметры конфигурации

Client проверка состояния интеграции

Наблюдаемость и телеметрия

Лесозаготовка

Отслеживание

Метрика

См. также

Обратная связь

Дополнительные ресурсы

Получите экземпляр `IConfiguration`

Получите экземпляр `IOptions<T>`