共用方式為

.NET Aspire Azure AI 搜尋文件整合

  • 發行項

在本文中，您將瞭解如何使用 .NET AspireAzure AI 搜尋檔案用戶端。 Aspire.Azure.Search.Documents 程式庫可用來在相依性注入（DI）容器中註冊 SearchIndexClient，以連線到 Azure 搜尋。 它可啟用對應的健康檢查和日誌記錄。

如需使用 SearchIndexClient的詳細資訊，請參閱 如何使用 Azure。 在 C# .NET 應用程式中使用 Search.Documents。

開始使用

若要開始使用 .NET AspireAzure AI 搜尋檔案整合，請在用戶端使用的專案中安裝 📦Aspire。Azure。Search.Documents NuGet 套件，也就是使用 Azure AI 搜尋檔案用戶端的應用程式專案。

dotnet add package Aspire.Azure.Search.Documents

如需詳細資訊，請參閱 dotnet add package 或 管理 .NET 應用程式中的套件相依性。

範例使用方式

在用戶端使用專案的 Program.cs 檔案中，呼叫擴充方法來註冊 SearchIndexClient，以便透過依賴注入容器來使用。 AddAzureSearchClient 方法會採用連接名稱參數。

builder.AddAzureSearchClient("searchConnectionName");

接著，您可以使用依賴注入來擷取 SearchIndexClient 實體。 例如，若要從範例服務取得客戶端：

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

您也可以呼叫 SearchClient 方法來擷取可用於查詢的 SearchIndexClient.GetSearchClient，如下所示：

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

如需詳細資訊，請參閱 .NET的Azure AI 搜尋用戶端庫，以獲得使用 SearchIndexClient的範例。

應用程式主機使用方式

若要將 Azure AI 主控支援新增至您的 IDistributedApplicationBuilder，請在 📦 專案中安裝 AspireAzure主控。.Search NuGet 套件。

dotnet add package Aspire.Hosting.Azure.Search

在 Program.cs的 AppHost 檔案中，添加 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 方法會將該連接資訊傳遞至 search 項目中名為 MyService 的連接字串。 在 Program.cs的 MyService 檔案中，可以使用下列專案來取用連線：

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。 它會使用 AzureSearchSettings 鍵從組態載入 SearchClientOptions 和 Aspire:Azure:Search:Documents。 設定選項的範例 appsettings.json：

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

使用內聯委派

您也可以傳遞 Action<AzureSearchSettings> configureSettings 委派來設定部分或所有內嵌選項，例如停用程式代碼追蹤：

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

您也可以使用 SearchClientOptions 方法的選擇性 Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder 參數來設定 AddAzureSearch。 例如，若要設定此用戶端的用戶端識別碼：

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

Client 整合性健康檢查

根據預設，.NET.NET Aspire客戶端整合 的 健康檢查 已對所有服務啟用。 同樣地，許多 .NET.NET Aspire代管整合 也會啟用健康檢查端點。 如需詳細資訊，請參閱：

  • .NET 在 C# 中應用程式健康情況檢查
  • 中的 健康情況檢查

.NET Aspire Azure AI 搜尋文檔整合會實作單一健康檢查，會在 GetServiceStatisticsAsync 上呼叫 SearchIndexClient 方法，以確認服務的可用性。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和度量組態，有時稱為 觀察性的支柱。 如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。 視支援服務而定，某些整合可能只支援其中一些功能。 例如，某些整合支援記錄和追蹤，但不支援計量。 您也可以使用 組態 一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire Azure AI 搜尋檔案整合會使用下列記錄類別：

  • Azure
  • Azure.Core
  • Azure.Identity

另請參閱