Azure Search .NET SDK sürüm 1.1'e yükseltme

Makale
09/16/2021

Azure Search .NET SDK'sının 1.0.2-preview veya daha eski bir sürümünü kullanıyorsanız, bu makale uygulamanızı 1.1 sürümünü kullanacak şekilde yükseltmenize yardımcı olur.

Örnekler de dahil olmak üzere SDK'nın daha genel bir kılavuzu için bkz. .NET Uygulamasından Azure Search'ü kullanma.

Not

Sürüm 1.1'e yükseltdiğinizde veya zaten 1.1 ile 2.0-preview (dahil) arasında bir sürüm kullanıyorsanız sürüm 3'e yükseltmeniz gerekir. Yönergeler için bkz. Azure Search .NET SDK sürüm 3'e yükseltme .

İlk olarak, NuGet Paket Yöneticisi Konsolu'nu kullanmak için Microsoft.Azure.Search NuGet başvurunuzu güncelleştirin veya proje başvurularınıza sağ tıklayıp "NuGet Paketlerini Yönet..." seçeneğini belirleyin. Visual Studio...

NuGet yeni paketleri ve bağımlılıklarını indirdikten sonra projenizi yeniden derleyin.

Daha önce 1.0.0-preview, 1.0.1-preview veya 1.0.2-preview sürümünü kullanıyorsanız derleme başarılı olmalı ve başlamaya hazırsınız demektir!

Daha önce 0.13.0-preview veya daha eski bir sürümü kullanıyorsanız, aşağıdakine benzer derleme hataları görmeniz gerekir:

Program.cs(137,56,137,62): error CS0117: 'Microsoft.Azure.Search.Models.IndexBatch' does not contain a definition for 'Create'
Program.cs(137,99,137,105): error CS0117: 'Microsoft.Azure.Search.Models.IndexAction' does not contain a definition for 'Create'
Program.cs(146,41,146,54): error CS1061: 'Microsoft.Azure.Search.IndexBatchException' does not contain a definition for 'IndexResponse' and no extension method 'IndexResponse' accepting a first argument of type 'Microsoft.Azure.Search.IndexBatchException' could be found (are you missing a using directive or an assembly reference?)
Program.cs(163,13,163,42): error CS0246: The type or namespace name 'DocumentSearchResponse' could not be found (are you missing a using directive or an assembly reference?)

Sonraki adım, derleme hatalarını tek tek düzeltmektir. Çoğu, SDK'da yeniden adlandırılmış bazı sınıf ve yöntem adlarını değiştirmeyi gerektirir. Sürüm 1.1'deki hataya neden olan değişikliklerin listesi, bu ad değişikliklerinin listesini içerir.

