通过

.NET Aspire Azure 人工智能搜索文档集成

  • 项目

在本文中，您将学习如何使用 .NET AspireAzure AI 搜索文档 client。 Aspire.Azure.Search.Documents 库用于在依赖注入（DI）容器中注册 SearchIndexClient，以便连接到 Azure 搜索。 它启用相应的运行状况检查和日志记录。

有关使用 SearchIndexClient的更多信息，请参阅 如何使用 Azure。搜索文档在 C# .NET 应用程序中。

入门

若要开始使用 .NET AspireAzure AI 搜索文档集成，请安装 📦Aspire。Azure。search.Documentsclient-consuming 项目中的 NuGet 包，即使用 Azure AI 搜索文档 client的应用程序的项目。

dotnet add package Aspire.Azure.Search.Documents

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

示例用法

在 client使用项目的 Program.cs 文件中，调用扩展方法注册 SearchIndexClient，以便通过依赖项注入容器使用。 AddAzureSearchClient 方法采用连接名称参数。

builder.AddAzureSearchClient("searchConnectionName");

然后，可以使用依赖项注入检索 SearchIndexClient 实例。 例如，若要从一个示例服务中检索 client，

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

还可以通过调用 SearchIndexClient.GetSearchClient 方法检索可用于查询的 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 搜索 client 库，.NET 获取有关使用 SearchIndexClient的示例。

应用主机使用情况

若要将 Azure AI 托管支持添加到 IDistributedApplicationBuilder，请在 应用主机 项目中安装 📦Aspire.Hosting.Azure.Search NuGet 包。

dotnet add package Aspire.Hosting.Azure.Search

在 AppHost的 Program.cs 文件中，添加 Azure 搜索服务，并使用以下方法使用连接：

var builder = DistributedApplication.CreateBuilder(args);

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

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(search);

AddAzureSearch 方法将从 AppHost 的配置（例如，从 ConnectionStrings:search 配置密钥下的“用户机密”读取连接信息。 WithReference 方法将该连接信息传递到 MyService 项目中名为 search 的连接字符串中。 在 MyServiceProgram.cs 文件中，可以使用以下命令使用连接：

builder.AddAzureSearch("search");

配置

.NET Aspire Azure Azure 搜索库提供了多个选项，用于根据项目的要求和约定配置 Azure 搜索服务。 请注意，需要提供 Endpoint 或 ConnectionString 中的任一项。

使用连接字符串

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

builder.AddAzureSearch("searchConnectionName");

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

帐户终结点

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

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

连接字符串

或者，可以使用自定义连接字符串。

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

使用配置提供程序

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

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

使用内联委托

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

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

还可以通过 AddAzureSearch 方法的可选 Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder 参数来设置 SearchClientOptions。 例如，设置此 client的 client ID：

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

健康检查

默认情况下，.NET.NET Aspire 集成为所有服务启用 健康检查。 有关详细信息，请参阅 .NET.NET Aspire 集成概述。

.NET Aspire Azure AI 搜索文档集成通过调用 SearchIndexClient 上的 GetServiceStatisticsAsync 方法来进行单次运行状况检查，以验证服务的可用性。

可观测性和遥测

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

伐木

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

  • Azure
  • Azure.Core
  • Azure.Identity

另请参阅