Skip to content

Latest commit

 

History

History
207 lines (144 loc) · 7.87 KB

azureai-search-document-component.md

File metadata and controls

207 lines (144 loc) · 7.87 KB
Raw
title description ms.topic ms.date
.NET Aspire Azure AI Search Documents component
Learn how to use the .NET Aspire Azure AI Search Documents component.
how-to
07/17/2024

.NET Aspire Azure AI Search Documents component

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 xref:Azure.Search.Documents.Indexes.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 in the consuming client project.

.NET CLI

dotnet add package Aspire.Azure.Search.Documents

PackageReference

<PackageReference Include="Aspire.Azure.Search.Documents"
                  Version="[SelectVersion]" />

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

Example usage

In the :::no-loc text="Program.cs"::: file of your component-consuming project, call the extension method to register an SearchIndexClient for use via the dependency injection container. The xref:Microsoft.Extensions.Hosting.AspireAzureSearchExtensions.AddAzureSearchClient%2A method takes a connection name parameter.

builder.AddAzureSearchClient("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 xref:Azure.Search.Documents.Indexes.SearchIndexClient.GetSearchClient%2A?displayProperty=nameWithType 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 xref:Aspire.Hosting.IDistributedApplicationBuilder, install the Aspire.Hosting.Azure.Search NuGet package in the app host project.

.NET CLI

dotnet add package Aspire.Hosting.Azure.Search

PackageReference

<PackageReference Include="Aspire.Hosting.Azure.Search"
                  Version="[SelectVersion]" />

In the :::no-loc text="Program.cs"::: file of AppHost, add an Azure Search service and consume the connection using the following methods:

var builder = DistributedApplication.CreateBuilder(args);

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

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

The xref:Aspire.Hosting.AzureSearchExtensions.AddAzureSearch%2A 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 :::no-loc text="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 xref:Azure.Identity.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 xref:Microsoft.Extensions.Configuration?displayProperty=fullName. It loads the AzureSearchSettings and SearchClientOptions from configuration by using the Aspire:Azure:Search:Documents key. Example :::no-loc text="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 xref:Azure.Search.Documents.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"));

[!INCLUDE component-health-checks]

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

[!INCLUDE component-observability-and-telemetry]

Logging

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

  • Azure
  • Azure.Core
  • Azure.Identity

See also