Connect to Azure AI Search

This page describes how consuming apps connect to an Azure AI Search resource that’s already modeled in your AppHost. For the AppHost API surface — adding a search resource, connecting to existing services, customizing provisioning, and more — see Azure AI Search Hosting integration.

When you reference an Azure AI Search resource from your AppHost, Aspire injects the connection information into the consuming app as environment variables. Your app can either read those environment variables directly — the pattern works the same from any language — or, in C#, use the Aspire Azure AI Search client integration for automatic dependency injection, health checks, and telemetry.

Connection properties

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Endpoint property of a resource called search becomes SEARCH_ENDPOINT.

The Azure AI Search resource exposes the following connection properties:

Property Name	Description
Endpoint	The HTTPS endpoint of the Azure AI Search service: https://{name}.search.windows.net
ApiKey	The admin API key (only available when using key-based connection strings, not role-based auth)

Example connection string (role-based access, default):

Endpoint=https://mysearch.search.windows.net

Example connection string (key-based access):

Endpoint=https://mysearch.search.windows.net;Key={account_key}

참고

By default, Azure AI Search resources are provisioned with disableLocalAuth: true, which uses role-based access via managed identity rather than API keys. The ApiKey property is only available when you provide a key-based connection string.

Connect from your app

Pick the language your consuming app is written in. Each example assumes your AppHost adds an Azure AI Search resource named search and references it from the consuming app.

C#

For C# apps, the recommended approach is the Aspire Azure AI Search client integration. It registers a SearchIndexClient through dependency injection and adds health checks and telemetry automatically. If you’d rather read environment variables directly, see the Read environment variables section at the end of this tab.

Install the client integration

Install the 📦 Aspire.Azure.Search.Documents NuGet package in the client-consuming project:

.NET CLI

.NET CLI — Add Aspire.Azure.Search.Documents package

dotnet add package Aspire.Azure.Search.Documents

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Azure.Search.Documents@*

PackageReference (*.csproj)

XML — Add Aspire.Azure.Search.Documents package reference

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

Add the Azure Search index client

In Program.cs, call AddAzureSearchClient on your IHostApplicationBuilder to register a SearchIndexClient:

C# — Program.cs

builder.AddAzureSearchClient(connectionName: "search");

팁

The connectionName must match the Azure AI Search resource name from the AppHost. For more information, see Add Azure AI Search resource.

Resolve the client through dependency injection:

C# — ExampleService.cs

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

You can also retrieve a SearchClient for querying by calling GetSearchClient on the injected SearchIndexClient:

C# — ExampleService.cs

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

Add keyed Azure Search index clients

To register multiple SearchIndexClient instances with different connection names, use AddKeyedAzureSearchClient:

C# — Program.cs

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

Then resolve each instance by key:

C# — ExampleService.cs

public class ExampleService(
    [FromKeyedServices("catalog")] SearchIndexClient catalogClient,
    [FromKeyedServices("documents")] SearchIndexClient documentsClient)
{
    // Use clients...
}

For more information, see .NET dependency injection: Keyed services.

Configuration

The Aspire Azure AI Search client integration offers multiple ways to provide configuration.

Connection strings. When using a connection string from the ConnectionStrings configuration section, pass the connection name to AddAzureSearchClient.

For role-based access (recommended), provide just the endpoint URL:

JSON — appsettings.json

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

For key-based access, provide the full connection string:

JSON — appsettings.json

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

Configuration providers. The client integration supports Microsoft.Extensions.Configuration. It loads AzureSearchSettings from appsettings.json (or any other configuration source) by using the Aspire:Azure:Search:Documents key:

JSON — appsettings.json

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

For the complete Azure AI Search Documents client integration JSON schema, see Aspire.Azure.Search.Documents/ConfigurationSchema.json.

Named configuration. To configure multiple instances, use the connection name as a key:

JSON — appsettings.json

{
  "Aspire": {
    "Azure": {
      "Search": {
        "Documents": {
          "search1": {
            "Endpoint": "https://mysearch1.search.windows.net/",
            "DisableTracing": false
          },
          "search2": {
            "Endpoint": "https://mysearch2.search.windows.net/",
            "DisableTracing": true
          }
        }
      }
    }
  }
}

Named configuration takes precedence over top-level configuration when both are provided.

Inline delegates. Pass an Action<AzureSearchSettings> to configure settings inline:

C# — Program.cs

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

