在 .NET Aspire 中集成 Azure AI SearchAspire.Azure.Search.Documents 组件完整指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本文以 Aspire.Azure.Search.Documents 组件文档 为核心系统讲解如何在 .NET Aspire 应用中注册与使用 Azure AI Search原 Azure Cognitive Search的SearchIndexClient客户端覆盖安装、依赖注入、连接配置、AppHost 编排以及日志与遥测开箱即用的能力。读完本文你将掌握从零搭建AppHost 编排 业务项目消费的完整 Azure AI Search 集成方案并理解其底层配置解析与客户端工厂的实现原理。组件定位为 Azure AI Search 提供 DI 化的一等公民接入Aspire.Azure.Search.Documents是 .NET Aspire 的 Azure 云组件之一。它的核心职责在 AspireAzureSearchExtensions.cs 的类注释中写得很明确将SearchIndexClient以**单例singleton**形式注册到IHostApplicationBuilder的服务集合中用于连接 Azure AI Search并自动启用对应的日志logging与遥测telemetry。也就是说你无需再手动编写new SearchIndexClient(...)的样板代码也无需自行搭接日志与 OpenTelemetry 管道。组件在注册客户端的同时把 Azure SDK 的日志、追踪tracing和健康检查能力全部接入 Aspire 的统一体系中让搜索服务成为应用可观测的一部分。该组件的项目文件 Aspire.Azure.Search.Documents.csproj 显示它直接引用 Azure 官方 SDKAzure.Search.Documents以及Microsoft.Extensions.Azure、Microsoft.Extensions.Configuration.Binder、Microsoft.Extensions.Diagnostics.HealthChecks、OpenTelemetry.Extensions.Hosting等基础设施包这正是它能零胶水接入 DI、配置与可观测性的技术基础。快速开始安装与前置条件前置条件在开始前需要准备两项 Azure 资源Azure 订阅可通过 Azure 门户免费创建。Azure AI Search 服务在 Azure 门户中创建 Search Service 资源创建后会得到一个形如https://{search_service}.search.windows.net的端点以及对应的密钥Key或可用的 Microsoft Entra 凭据。安装组件包在目标项目通常是业务服务项目而非 AppHost 项目中通过 NuGet 安装dotnet add package Aspire.Azure.Search.Documents安装完成后即可调用组件提供的扩展方法完成客户端注册。基本用法注册客户端并通过 DI 消费注册 SearchIndexClient在业务项目如 Web API的Program.cs中调用AddAzureSearchClient扩展方法将SearchIndexClient注册进依赖注入容器。该方法需要一个**连接名称connection name**参数用于从配置的ConnectionStrings节中检索连接信息builder.AddAzureSearchClient(searchConnectionName);AddAzureSearchClient的完整签名见 AspireAzureSearchExtensions.cs为public static void AddAzureSearchClient( this IHostApplicationBuilder builder, string connectionName, ActionAzureSearchSettings? configureSettings null, ActionIAzureClientBuilderSearchIndexClient, SearchClientOptions? configureClientBuilder null)两个可选委托参数分别用于内联调整AzureSearchSettings组件级设置和SearchClientOptionsAzure SDK 客户端级设置下文会详细展开。通过依赖注入获取客户端注册完成后你可以在任意被 DI 管理的类型中直接注入SearchIndexClient。例如在 Web API 控制器中private readonly SearchIndexClient _indexClient; public SearchController(SearchIndexClient indexClient) { _indexClient indexClient; }获取 SearchClient 执行查询SearchIndexClient是索引管理与元数据操作入口真正执行文档查询需要使用SearchClient。通过SearchIndexClient.GetSearchClient(string indexName)即可获得针对指定索引的查询客户端private readonly SearchIndexClient _indexClient; public SearchController(SearchIndexClient indexClient) { _indexClient indexClient; } public async Tasklong GetDocumentCountAsync(string indexName, CancellationToken cancellationToken) { var searchClient _indexClient.GetSearchClient(indexName); var documentCountResponse await searchClient.GetDocumentCountAsync(cancellationToken); return documentCountResponse.Value; }这里GetDocumentCountAsync只是查询能力的一个示例。SearchClient还支持索引文档的增删改查、搜索SearchAsync、建议suggestions等操作具体用法可参考 Azure AI Search 的 .NET 客户端库文档。配置详解三种方式覆盖不同场景组件支持多种配置途径可按项目约定灵活选用。注意无论采用哪种方式Endpoint与ConnectionString二者必须提供其一否则组件无法构建客户端。方式一使用连接字符串ConnectionStrings连接字符串可从 Azure 门户的Keys and Endpoint页签获取格式为Endpoint{endpoint};Key{key};。在调用AddAzureSearchClient时传入连接名称builder.AddAzureSearchClient(searchConnectionName);组件会从配置的ConnectionStrings节中取出该名称对应的值。支持两种连接字符串格式1. 纯 Endpoint 格式推荐只配置端点地址配合AzureSearchSettings.Credential默认基于当前环境自动创建的TokenCredential完成身份认证{ ConnectionStrings: { searchConnectionName: https://{search_service}.search.windows.net/ } }该方式是官方推荐做法。当未显式配置任何凭据时组件会通过AzureCredentialHelper.CreateDefaultAzureCredential()创建默认凭据见 AspireAzureSearchExtensions.cs它会按标准顺序尝试环境变量、托管标识等多种 Azure 凭据来源。2. 完整连接字符串格式直接携带访问密钥{ ConnectionStrings: { searchConnectionName: Endpointhttps://{search_service}.search.windows.net/;Key{account_key}; } }从源码角度看这两种格式的解析逻辑实现在 AzureSearchSettings.cs 的ParseConnectionString方法中若连接字符串整体能被解析为绝对 URI则直接将其作为Endpoint否则按键值对解析读取Endpoint得到Endpoint属性读取Key得到Key属性。方式二使用配置提供者Microsoft.Extensions.Configuration组件支持标准 .NET 配置系统从Aspire:Azure:Search:Documents配置节加载AzureSearchSettings和SearchClientOptions。示例appsettings.json{ Aspire: { Azure: { Search: { Documents: { DisableTracing: false } } } } }该配置节名在源码中定义为常量DefaultConfigSectionName Aspire:Azure:Search:Documents。组件的 ConfigurationSchema.json 完整定义了这一节支持的全部属性核心包括配置项类型说明默认值Endpointstring (uri)Azure AI Search 端点形如https://{search_service}.search.windows.net无Keystring用于认证的访问密钥配置后优先使用AzureKeyCredential无DisableTracingboolean是否禁用 OpenTelemetry 追踪falseDisableHealthChecksboolean是否禁用健康检查falseClientOptions.Retryobject客户端重试策略ModeFixed/Exponential、MaxRetries、Delay、MaxDelay、NetworkTimeoutSDK 默认ClientOptions.Diagnosticsobject诊断选项ApplicationId、DefaultApplicationId、IsDistributedTracingEnabled、IsLoggingEnabled、IsLoggingContentEnabled、LoggedContentSizeLimit默认 4096 字节、LoggedHeaderNames、LoggedQueryParameters等SDK 默认其中Endpoint与Key也可以通过配置节直接提供而不必走ConnectionStrings与内联委托方式等效。方式三使用内联委托Inline DelegatesAddAzureSearchClient的两个可选参数提供了纯代码配置的途径。调整AzureSearchSettings例如从代码中禁用追踪builder.AddAzureSearchClient(searchConnectionName, settings settings.DisableTracing true);调整SearchClientOptions通过configureClientBuilder参数操作IAzureClientBuilderSearchIndexClient, SearchClientOptions例如为客户端设置 User-Agent 中的应用 ID用于在 Azure 端区分请求来源builder.AddAzureSearchClient(searchConnectionName, configureClientBuilder: builder builder.ConfigureOptions(options options.Diagnostics.ApplicationId CLIENT_ID));configureSettings委托在设置从配置读取完成后被调用见 AspireAzureSearchExtensions.cs因此它既可以修改配置节带来的值也可以补充配置节未覆盖的设置两者可自由组合。多实例场景AddKeyedAzureSearchClient除了单例注册组件还提供了键控keyed注册能力AddKeyedAzureSearchClient(string name, ...)允许在同一应用中同时连接多个 Azure AI Search 服务builder.AddKeyedAzureSearchClient(search1); builder.AddKeyedAzureSearchClient(search2);键控客户端从Aspire:Azure:Search:Documents:{name}配置节读取设置并以name作为服务键ServiceKey注入消费时使用GetRequiredKeyedServiceSearchIndexClient(search1)获取。这一点在测试 AspireAzureSearchExtensionsTests.cs 的CanAddMultipleKeyedServices用例中有明确验证三个连接分别注册后search2与search3得到的是两个指向不同端点的独立客户端实例。AppHost 编排在分布式应用中管理 Search 服务以上是业务项目消费端的接入方式。在 Aspire 的完整开发模型中通常还需要在AppHost 项目中通过托管Hosting集成来编排 Azure AI Search 资源。这需要安装托管库dotnet add package Aspire.Hosting.Azure.Search然后在 AppHost 的_AppHost.cs_中按是否发布模式区分资源的建模方式var search builder.ExecutionContext.IsPublishMode ? builder.AddAzureSearch(search) : builder.AddConnectionString(search); var myService builder.AddProjectProjects.MyService() .WithReference(search);这段代码表达了两种模式发布模式Publish ModeAddAzureSearch(search)向应用模型中添加一个真实的 Azure AI Search 资源部署时由 Azure Provisioning 自动在订阅中创建。本地开发模式AddConnectionString(search)从 AppHost 自身配置例如 user secrets的ConnectionStrings:search键读取连接信息方便开发者直接连接既有搜索服务而无需真正部署 Azure 资源。WithReference(search)将连接信息以名为search的连接字符串注入MyService项目。于是业务项目中只需一句builder.AddAzureSearchClient(search);即可完成消费端接入AppHost 与业务项目通过约定好的连接名称天然对齐。托管集成的默认行为与角色分配从 AzureSearchExtensions.cs 的实现可以看到AddAzureSearch的默认行为新建的SearchService资源采用Basic SKUReplicaCount 1、PartitionCount 1、默认托管模式HostingMode.Default并默认禁用本地认证IsLocalAuthDisabled true——这正与消费端优先使用 Entra 凭据、Endpoint 连接的推荐方式相呼应默认给引用该资源的项目分配两个内置角色SearchIndexDataContributor与SearchServiceContributor分别覆盖数据面与控制面权限输出connectionString、endpoint、name、id四个 Provisioning 输出供后续角色分配与私有端点private endpoint场景使用若资源带有私有端点注解还会自动禁用公网访问PublicNetworkAccess.Disabled。如需自定义角色可用WithRoleAssignments替换默认角色分配例如只授予只读数据权限var search builder.AddAzureSearch(search); var api builder.AddProjectProjects.Api(api) .WithRoleAssignments(search, SearchBuiltInRole.SearchIndexDataReader) .WithReference(search);角色定义集中在 AzureSearchRole.cs支持SearchIndexDataContributor、SearchIndexDataReader、SearchServiceContributor三种。该托管集成更详细的使用说明见 Aspire.Hosting.Azure.Search 文档其中还包含 TypeScript AppHostbuilder.addAzureSearch(search)的等价写法。客户端工厂与认证逻辑底层原理剖析理解SearchIndexClient究竟如何被构建有助于排查连接问题。组件的核心逻辑在 AspireAzureSearchExtensions.cs 的AddClient工厂方法中return azureFactoryBuilder.AddClientSearchIndexClient, SearchClientOptions((options, _, _) { if (settings.Endpoint is null) { throw new InvalidOperationException( $A SearchIndexClient could not be configured. Ensure valid connection information was provided in ConnectionStrings:{connectionName} or specify an {nameof(AzureSearchSettings.Endpoint)} in the {configurationSectionName} configuration section.); } if (!string.IsNullOrWhiteSpace(settings.Key)) { return new SearchIndexClient(settings.Endpoint, new AzureKeyCredential(settings.Key), options); } else { return new SearchIndexClient(settings.Endpoint, settings.Credential ?? AzureCredentialHelper.CreateDefaultAzureCredential(), options); } });由此可以得到三条明确的认证规则Endpoint为 null 时直接抛出InvalidOperationException提示信息会明确指向ConnectionStrings:{connectionName}或配置节Aspire:Azure:Search:Documents方便快速定位配置缺失配置了Key时优先使用AzureKeyCredential共享密钥认证未配置Key时使用settings.Credential若也未设置则回退到默认 Azure 凭据链AzureCredentialHelper.CreateDefaultAzureCredential()即 Entra/托管标识认证。此外AzureSearchSettings的Credential属性还通过GetTokenCredential供组件内部其他环节如角色分配场景复用。可观测性与健康检查开箱即用的运维能力该组件之所以开箱即用体现在它对 Aspire 三大可观测支柱的默认接入见 AspireAzureSearchExtensions.cs日志Logging基于Azure.Core的 HTTP 管道日志。通过SearchClientOptions.Diagnostics系列选项可控制日志粒度例如IsLoggingEnabled、IsLoggingContentEnabled默认最多记录 4096 字节请求/响应体、LoggedHeaderNames、LoggedQueryParameters等。日志分类器涵盖Azure、Azure-Search-Documents、Azure.Core、Azure.Identity等可在日志配置中按需调整级别见 ConfigurationSchema.json。追踪Tracing组件将 Activity 源ActivitySource声明为Azure.Search.Documents.*使 Azure SDK 发出的分布式追踪活动System.Diagnostics.Activity自动流入 Aspire 的 OpenTelemetry 管道。默认开启可通过DisableTracing关闭builder.AddAzureSearchClient(searchConnectionName, settings settings.DisableTracing true);健康检查Health Checks组件默认注册一个基于SearchIndexClient的健康检查实现见 AzureSearchIndexHealthCheck.cs通过调用GetServiceStatisticsAsync探测搜索服务的连通性成功返回Healthy失败则返回携带描述信息Failed to connect to Azure AI Search service.的Unhealthy状态。健康检查的名称在 AspireAzureSearchExtensionsTests.cs 中有明确约定普通注册为Azure_SearchIndexClient键控注册为Azure_SearchIndexClient_{name}。测试用例AddAzureSearchClient_HealthCheckReportsConnectionFailureDescription验证了连接不可达时健康检查会正确报告Unhealthy与失败原因。可通过DisableHealthChecks关闭健康检查{ Aspire: { Azure: { Search: { Documents: { DisableHealthChecks: true } } } } }指标Metrics需要特别说明的是与多数 Azure 组件不同该组件目前不启用客户端指标——源码中GetMetricsEnabled固定返回false。也就是说开箱即用的是日志、追踪与健康检查三件套指标维度需要依赖其他监控渠道。测试验证组件行为的代码级证据仓库中的 Aspire.Azure.Search.Documents.Tests 测试项目从多个维度固化了组件行为可作为你集成时的行为参照ReadsFromConnectionStringsCorrectly验证ConnectionStrings:search中的Endpoint...;Key...连接字符串能被正确解析并反映到客户端Endpoint上测试代码ConnectionStringCanBeSetInCode验证通过configureSettings委托在代码中直接指定Endpoint与Key同样可行CanAddMultipleKeyedServices验证键控注册支持同一进程内多搜索服务并存AddAzureSearchClient_HealthCheckReportsConnectionFailureDescription验证不可达端点下健康检查报告Unhealthy及对应描述信息。这些用例与上文配置解析多实例健康检查三节一一对应是理解组件契约的官方行为基准。小结与扩展阅读综上Aspire.Azure.Search.Documents组件提供了从AppHost 资源编排到业务项目客户端注册的完整链路业务侧一行AddAzureSearchClient(name)完成单例注册与可观测性接入托管侧AddAzureSearchWithReference完成资源的建模、部署与连接传递。三条配置通道ConnectionStrings、配置提供者、内联委托按项目约定自由组合键控注册则服务于多搜索服务的复杂场景。如需进一步深入可在仓库中继续阅读组件入口与工厂实现AspireAzureSearchExtensions.cs设置模型与连接字符串解析AzureSearchSettings.cs完整配置 SchemaConfigurationSchema.json托管集成使用说明Aspire.Hosting.Azure.Search/README.md托管集成实现AzureSearchExtensions.cs组件行为测试AspireAzureSearchExtensionsTests.cs各 Aspire 组件总览src/Components 目录【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 .NET Aspire 中集成 Azure AI Search：Aspire.Azure.Search.Documents 组件完整指南
在 .NET Aspire 中集成 Azure AI SearchAspire.Azure.Search.Documents 组件完整指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本文以 Aspire.Azure.Search.Documents 组件文档 为核心系统讲解如何在 .NET Aspire 应用中注册与使用 Azure AI Search原 Azure Cognitive Search的SearchIndexClient客户端覆盖安装、依赖注入、连接配置、AppHost 编排以及日志与遥测开箱即用的能力。读完本文你将掌握从零搭建AppHost 编排 业务项目消费的完整 Azure AI Search 集成方案并理解其底层配置解析与客户端工厂的实现原理。组件定位为 Azure AI Search 提供 DI 化的一等公民接入Aspire.Azure.Search.Documents是 .NET Aspire 的 Azure 云组件之一。它的核心职责在 AspireAzureSearchExtensions.cs 的类注释中写得很明确将SearchIndexClient以**单例singleton**形式注册到IHostApplicationBuilder的服务集合中用于连接 Azure AI Search并自动启用对应的日志logging与遥测telemetry。也就是说你无需再手动编写new SearchIndexClient(...)的样板代码也无需自行搭接日志与 OpenTelemetry 管道。组件在注册客户端的同时把 Azure SDK 的日志、追踪tracing和健康检查能力全部接入 Aspire 的统一体系中让搜索服务成为应用可观测的一部分。该组件的项目文件 Aspire.Azure.Search.Documents.csproj 显示它直接引用 Azure 官方 SDKAzure.Search.Documents以及Microsoft.Extensions.Azure、Microsoft.Extensions.Configuration.Binder、Microsoft.Extensions.Diagnostics.HealthChecks、OpenTelemetry.Extensions.Hosting等基础设施包这正是它能零胶水接入 DI、配置与可观测性的技术基础。快速开始安装与前置条件前置条件在开始前需要准备两项 Azure 资源Azure 订阅可通过 Azure 门户免费创建。Azure AI Search 服务在 Azure 门户中创建 Search Service 资源创建后会得到一个形如https://{search_service}.search.windows.net的端点以及对应的密钥Key或可用的 Microsoft Entra 凭据。安装组件包在目标项目通常是业务服务项目而非 AppHost 项目中通过 NuGet 安装dotnet add package Aspire.Azure.Search.Documents安装完成后即可调用组件提供的扩展方法完成客户端注册。基本用法注册客户端并通过 DI 消费注册 SearchIndexClient在业务项目如 Web API的Program.cs中调用AddAzureSearchClient扩展方法将SearchIndexClient注册进依赖注入容器。该方法需要一个**连接名称connection name**参数用于从配置的ConnectionStrings节中检索连接信息builder.AddAzureSearchClient(searchConnectionName);AddAzureSearchClient的完整签名见 AspireAzureSearchExtensions.cs为public static void AddAzureSearchClient( this IHostApplicationBuilder builder, string connectionName, ActionAzureSearchSettings? configureSettings null, ActionIAzureClientBuilderSearchIndexClient, SearchClientOptions? configureClientBuilder null)两个可选委托参数分别用于内联调整AzureSearchSettings组件级设置和SearchClientOptionsAzure SDK 客户端级设置下文会详细展开。通过依赖注入获取客户端注册完成后你可以在任意被 DI 管理的类型中直接注入SearchIndexClient。例如在 Web API 控制器中private readonly SearchIndexClient _indexClient; public SearchController(SearchIndexClient indexClient) { _indexClient indexClient; }获取 SearchClient 执行查询SearchIndexClient是索引管理与元数据操作入口真正执行文档查询需要使用SearchClient。通过SearchIndexClient.GetSearchClient(string indexName)即可获得针对指定索引的查询客户端private readonly SearchIndexClient _indexClient; public SearchController(SearchIndexClient indexClient) { _indexClient indexClient; } public async Tasklong GetDocumentCountAsync(string indexName, CancellationToken cancellationToken) { var searchClient _indexClient.GetSearchClient(indexName); var documentCountResponse await searchClient.GetDocumentCountAsync(cancellationToken); return documentCountResponse.Value; }这里GetDocumentCountAsync只是查询能力的一个示例。SearchClient还支持索引文档的增删改查、搜索SearchAsync、建议suggestions等操作具体用法可参考 Azure AI Search 的 .NET 客户端库文档。配置详解三种方式覆盖不同场景组件支持多种配置途径可按项目约定灵活选用。注意无论采用哪种方式Endpoint与ConnectionString二者必须提供其一否则组件无法构建客户端。方式一使用连接字符串ConnectionStrings连接字符串可从 Azure 门户的Keys and Endpoint页签获取格式为Endpoint{endpoint};Key{key};。在调用AddAzureSearchClient时传入连接名称builder.AddAzureSearchClient(searchConnectionName);组件会从配置的ConnectionStrings节中取出该名称对应的值。支持两种连接字符串格式1. 纯 Endpoint 格式推荐只配置端点地址配合AzureSearchSettings.Credential默认基于当前环境自动创建的TokenCredential完成身份认证{ ConnectionStrings: { searchConnectionName: https://{search_service}.search.windows.net/ } }该方式是官方推荐做法。当未显式配置任何凭据时组件会通过AzureCredentialHelper.CreateDefaultAzureCredential()创建默认凭据见 AspireAzureSearchExtensions.cs它会按标准顺序尝试环境变量、托管标识等多种 Azure 凭据来源。2. 完整连接字符串格式直接携带访问密钥{ ConnectionStrings: { searchConnectionName: Endpointhttps://{search_service}.search.windows.net/;Key{account_key}; } }从源码角度看这两种格式的解析逻辑实现在 AzureSearchSettings.cs 的ParseConnectionString方法中若连接字符串整体能被解析为绝对 URI则直接将其作为Endpoint否则按键值对解析读取Endpoint得到Endpoint属性读取Key得到Key属性。方式二使用配置提供者Microsoft.Extensions.Configuration组件支持标准 .NET 配置系统从Aspire:Azure:Search:Documents配置节加载AzureSearchSettings和SearchClientOptions。示例appsettings.json{ Aspire: { Azure: { Search: { Documents: { DisableTracing: false } } } } }该配置节名在源码中定义为常量DefaultConfigSectionName Aspire:Azure:Search:Documents。组件的 ConfigurationSchema.json 完整定义了这一节支持的全部属性核心包括配置项类型说明默认值Endpointstring (uri)Azure AI Search 端点形如https://{search_service}.search.windows.net无Keystring用于认证的访问密钥配置后优先使用AzureKeyCredential无DisableTracingboolean是否禁用 OpenTelemetry 追踪falseDisableHealthChecksboolean是否禁用健康检查falseClientOptions.Retryobject客户端重试策略ModeFixed/Exponential、MaxRetries、Delay、MaxDelay、NetworkTimeoutSDK 默认ClientOptions.Diagnosticsobject诊断选项ApplicationId、DefaultApplicationId、IsDistributedTracingEnabled、IsLoggingEnabled、IsLoggingContentEnabled、LoggedContentSizeLimit默认 4096 字节、LoggedHeaderNames、LoggedQueryParameters等SDK 默认其中Endpoint与Key也可以通过配置节直接提供而不必走ConnectionStrings与内联委托方式等效。方式三使用内联委托Inline DelegatesAddAzureSearchClient的两个可选参数提供了纯代码配置的途径。调整AzureSearchSettings例如从代码中禁用追踪builder.AddAzureSearchClient(searchConnectionName, settings settings.DisableTracing true);调整SearchClientOptions通过configureClientBuilder参数操作IAzureClientBuilderSearchIndexClient, SearchClientOptions例如为客户端设置 User-Agent 中的应用 ID用于在 Azure 端区分请求来源builder.AddAzureSearchClient(searchConnectionName, configureClientBuilder: builder builder.ConfigureOptions(options options.Diagnostics.ApplicationId CLIENT_ID));configureSettings委托在设置从配置读取完成后被调用见 AspireAzureSearchExtensions.cs因此它既可以修改配置节带来的值也可以补充配置节未覆盖的设置两者可自由组合。多实例场景AddKeyedAzureSearchClient除了单例注册组件还提供了键控keyed注册能力AddKeyedAzureSearchClient(string name, ...)允许在同一应用中同时连接多个 Azure AI Search 服务builder.AddKeyedAzureSearchClient(search1); builder.AddKeyedAzureSearchClient(search2);键控客户端从Aspire:Azure:Search:Documents:{name}配置节读取设置并以name作为服务键ServiceKey注入消费时使用GetRequiredKeyedServiceSearchIndexClient(search1)获取。这一点在测试 AspireAzureSearchExtensionsTests.cs 的CanAddMultipleKeyedServices用例中有明确验证三个连接分别注册后search2与search3得到的是两个指向不同端点的独立客户端实例。AppHost 编排在分布式应用中管理 Search 服务以上是业务项目消费端的接入方式。在 Aspire 的完整开发模型中通常还需要在AppHost 项目中通过托管Hosting集成来编排 Azure AI Search 资源。这需要安装托管库dotnet add package Aspire.Hosting.Azure.Search然后在 AppHost 的_AppHost.cs_中按是否发布模式区分资源的建模方式var search builder.ExecutionContext.IsPublishMode ? builder.AddAzureSearch(search) : builder.AddConnectionString(search); var myService builder.AddProjectProjects.MyService() .WithReference(search);这段代码表达了两种模式发布模式Publish ModeAddAzureSearch(search)向应用模型中添加一个真实的 Azure AI Search 资源部署时由 Azure Provisioning 自动在订阅中创建。本地开发模式AddConnectionString(search)从 AppHost 自身配置例如 user secrets的ConnectionStrings:search键读取连接信息方便开发者直接连接既有搜索服务而无需真正部署 Azure 资源。WithReference(search)将连接信息以名为search的连接字符串注入MyService项目。于是业务项目中只需一句builder.AddAzureSearchClient(search);即可完成消费端接入AppHost 与业务项目通过约定好的连接名称天然对齐。托管集成的默认行为与角色分配从 AzureSearchExtensions.cs 的实现可以看到AddAzureSearch的默认行为新建的SearchService资源采用Basic SKUReplicaCount 1、PartitionCount 1、默认托管模式HostingMode.Default并默认禁用本地认证IsLocalAuthDisabled true——这正与消费端优先使用 Entra 凭据、Endpoint 连接的推荐方式相呼应默认给引用该资源的项目分配两个内置角色SearchIndexDataContributor与SearchServiceContributor分别覆盖数据面与控制面权限输出connectionString、endpoint、name、id四个 Provisioning 输出供后续角色分配与私有端点private endpoint场景使用若资源带有私有端点注解还会自动禁用公网访问PublicNetworkAccess.Disabled。如需自定义角色可用WithRoleAssignments替换默认角色分配例如只授予只读数据权限var search builder.AddAzureSearch(search); var api builder.AddProjectProjects.Api(api) .WithRoleAssignments(search, SearchBuiltInRole.SearchIndexDataReader) .WithReference(search);角色定义集中在 AzureSearchRole.cs支持SearchIndexDataContributor、SearchIndexDataReader、SearchServiceContributor三种。该托管集成更详细的使用说明见 Aspire.Hosting.Azure.Search 文档其中还包含 TypeScript AppHostbuilder.addAzureSearch(search)的等价写法。客户端工厂与认证逻辑底层原理剖析理解SearchIndexClient究竟如何被构建有助于排查连接问题。组件的核心逻辑在 AspireAzureSearchExtensions.cs 的AddClient工厂方法中return azureFactoryBuilder.AddClientSearchIndexClient, SearchClientOptions((options, _, _) { if (settings.Endpoint is null) { throw new InvalidOperationException( $A SearchIndexClient could not be configured. Ensure valid connection information was provided in ConnectionStrings:{connectionName} or specify an {nameof(AzureSearchSettings.Endpoint)} in the {configurationSectionName} configuration section.); } if (!string.IsNullOrWhiteSpace(settings.Key)) { return new SearchIndexClient(settings.Endpoint, new AzureKeyCredential(settings.Key), options); } else { return new SearchIndexClient(settings.Endpoint, settings.Credential ?? AzureCredentialHelper.CreateDefaultAzureCredential(), options); } });由此可以得到三条明确的认证规则Endpoint为 null 时直接抛出InvalidOperationException提示信息会明确指向ConnectionStrings:{connectionName}或配置节Aspire:Azure:Search:Documents方便快速定位配置缺失配置了Key时优先使用AzureKeyCredential共享密钥认证未配置Key时使用settings.Credential若也未设置则回退到默认 Azure 凭据链AzureCredentialHelper.CreateDefaultAzureCredential()即 Entra/托管标识认证。此外AzureSearchSettings的Credential属性还通过GetTokenCredential供组件内部其他环节如角色分配场景复用。可观测性与健康检查开箱即用的运维能力该组件之所以开箱即用体现在它对 Aspire 三大可观测支柱的默认接入见 AspireAzureSearchExtensions.cs日志Logging基于Azure.Core的 HTTP 管道日志。通过SearchClientOptions.Diagnostics系列选项可控制日志粒度例如IsLoggingEnabled、IsLoggingContentEnabled默认最多记录 4096 字节请求/响应体、LoggedHeaderNames、LoggedQueryParameters等。日志分类器涵盖Azure、Azure-Search-Documents、Azure.Core、Azure.Identity等可在日志配置中按需调整级别见 ConfigurationSchema.json。追踪Tracing组件将 Activity 源ActivitySource声明为Azure.Search.Documents.*使 Azure SDK 发出的分布式追踪活动System.Diagnostics.Activity自动流入 Aspire 的 OpenTelemetry 管道。默认开启可通过DisableTracing关闭builder.AddAzureSearchClient(searchConnectionName, settings settings.DisableTracing true);健康检查Health Checks组件默认注册一个基于SearchIndexClient的健康检查实现见 AzureSearchIndexHealthCheck.cs通过调用GetServiceStatisticsAsync探测搜索服务的连通性成功返回Healthy失败则返回携带描述信息Failed to connect to Azure AI Search service.的Unhealthy状态。健康检查的名称在 AspireAzureSearchExtensionsTests.cs 中有明确约定普通注册为Azure_SearchIndexClient键控注册为Azure_SearchIndexClient_{name}。测试用例AddAzureSearchClient_HealthCheckReportsConnectionFailureDescription验证了连接不可达时健康检查会正确报告Unhealthy与失败原因。可通过DisableHealthChecks关闭健康检查{ Aspire: { Azure: { Search: { Documents: { DisableHealthChecks: true } } } } }指标Metrics需要特别说明的是与多数 Azure 组件不同该组件目前不启用客户端指标——源码中GetMetricsEnabled固定返回false。也就是说开箱即用的是日志、追踪与健康检查三件套指标维度需要依赖其他监控渠道。测试验证组件行为的代码级证据仓库中的 Aspire.Azure.Search.Documents.Tests 测试项目从多个维度固化了组件行为可作为你集成时的行为参照ReadsFromConnectionStringsCorrectly验证ConnectionStrings:search中的Endpoint...;Key...连接字符串能被正确解析并反映到客户端Endpoint上测试代码ConnectionStringCanBeSetInCode验证通过configureSettings委托在代码中直接指定Endpoint与Key同样可行CanAddMultipleKeyedServices验证键控注册支持同一进程内多搜索服务并存AddAzureSearchClient_HealthCheckReportsConnectionFailureDescription验证不可达端点下健康检查报告Unhealthy及对应描述信息。这些用例与上文配置解析多实例健康检查三节一一对应是理解组件契约的官方行为基准。小结与扩展阅读综上Aspire.Azure.Search.Documents组件提供了从AppHost 资源编排到业务项目客户端注册的完整链路业务侧一行AddAzureSearchClient(name)完成单例注册与可观测性接入托管侧AddAzureSearchWithReference完成资源的建模、部署与连接传递。三条配置通道ConnectionStrings、配置提供者、内联委托按项目约定自由组合键控注册则服务于多搜索服务的复杂场景。如需进一步深入可在仓库中继续阅读组件入口与工厂实现AspireAzureSearchExtensions.cs设置模型与连接字符串解析AzureSearchSettings.cs完整配置 SchemaConfigurationSchema.json托管集成使用说明Aspire.Hosting.Azure.Search/README.md托管集成实现AzureSearchExtensions.cs组件行为测试AspireAzureSearchExtensionsTests.cs各 Aspire 组件总览src/Components 目录【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考