Belgelerinizi modellemek için özel sınıflar kullanıyorsanız ve bu sınıfların null atanamayan ilkel türlerin özellikleri varsa (örneğin, int C bool # dilinde), SDK'nın 1.1 sürümünde farkında olmanız gereken bir hata düzeltmesi vardır. Diğer ayrıntılar için bkz. Sürüm 1.1'deki hata düzeltmeleri .

Son olarak, derleme hatalarını düzeltdikten sonra, isterseniz yeni işlevlerden yararlanmak için uygulamanızda değişiklikler yapabilirsiniz.

Sürüm 1.1'deki hataya neden olan değişikliklerin listesi

Aşağıdaki liste, değişikliğin uygulama kodunuzu etkileme olasılığına göre sıralanır.

IndexBatch ve IndexAction değişiklikleri

IndexBatch.Create olarak yeniden adlandırıldı IndexBatch.New ve artık bağımsız params değişkeni yok. Farklı eylem türlerini (birleştirmeler, silmeler vb.) karıştıran toplu işlemler için kullanabilirsiniz IndexBatch.New . Ayrıca, tüm eylemlerin aynı olduğu toplu işlemler oluşturmak için yeni statik yöntemler vardır: Delete, Merge, MergeOrUploadve Upload.

IndexAction artık ortak oluşturucuları yok ve özellikleri artık sabit. Farklı amaçlarla eylem oluşturmak için yeni statik yöntemleri kullanmalısınız: Delete, Merge, MergeOrUploadve Upload. IndexAction.Create Kaldırıldı. Yalnızca bir belgeyi alan aşırı yüklemeyi kullandıysanız, bunun yerine kullandığınızdan Upload emin olun.

Örnek

Kodunuz aşağıdaki gibi görünüyorsa:

var batch = IndexBatch.Create(documents.Select(doc => IndexAction.Create(doc)));
indexClient.Documents.Index(batch);

Derleme hatalarını düzeltmek için bunu şu şekilde değiştirebilirsiniz:

var batch = IndexBatch.New(documents.Select(doc => IndexAction.Upload(doc)));
indexClient.Documents.Index(batch);

İsterseniz bunu daha da basitleştirebilirsiniz:

var batch = IndexBatch.Upload(documents);
indexClient.Documents.Index(batch);

IndexBatchException değişiklikleri

IndexBatchException.IndexResponse özelliği olarak yeniden adlandırılmıştır IndexingResultsve türü artık IList<IndexingResult>şeklindedir.

Örnek

Kodunuz aşağıdaki gibi görünüyorsa:

catch (IndexBatchException e)
{
    Console.WriteLine(
        "Failed to index some of the documents: {0}",
        String.Join(", ", e.IndexResponse.Results.Where(r => !r.Succeeded).Select(r => r.Key)));
}

Derleme hatalarını düzeltmek için bunu şu şekilde değiştirebilirsiniz:

catch (IndexBatchException e)
{
    Console.WriteLine(
        "Failed to index some of the documents: {0}",
        String.Join(", ", e.IndexingResults.Where(r => !r.Succeeded).Select(r => r.Key)));
}

İşlem yöntemi değişiklikleri

Azure Search .NET SDK'sı içindeki her işlem, zaman uyumlu ve zaman uyumsuz çağıranlar için bir dizi yöntem aşırı yüklemesi olarak kullanıma sunulur. Bu yöntem aşırı yüklemelerinin imzaları ve çarpanları sürüm 1.1'de değişmiştir.

Örneğin, SDK'nın eski sürümlerindeki "Dizin İstatistiklerini Al" işlemi şu imzaları kullanıma sunar:

IIndexOperations içinde:

// Asynchronous operation with all parameters
Task<IndexGetStatisticsResponse> GetStatisticsAsync(
    string indexName,
    CancellationToken cancellationToken);

IndexOperationsExtensions içinde:

// Asynchronous operation with only required parameters
public static Task<IndexGetStatisticsResponse> GetStatisticsAsync(
    this IIndexOperations operations,
    string indexName);

// Synchronous operation with only required parameters
public static IndexGetStatisticsResponse GetStatistics(
    this IIndexOperations operations,
    string indexName);

Sürüm 1.1'deki aynı işlem için yöntem imzaları şöyle görünür:

IIndexesOperations içinde:

// Asynchronous operation with lower-level HTTP features exposed
Task<AzureOperationResponse<IndexGetStatisticsResult>> GetStatisticsWithHttpMessagesAsync(
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions),
    Dictionary<string, List<string>> customHeaders = null,
    CancellationToken cancellationToken = default(CancellationToken));

IndexesOperationsExtensions içinde:

// Simplified asynchronous operation
public static Task<IndexGetStatisticsResult> GetStatisticsAsync(
    this IIndexesOperations operations,
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions),
    CancellationToken cancellationToken = default(CancellationToken));

// Simplified synchronous operation
public static IndexGetStatisticsResult GetStatistics(
    this IIndexesOperations operations,
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions));

Sürüm 1.1'den başlayarak, Azure Search .NET SDK'sı işlem yöntemlerini farklı düzenler:

İsteğe bağlı parametreler artık ek yöntem aşırı yüklemeleri yerine varsayılan parametreler olarak modellenir. Bu, yöntem aşırı yüklemelerinin sayısını bazen önemli ölçüde azaltır.
Uzantı yöntemleri artık http'nin çok fazla ayrıntısını çağırandan gizler. Örneğin, SDK'nın eski sürümleri HTTP durum koduna sahip bir yanıt nesnesi döndürdü. İşlem yöntemleri CloudException hataya işaret eden herhangi bir durum kodu oluşturacağından genellikle denetlemeniz gerekmiyordu. Yeni uzantı yöntemleri yalnızca model nesnelerini döndürerek kodunuzda bunları açma zahmetini yaşamanızı sağlar.
Buna karşılık, çekirdek arabirimler artık ihtiyacınız olduğunda HTTP düzeyinde daha fazla denetim sağlayan yöntemleri kullanıma sunar. Artık isteklere dahil edilecek özel HTTP üst bilgilerini geçirebilirsiniz ve yeni AzureOperationResponse<T> dönüş türü, işlem için ve HttpResponseMessage öğesine doğrudan erişim HttpRequestMessage sağlar. AzureOperationResponse ad alanında Microsoft.Rest.Azure tanımlanır ve öğesinin yerini alır Hyak.Common.OperationResponse.