You can also configure the SearchClientOptions using the configureClientBuilder parameter:

C# — Program.cs

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

Client integration health checks

The Azure AI Search client integration adds a health check that calls GetServiceStatisticsAsync on the SearchIndexClient to verify that the service is available. The health check is wired into the /health HTTP endpoint, where all registered health checks must pass before the app is considered ready to accept traffic.

Observability and telemetry

The Aspire Azure AI Search client integration automatically configures logging, tracing, and metrics through OpenTelemetry.

Logging categories:

• Azure
• Azure.Core
• Azure.Identity

Tracing activities:

• The integration emits tracing activities using OpenTelemetry when interacting with the search service.

Any of these telemetry features can be disabled through the configuration options above.

Read environment variables in C#

If you prefer not to use the Aspire client integration, you can read the Aspire-injected endpoint from the environment and use the 📦 Azure.Search.Documents package directly with DefaultAzureCredential:

C# — Program.cs

using Azure;
using Azure.Identity;
using Azure.Search.Documents.Indexes;

var endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT")!);

// Use DefaultAzureCredential for role-based access (recommended)
var indexClient = new SearchIndexClient(endpoint, new DefaultAzureCredential());

// Use AzureKeyCredential for key-based access
// var apiKey = Environment.GetEnvironmentVariable("SEARCH_APIKEY");
// var indexClient = new SearchIndexClient(endpoint, new AzureKeyCredential(apiKey!));

Go

Use the azure-sdk-for-go package for Azure AI Search:

Terminal

go get github.com/Azure/azure-sdk-for-go/sdk/search/azsearch
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Read the injected environment variable and connect:

Go — main.go

package main

import (
    "os"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/search/azsearch"
)

func main() {
    // Read the Aspire-injected endpoint
    endpoint := os.Getenv("SEARCH_ENDPOINT")

    // Use DefaultAzureCredential for role-based access (recommended)
    cred, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        panic(err)
    }

    client, err := azsearch.NewIndexesClient(endpoint, cred, nil)
    if err != nil {
        panic(err)
    }

    _ = client
}

For key-based access, use azsearch.NewIndexesClientWithKey:

Go — main.go (key-based)

package main

import (
    "os"
    "github.com/Azure/azure-sdk-for-go/sdk/search/azsearch"
)

func main() {
    endpoint := os.Getenv("SEARCH_ENDPOINT")
    apiKey := os.Getenv("SEARCH_APIKEY")

    client, err := azsearch.NewIndexesClientWithKey(endpoint, apiKey, nil)
    if err != nil {
        panic(err)
    }

    _ = client
}

Python

Install the azure-search-documents package:

Terminal

pip install azure-search-documents azure-identity

Read the injected environment variable and connect:

Python — app.py

import os
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

# Read the Aspire-injected endpoint
endpoint = os.getenv("SEARCH_ENDPOINT")

# Use DefaultAzureCredential for role-based access (recommended)
credential = DefaultAzureCredential()
client = SearchIndexClient(endpoint=endpoint, credential=credential)

For key-based access, use AzureKeyCredential:

Python — app.py (key-based)

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

endpoint = os.getenv("SEARCH_ENDPOINT")
api_key = os.getenv("SEARCH_APIKEY")

client = SearchIndexClient(endpoint=endpoint, credential=AzureKeyCredential(api_key))

TypeScript

Install the @azure/search-documents package:

Terminal

npm install @azure/search-documents @azure/identity

Read the injected environment variables and connect:

TypeScript — index.ts

import { SearchIndexClient } from '@azure/search-documents';
import { DefaultAzureCredential } from '@azure/identity';

// Read Aspire-injected connection properties
const endpoint = process.env.SEARCH_ENDPOINT!;

// Use DefaultAzureCredential for role-based access (recommended)
const client = new SearchIndexClient(endpoint, new DefaultAzureCredential());

For key-based access, use AzureKeyCredential:

TypeScript — index.ts (key-based)

import { SearchIndexClient, AzureKeyCredential } from '@azure/search-documents';

const endpoint = process.env.SEARCH_ENDPOINT!;
const apiKey = process.env.SEARCH_APIKEY!;

const client = new SearchIndexClient(endpoint, new AzureKeyCredential(apiKey));

팁

For role-based access to work in local development, ensure that your local Azure identity (the account you’re signed in to with the Azure CLI or Azure Developer CLI) has the required roles assigned on the Azure AI Search service. For more information, see Local provisioning: Configuration.