Edit

.NET Aspire Azure AI Search Documents component

  • Article

In this article, you learn how to use the .NET Aspire Azure AI Search Documents client. The Aspire.Azure.Search.Documents library is used to register an SearchIndexClient in the dependency injection (DI) container for connecting to Azure Search. It enables corresponding health checks and logging.

For more information on using the SearchIndexClient, see How to use Azure.Search.Documents in a C# .NET Application.

Get started

To get started with the .NET Aspire Azure AI Search Documents component, install the Aspire.Azure.Search.Documents NuGet package.

dotnet add package Aspire.Azure.Search.Documents --prerelease

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Example usage

In the Program.cs file of your component-consuming project, call the extension method to register an SearchIndexClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddAzureSearch("searchConnectionName");

You can then retrieve the SearchIndexClient instance using dependency injection. For example, to retrieve the client from an example service:

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

You can also retrieve a SearchClient which can be used for querying, by calling the SearchIndexClient.GetSearchClient method as follows:

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

For more information, see the Azure AI Search client library for .NET for examples on using the SearchIndexClient.

App host usage

To add Azure AI hosting support to your IDistributedApplicationBuilder, install the Aspire.Hosting.Azure.CognitiveServices NuGet package.

dotnet add package Aspire.Hosting.Azure.CognitiveServices --prerelease

In the Program.cs file of AppHost, add an Azure Search service and consume the connection using the following methods:

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

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

The AddAzureSearch method will read connection information from the AppHost's configuration (for example, from "user secrets") under the ConnectionStrings:search config key. The WithReference method passes that connection information into a connection string named search in the MyService project. In the Program.cs file of MyService, the connection can be consumed using:

builder.AddAzureSearch("search");

Configuration

The .NET Aspire Azure Azure Search library provides multiple options to configure the Azure Search Service based on the requirements and conventions of your project. Note that either an Endpoint or a ConnectionString is required to be supplied.

Use a connection string

A connection can be constructed from the Keys and Endpoint tab with the format Endpoint={endpoint};Key={key};. You can provide the name of the connection string when calling builder.AddAzureSearch():

builder.AddAzureSearch("searchConnectionName");

And then the connection string will be retrieved from the ConnectionStrings configuration section. Two connection formats are supported:

Account endpoint

The recommended approach is to use an Endpoint, which works with the AzureSearchSettings.Credential property to establish a connection. If no credential is configured, the DefaultAzureCredential is used.

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

Connection string

Alternatively, a custom connection string can be used.

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

Use configuration providers

The .NET Aspire Azure AI Search library supports Microsoft.Extensions.Configuration. It loads the AzureSearchSettings and SearchClientOptions from configuration by using the Aspire:Azure:Search:Documents key. Example appsettings.json that configures some of the options:

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

Use inline delegates

You can also pass the Action<AzureSearchSettings> configureSettings delegate to set up some or all the options inline, for example to disable tracing from code:

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

You can also setup the SearchClientOptions using the optional Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder parameter of the AddAzureSearch method. For example, to set the client ID for this client:

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

Health checks

By default, .NET Aspire components enable health checks for all services. For more information, see .NET Aspire components overview.

The .NET Aspire Azure AI Search Documents component implements a single health check, that calls the GetServiceStatisticsAsync method on the SearchIndexClient to verify that the service is available.

Observability and telemetry

.NET Aspire components automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about component observability and telemetry, see .NET Aspire components overview. Depending on the backing service, some components may only support some of these features. For example, some components support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The .NET Aspire Azure AI Search Documents component uses the following log categories:

  • Azure
  • Azure.Core
  • Azure.Identity

See also