.NET Aspire Azure AI 搜索集成

项目
03/10/2025

包括： 托管集成和 Client 集成

借助 .NET AspireAzure AI 搜索文档集成，您可以将 .NET 应用程序连接到 Azure AI 搜索（原称 Azure 认知搜索）服务。 Azure AI 搜索是一个企业级的信息检索系统，适用于你引入搜索引擎索引的多样化内容，通过查询和应用向用户呈现。它配备了一整套先进的搜索技术，专为各种规模的高性能应用程序而打造。

托管集成

托管集成 .NET AspireAzure AI 搜索将 Azure AI 搜索资源建模为 AzureSearchResource 类型。若要访问此类型和 API 以在应用主机项目中使用它们，请安装 📦Aspire.Hosting.Azure.Search NuGet 包：

.NET 命令行界面 (CLI)
PackageReference

dotnet add package Aspire.Hosting.Azure.Search

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

有关详细信息，请参阅 dotnet add package 或在 .NET 应用程序中管理包依赖项。

添加 Azure AI 搜索资源

若要将 AzureSearchResource 添加到应用主机项目，请调用提供名称的 AddAzureSearch 方法：

var builder = DistributedApplication.CreateBuilder(args);

var search = builder.AddAzureSearch("search");

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

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

前面的代码将名为 search 的 Azure AI 搜索资源添加到应用主机项目中。 WithReference 方法将连接信息传递给 ExampleProject 项目。

重要

调用 AddAzureSearch时，它会隐式调用 AddAzureProvisioning(IDistributedApplicationBuilder)，这增加了在应用启动期间动态生成 Azure 资源的支持。应用程序必须配置相应的订阅和位置。有关详细信息，请参阅本地预配：配置

生成的配置脚本 Bicep

如果你不熟悉 Bicep，它是一种领域专用语言，用于定义 Azure 资源。使用 .NET.NET Aspire时，无需手动编写 Bicep;相反，预配 API 会为你生成 Bicep。发布应用时，生成的 Bicep 文件将会与清单文件一同输出。添加 Azure AI 搜索资源时，会生成 Bicep，以便使用适当的默认值预配搜索服务。

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

param principalType string

param principalId string

resource search 'Microsoft.Search/searchServices@2023-11-01' = {
  name: take('search-${uniqueString(resourceGroup().id)}', 60)
  location: location
  properties: {
    hostingMode: 'default'
    disableLocalAuth: true
    partitionCount: 1
    replicaCount: 1
  }
  sku: {
    name: 'basic'
  }
  tags: {
    'aspire-resource-name': 'search'
  }
}

resource search_SearchIndexDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7')
    principalType: principalType
  }
  scope: search
}

resource search_SearchServiceContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0')
    principalType: principalType
  }
  scope: search
}

output connectionString string = 'Endpoint=https://${search.name}.search.windows.net'

前面的 Bicep 是一个模块，它使用以下默认值预配 Azure AI 搜索服务资源：

location：资源组的位置参数，默认为 resourceGroup().location。
principalType：Azure AI 搜索资源的主体类型参数。
principalId：Azure AI 搜索资源的主体 ID 参数。
search：表示 Azure AI 搜索服务的资源。
- properties：Azure AI 搜索服务的属性：
  - hostingMode：设置为 default。
  - disableLocalAuth：设置为 true。
  - partitionCount：设置为 1。
  - replicaCount：设置为 1。
- sku：默认值为 basic。
search_SearchIndexDataContributor：Azure AI 搜索索引数据参与者角色的分配。有关更多信息，请参见搜索索引数据贡献者。
search_SearchServiceContributor：Azure AI 搜索服务参与者角色的角色分配。有关更多信息，请参阅搜索服务参与者。
connectionString：用于连接 Azure AI 搜索服务的连接字符串。连接字符串是使用 Azure AI 搜索服务的 Endpoint 属性生成的。

生成的 Bicep 是一个起始点，可以根据您的具体需求进行自定义。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。此类型提供了一种流畅的 API，可以通过 Azure API 来配置 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) 资源，从而实现对生成的 Bicep 的自定义。例如，可以配置搜索服务分区、副本等：