ScoringParameters değişiklikleri

Arama sorgusundaki puanlama profillerine parametre sağlamayı kolaylaştırmak için en son SDK'ya adlı ScoringParameter yeni bir sınıf eklendi. ScoringProfiles Daha önce sınıfının özelliği SearchParameters olarak IList<string>yazıldı; Şimdi olarak IList<ScoringParameter>yazıldı.

Örnek

Kodunuz aşağıdaki gibi görünüyorsa:

var sp = new SearchParameters();
sp.ScoringProfile = "jobsScoringFeatured";      // Use a scoring profile
sp.ScoringParameters = new[] { "featuredParam-featured", "mapCenterParam-" + lon + "," + lat };

Derleme hatalarını düzeltmek için bunu şu şekilde değiştirebilirsiniz:

var sp = new SearchParameters();
sp.ScoringProfile = "jobsScoringFeatured";      // Use a scoring profile
sp.ScoringParameters =
    new[]
    {
        new ScoringParameter("featuredParam", new[] { "featured" }),
        new ScoringParameter("mapCenterParam", GeographyPoint.Create(lat, lon))
    };

Model sınıfı değişiklikleri

İşlem yöntemi değişiklikleri'nde açıklanan imza değişiklikleri nedeniyle, ad alanında Microsoft.Azure.Search.Models birçok sınıf yeniden adlandırıldı veya kaldırıldı. Örnek:

IndexDefinitionResponse şununla değiştirildi: AzureOperationResponse<Index>
DocumentSearchResponse, DocumentSearchResult olarak yeniden adlandırıldı
IndexResult, IndexingResult olarak yeniden adlandırıldı
Documents.Count() şimdi belge sayısı yerine bir long döndürür DocumentCountResponse
IndexGetStatisticsResponse, IndexGetStatisticsResult olarak yeniden adlandırıldı
IndexListResponse, IndexListResult olarak yeniden adlandırıldı

Özetlemek gerekirse, OperationResponseyalnızca bir model nesnesini sarmalama amacıyla var olan türetilmiş sınıflar kaldırıldı. Kalan sınıfların sonekleri olarak değiştirildi ResponseResult.

Örnek

Kodunuz aşağıdaki gibi görünüyorsa:

IndexerGetStatusResponse statusResponse = null;

try
{
    statusResponse = _searchClient.Indexers.GetStatus(indexer.Name);
}
catch (Exception ex)
{
    Console.WriteLine("Error polling for indexer status: {0}", ex.Message);
    return;
}

IndexerExecutionResult lastResult = statusResponse.ExecutionInfo.LastResult;

Derleme hatalarını düzeltmek için bunu şu şekilde değiştirebilirsiniz:

IndexerExecutionInfo status = null;

try
{
    status = _searchClient.Indexers.GetStatus(indexer.Name);
}
catch (Exception ex)
{
    Console.WriteLine("Error polling for indexer status: {0}", ex.Message);
    return;
}

IndexerExecutionResult lastResult = status.LastResult;

Yanıt sınıfları ve IEnumerable

Kodunuzu etkileyebilecek ek bir değişiklik de, koleksiyonları barındıran yanıt sınıflarının artık uygulamasının olmamasıdır IEnumerable<T>. Bunun yerine koleksiyon özelliğine doğrudan erişebilirsiniz. Örneğin, kodunuz aşağıdaki gibi görünüyorsa:

DocumentSearchResponse<Hotel> response = indexClient.Documents.Search<Hotel>(searchText, sp);
foreach (SearchResult<Hotel> result in response)
{
    Console.WriteLine(result.Document);
}

Derleme hatalarını düzeltmek için bunu şu şekilde değiştirebilirsiniz:

DocumentSearchResult<Hotel> response = indexClient.Documents.Search<Hotel>(searchText, sp);
foreach (SearchResult<Hotel> result in response.Results)
{
    Console.WriteLine(result.Document);
}

Web uygulamaları için özel durum