builder.AddAzureSearch("search")
    .ConfigureInfrastructure(infra =>
    {
        var searchService = infra.GetProvisionableResources()
                                 .OfType<SearchService>()
                                 .Single();

        searchService.PartitionCount = 6;
        searchService.ReplicaCount = 3;
        searchService.SearchSkuName = SearchServiceSkuName.Standard3;
        searchService.Tags.Add("ExampleKey", "Example value");
    });

前面的代码：

将一个调用链接至 ConfigureInfrastructure API：
- infra 参数是 AzureResourceInfrastructure 类型的实例。
- 通过调用 GetProvisionableResources() 方法检索可预配资源。
- 检索单个 SearchService 资源。
  - SearchService.PartitionCount 设置为 6。
  - SearchService.ReplicaCount 设置为 3。
  - SearchService.SearchSkuName 设置为 SearchServiceSkuName.Standard3。
  - 在认知服务资源上添加了一个标记，键为 ExampleKey，值为 Example value。

还有更多配置选项可用于自定义 Azure AI 搜索资源。有关详细信息，请参阅 Azure.Provisioning 自定义设置。

连接到现有的 Azure AI 搜索服务

你可能有一个现有的Azure AI 搜索服务，你想要连接到它。可以将调用链用于标注 AzureSearchResource 是现有资源：

var builder = DistributedApplication.CreateBuilder(args);

var existingSearchName = builder.AddParameter("existingSearchName");
var existingSearchResourceGroup = builder.AddParameter("existingSearchResourceGroup");

var search = builder.AddAzureSearch("search")
                    .AsExisting(existingSearchName, existingSearchResourceGroup);

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

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

有关将 Azure AI 搜索资源视为现有资源的详细信息，请参阅使用现有 Azure 资源。

或者，可以向应用主机添加连接字符串，而不是表示 Azure AI 搜索资源。这是一种仅依赖于 string 值的弱类型化方法。若要将连接添加到现有 Azure AI 搜索服务，请调用 AddConnectionString 方法：

var builder = DistributedApplication.CreateBuilder(args);

var search = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureSearch("search")
    : builder.AddConnectionString("search");

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

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

注释

连接字符串用于表示各种连接信息，包括数据库连接、消息代理、终结点 URI 和其他服务。在 .NET.NET Aspire 名词中，术语“连接字符串”用于表示任何类型的连接信息。

连接字符串在应用主机的配置（通常位于用户机密）的 ConnectionStrings 部分下进行配置：

{
  "ConnectionStrings": {
    "search": "https://{account_name}.search.azure.com/"
  }
}

有关详细信息，请参阅 Azure添加现有资源。

托管环境集成运行状况检查

Azure AI 搜索托管集成目前未实现任何健康检查。将来的版本可能会更改此限制。与往常一样，如果有任何建议或反馈，请随时提出问题。

Client 集成

若要开始使用 .NET AspireAzure AI 搜索文档客户端集成，请在客户端使用的项目中安装 📦Aspire.Azure.Search.Documents NuGet 包，即指使用 Azure AI 搜索文档客户端的应用程序项目。

.NET 命令行界面 (CLI)
PackageReference

dotnet add package Aspire.Azure.Search.Documents

<PackageReference Include="Aspire.Azure.Search.Documents"
                  Version="*" />

添加 Azure AI 搜索索引客户端

在您的客户端消费项目中的 Program.cs 文件中，对任何 AddAzureSearchClient 调用 IHostApplicationBuilder 扩展方法，以注册 SearchIndexClient，以便通过依赖注入容器进行使用。该方法采用连接名称参数。

builder.AddAzureSearchClient(connectionName: "search");

小提示

connectionName 参数必须与在应用主机项目中添加 Azure AI 搜索资源时使用的名称匹配。有关详细信息，请参阅添加 Azure AI 搜索资源。

添加 SearchIndexClient后，可以使用依赖项注入检索客户端实例。例如，若要从示例服务检索客户端实例：

public class ExampleService(SearchIndexClient indexClient)
{
    // Use indexClient
}

您还可以通过调用 GetSearchClient(String) 方法来检索 SearchClient，它可用于查询：

public class ExampleService(SearchIndexClient indexClient)
{
    public async Task<long> GetDocumentCountAsync(
        string indexName,
        CancellationToken cancellationToken)
    {
        var searchClient = indexClient.GetSearchClient(indexName);

        var documentCountResponse = await searchClient.GetDocumentCountAsync(
            cancellationToken);

        return documentCountResponse.Value;
    }
}