Arama sonuçlarını tarayıcıya göndermek için doğrudan seri hale DocumentSearchResponse getiren bir web uygulamanız varsa kodunuzu değiştirmeniz gerekir, aksi takdirde sonuçlar doğru seri hale getirilmeyecektir. Örneğin, kodunuz aşağıdaki gibi görünüyorsa:

public ActionResult Search(string q = "")
{
    // If blank search, assume they want to search everything
    if (string.IsNullOrWhiteSpace(q))
        q = "*";

    return new JsonResult
    {
        JsonRequestBehavior = JsonRequestBehavior.AllowGet,
        Data = _featuresSearch.Search(q)
    };
}

Arama sonucunun işlenmesini .Results düzeltmek için arama yanıtının özelliğini alarak bunu değiştirebilirsiniz:

public ActionResult Search(string q = "")
{
    // If blank search, assume they want to search everything
    if (string.IsNullOrWhiteSpace(q))
        q = "*";

    return new JsonResult
    {
        JsonRequestBehavior = JsonRequestBehavior.AllowGet,
        Data = _featuresSearch.Search(q).Results
    };
}

Bu tür durumları kodunuzda kendiniz aramanız gerekir; türü olduğundan JsonResult.Dataobjectderleyici sizi uyarmaz.

CloudException değişiklikleri

CloudException sınıfı ad alanından Hyak.Common ad alanına Microsoft.Rest.Azure taşındı. Ayrıca özelliği Error olarak yeniden adlandırıldı Body.

SearchServiceClient ve SearchIndexClient değişiklikleri

özelliğinin Credentials türü , olan temel sınıfına ServiceClientCredentialsdeğiştirildiSearchCredentials. veya SearchServiceClientöğesine erişmeniz SearchCredentialsSearchIndexClient gerekiyorsa lütfen yeni SearchCredentials özelliğini kullanın.

SDK'nın SearchServiceClient eski sürümlerinde ve SearchIndexClient bir HttpClient parametre alan oluşturucular vardı. Bunlar, bir HttpClientHandler ve bir nesne dizisine DelegatingHandler sahip oluşturucularla değiştirilmiştir. Bu, gerekirse HTTP isteklerini önceden işlemek için özel işleyicilerin yüklenmesini kolaylaştırır.

Son olarak, ve UriSearchCredentials alan oluşturucular değişmiştir. Örneğin, şuna benzer bir kodunuz varsa:

var client =
    new SearchServiceClient(
        new SearchCredentials("abc123"),
        new Uri("http://myservice.search.windows.net"));

Derleme hatalarını düzeltmek için bunu şu şekilde değiştirebilirsiniz:

var client =
    new SearchServiceClient(
        new Uri("http://myservice.search.windows.net"),
        new SearchCredentials("abc123"));

Ayrıca credentials parametresinin türünün olarak değiştirildiğini ServiceClientCredentialsunutmayın. bu, kodunuz'dan ServiceClientCredentialstüretildiğinden kodunuzu SearchCredentials etkileme olasılığı düşüktür.

İstek kimliğini geçirme

SDK'nın eski sürümlerinde, veya SearchIndexClient üzerinde SearchServiceClient bir istek kimliği ayarlayabilirsiniz ve bu kimlik REST API'ye yapılan her isteğe dahil edilebilir. Bu, desteğe başvurmanız gerekiyorsa arama hizmetinizle ilgili sorunları gidermek için yararlıdır. Ancak, tüm işlemler için aynı kimliği kullanmak yerine her işlem için benzersiz bir istek kimliği ayarlamak daha yararlıdır. Bu nedenle ve SetClientRequestIdSearchIndexClient yöntemleri SearchServiceClient kaldırılmıştır. Bunun yerine, isteğe bağlı SearchRequestOptions parametresi aracılığıyla her işlem yöntemine bir istek kimliği geçirebilirsiniz.

Not

SDK'nın gelecek bir sürümünde, diğer Azure SDK'ları tarafından kullanılan yaklaşımla tutarlı istemci nesnelerinde genel olarak bir istek kimliği ayarlamak için yeni bir mekanizma ekleyeceğiz.

Örnek

Aşağıdakine benzer bir kodunuz varsa:

client.SetClientRequestId(Guid.NewGuid());
...
long count = client.Documents.Count();

Derleme hatalarını düzeltmek için bunu şu şekilde değiştirebilirsiniz:

long count = client.Documents.Count(new SearchRequestOptions(requestId: Guid.NewGuid()));

Arabirim adı değişiklikleri

İşlem grubu arabirim adlarının tümü karşılık gelen özellik adlarıyla tutarlı olacak şekilde değiştirildi:

türü ISearchServiceClient.Indexes olarak yeniden adlandırıldı IIndexOperationsIIndexesOperations.
türü ISearchServiceClient.Indexers olarak yeniden adlandırıldı IIndexerOperationsIIndexersOperations.
türü ISearchServiceClient.DataSources olarak yeniden adlandırıldı IDataSourceOperationsIDataSourcesOperations.
türü ISearchIndexClient.Documents olarak yeniden adlandırıldı IDocumentOperationsIDocumentsOperations.

Test amacıyla bu arabirimlerin sahtelerini oluşturmadığınız sürece bu değişikliğin kodunuzu etkileme olasılığı düşüktür.

Sürüm 1.1'de hata düzeltmeleri

Azure Search .NET SDK'sının özel model sınıflarının seri hale getirilmesiyle ilgili eski sürümlerinde bir hata oluştu. Hata, boş değer atanamayan bir değer türünün özelliğiyle özel bir model sınıfı oluşturduysanız oluşabilir.

Yeniden oluşturma adımları

Boş değer atanamayan değer türünde bir özelliğe sahip özel bir model sınıfı oluşturun. Örneğin, yerine int?türünde int bir ortak UnitCount özellik ekleyin.

Bir belgenin dizinini bu türdeki varsayılan değerle (örneğin, için int0) oluşturursanız, Azure Search'te alan null olur. Daha sonra bu belgeyi ararsanız, Search çağrı dönüştürülemediğini nullintbelirten bir şikayet oluştururJsonSerializationException.

Ayrıca, hedeflenen değer yerine dizine null yazıldığı için filtreler beklendiği gibi çalışmayabilir.

Düzeltme ayrıntıları

Bu sorunu SDK'nın 1.1 sürümünde düzeltildi. Şimdi, aşağıdaki gibi bir model sınıfınız varsa:

public class Model
{
    public string Key { get; set; }

    public int IntValue { get; set; }
}

ve 0 olarak ayarladığınızda IntValue , bu değer artık kabloda doğru şekilde 0 olarak seri hale getirilir ve dizinde 0 olarak depolanır. Yuvarlama da beklendiği gibi çalışır.

Bu yaklaşımda dikkate alınması gereken olası bir sorun vardır: Null değer atanamayan bir özelliğe sahip bir model türü kullanıyorsanız, dizininizdeki hiçbir belgenin karşılık gelen alan için null değer içermediğini garanti etmeniz gerekir. Sdk veya Azure Search REST API'si bunu zorunlu kılmanıza yardımcı olmaz.

Bu yalnızca kuramsal bir sorun değildir: Var olan Edm.Int32 türünde bir dizine yeni bir alan eklediğiniz bir senaryoyu düşünün. Dizin tanımını güncelleştirdikten sonra, tüm belgelerin bu yeni alan için boş bir değeri olur (bunun nedeni, Azure Search'te tüm türlerin boş değer atanabilir olmasıdır). Ardından bu alan için boş değer atanamayan bir int özelliğiyle bir model sınıfı kullanırsanız belgeleri almaya çalışırken bunun gibi bir JsonSerializationException alırsınız:

Error converting value {null} to type 'System.Int32'. Path 'IntValue'.

Bu nedenle, yine de en iyi uygulama olarak model sınıflarınızda null atanabilir türler kullanmanızı öneririz.

Bu hata ve düzeltme hakkında daha fazla ayrıntı için lütfen GitHub'da bu soruna bakın.

Aracılığıyla paylaş

Azure Search .NET SDK sürüm 1.1'e yükseltme

Sürüm 1.1'deki hataya neden olan değişikliklerin listesi

IndexBatch ve IndexAction değişiklikleri

Örnek

IndexBatchException değişiklikleri

Örnek

İşlem yöntemi değişiklikleri

ScoringParameters değişiklikleri

Örnek

Model sınıfı değişiklikleri

Örnek

Yanıt sınıfları ve IEnumerable

Web uygulamaları için özel durum

CloudException değişiklikleri

SearchServiceClient ve SearchIndexClient değişiklikleri

İstek kimliğini geçirme

Örnek

Arabirim adı değişiklikleri

Sürüm 1.1'de hata düzeltmeleri

Yeniden oluşturma adımları

Düzeltme ayrıntıları

Ek kaynaklar