有关详细信息，请参阅：

Azure AI 搜索客户端库，用于 .NET示例，使用 SearchIndexClient。
请参阅 .NET中的依赖项注入以获取有关依赖项注入的详细信息。

添加已配置键 Azure 的 AI 搜索索引客户端

在某些情况下，可能需要使用不同的连接名称注册多个 SearchIndexClient 实例。若要注册密钥 Azure AI 搜索客户端，请调用 AddKeyedAzureSearchClient 方法：

builder.AddKeyedAzureSearchClient(name: "images");
builder.AddKeyedAzureSearchClient(name: "documents");

重要

使用键式服务时，预期 Azure AI 搜索资源配置了两个命名连接，一个用于 images，一个用于 documents。

然后，可以使用依赖项注入检索客户端实例。例如，若要从服务检索客户：

public class ExampleService(
    [KeyedService("images")] SearchIndexClient imagesClient,
    [KeyedService("documents")] SearchIndexClient documentsClient)
{
    // Use clients...
}

有关详细信息，请参阅 .NET中的键服务。

配置

.NET Aspire Azure AI 搜索文档库提供了多个选项，用于根据项目的要求和约定配置 Azure AI 搜索连接。必须提供 Endpoint 或 ConnectionString。

使用连接字符串

可以从 密钥和终结点 选项卡中使用格式 Endpoint={endpoint};Key={key};构造连接。调用 builder.AddAzureSearchClient()时，可以提供连接字符串的名称：

builder.AddAzureSearchClient("searchConnectionName");

从 ConnectionStrings 配置部分检索连接字符串。支持两种连接格式：

帐户终结点

建议的方法是使用 Endpoint，它与 AzureSearchSettings.Credential 属性配合使用以建立连接。如果未配置凭据，则使用 DefaultAzureCredential。

{
  "ConnectionStrings": {
    "search": "https://{search_service}.search.windows.net/"
  }
}

连接字符串

或者，可以使用具有密钥的连接字符串;不建议采用以下方法：

{
  "ConnectionStrings": {
    "search": "Endpoint=https://{search_service}.search.windows.net/;Key={account_key};"
  }
}

使用配置提供程序

.NET Aspire Azure AI 搜索库支持 Microsoft.Extensions.Configuration。它通过 AzureSearchSettings 键从配置中加载 SearchClientOptions 和 Aspire:Azure:Search:Documents。配置某些选项的示例 appsettings.json：

{
  "Aspire": {
    "Azure": {
      "Search": {
        "Documents": {
          "DisableTracing": false
        }
      }
    }
  }
}

有关完整的 Azure AI 搜索文档客户端集成 JSON 架构，请参阅 Aspire。Azure。Search.Documents/ConfigurationSchema.json。

使用内联委托

您还可以传递 Action<AzureSearchSettings> configureSettings 委托来设置一些或所有内联选项，例如从代码中禁用跟踪：

builder.AddAzureSearchClient(
    "searchConnectionName",
    static settings => settings.DisableTracing = true);

还可以使用 SearchClientOptions 方法的可选 Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder 参数来设置 AddAzureSearchClient。例如，若要设置此客户端的客户端 ID：

builder.AddAzureSearchClient(
    "searchConnectionName",
    configureClientBuilder: builder => builder.ConfigureOptions(
        static options => options.Diagnostics.ApplicationId = "CLIENT_ID"));

Client 整合健康检查

默认情况下，所有服务的.NET.NET Aspire客户端集成都启用了状态检查。同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。有关详细信息，请参阅：

在 C# 中的应用程序健康检查
运行状况检查在 ASP.NET Core 中

.NET Aspire Azure AI 文档搜索集成实现了一个单一的健康检查，该检查通过调用 SearchIndexClient 上的 GetServiceStatisticsAsync 方法来验证服务是否可用。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Azure AI 搜索文档集成使用以下日志类别：

Azure
Azure.Core
Azure.Identity

追踪

.NET Aspire Azure AI 搜索文档集成在与搜索服务交互时使用 OpenTelemetry 发出跟踪活动。

通过