Azure Search .NET SDK sürüm 9'a yükseltme

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

Daha genel bir SDK kılavuzu, örnekler de dahil olmak üzere, için bkz. .NET Uygulamasından Azure Search'ü Kullanma.

Azure Search .NET SDK'sının 9. sürümü, önceki sürümlerden birçok değişiklik içerir. Bunların bazıları önemli değişikliklerdir, ancak bunlar yalnızca kodunuzda nispeten küçük değişiklikler gerektirir. Kodunuzu yeni SDK sürümünü kullanacak şekilde değiştirme yönergeleri için bkz. yükseltme adımları.

Sürüm 9'daki yenilikler

Azure Search .NET SDK'sının 9. sürümü, aşağıdaki özelliklerle Azure Search REST API'sinin 2019-05-06 sürümünü hedefler:

• yapay zeka zenginleştirme görüntülerden, bloblardan ve diğer yapılandırılmamış veri kaynaklarından metin ayıklama özelliğidir ve içeriği zenginleştirerek Azure Search dizininde daha aranabilir olmasını sağlar.
• karmaşık tür desteği, Azure Search dizinindeki neredeyse tüm iç içe JSON yapılarını modellemenizi sağlar.
• Otomatik Tamamlama, yazdıkça arama davranışını uygulamak için Öneri API'sine bir alternatif sağlar. Otomatik tamamlama, kullanıcının şu anda yazmakta olduğu sözcüğü veya tümceciği "tamamlar".
• JsonLines ayrıştırma modu, blob dizinlemenin bir parçası olarak, yeni bir satırla ayrılmış her JSON varlığı için bir arama belgesi oluşturur.

Sürüm 8.0-preview'daki yeni önizleme özellikleri

Azure Search .NET SDK'sının sürüm 8.0-önizlemesi, API'nin 2017-11-11-Preview sürümünü hedefler. Bu sürüm, sürüm 9'un tüm özelliklerine ek olarak şunları içerir:

• Hizmet tarafında bekleyen şifreleme için müşteri tarafından yönetilen şifreleme anahtarları yeni bir önizleme özelliğidir. Microsoft tarafından yönetilen yerleşik durumda şifrelemeye ek olarak, anahtarların tek sahibi olduğunuz bir ek şifreleme katmanı uygulayabilirsiniz.

Yükseltme adımları

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

NuGet yeni paketleri ve bağımlılıklarını indirdikten sonra projenizi yeniden derleyin. Kodunuzun nasıl yapılandırıldığına bağlı olarak başarıyla yeniden oluşturulabilir. Öyleyse, başlamaya hazırsınız!

Derlemeniz başarısız olursa her derleme hatasını düzeltmeniz gerekir. Olası derleme hatalarının nasıl çözüleceğiyle ilgili ayrıntılar için sürüm 9'daki Önemli değişikliklere bakın.

Eski yöntemler veya özelliklerle ilgili ek derleme uyarıları görebilirsiniz. Uyarılar, kullanım dışı bırakılan özellik yerine nelerin kullanılacağına ilişkin yönergeler içerir. Örneğin, uygulamanız DataSourceType.DocumentDb özelliğini kullanıyorsa, "Bu üye kullanım dışı bırakıldı" diyen bir uyarı almanız gerekir. Bunun yerine CosmosDb kullanın".

Derleme hatalarını veya uyarılarını düzeltdikten sonra, isterseniz yeni işlevlerden yararlanmak için uygulamanızda değişiklikler yapabilirsiniz. SDK'daki yeni özellikler sürüm 9'daki yenilikler bölümünde ayrıntılı olarak açıklandı.

Sürüm 9'da hataya neden olan değişiklikler

Sürüm 9'da, uygulamanızı yeniden derlemenin yanı sıra kod değişiklikleri yapmanızı gerektirebilecek birkaç önemli değişiklik bulunmaktadır.

Sabit özellikler

Bazı model sınıflarının genel özellikleri artık sabittir. Test için bu sınıfların özel örneklerini oluşturmanız gerekiyorsa, yeni parametreli oluşturucuları kullanabilirsiniz:

• AutocompleteItem
• DocumentSearchResult
• DocumentSuggestResult
• FacetResult
• SearchResult
• SuggestResult

Alanda Yapılan Değişiklikler

Field sınıfı artık karmaşık alanları da temsil ebildiği için değişmiştir.

Aşağıdaki bool özellikleri artık null atanabilir:

• IsFilterable
• IsFacetable
• IsSearchable
• IsSortable
• IsRetrievable
• IsKey

Bunun nedeni, karmaşık alanlar söz konusu olduğunda bu özelliklerin artık null olması gerekir. Bu özellikleri okuyan kodunuz varsa, nullişlemeye hazır olması gerekir. Field'ın diğer tüm özelliklerinin her zaman null olabildiğini ve olmaya devam ettiğini ve karmaşık alanlar söz konusu olduğunda bunların bazılarının da null olacağını unutmayın, özellikle aşağıdakiler:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

Field'ın parametresiz yapıcısı internalyapılmıştır. Bundan böyle her Field, oluşturulurken mutlaka belirgin bir ad ve veri türü gerektirir.

Basitleştirilmiş toplu iş ve sonuç türleri

Sürüm 7.0-önizleme ve önceki sürümlerde, belge gruplarını kapsülleyen çeşitli sınıflar paralel sınıf hiyerarşileri halinde yapılandırılmıştı:

• DocumentSearchResult ve DocumentSearchResult<T>, DocumentSearchResultBase'den miras aldılar
• DocumentSuggestResult ve DocumentSuggestResult<T>, DocumentSuggestResultBase'den miras aldılar
• IndexAction ve IndexAction<T>, IndexActionBase'den miras aldılar
• IndexBatch ve IndexBatch<T>, IndexBatchBase'den miras aldılar
• SearchResult ve SearchResult<T>, SearchResultBase'den miras aldılar
• SuggestResult ve SuggestResult<T>, SuggestResultBase'den miras aldılar

Genel tür parametresi olmayan türetilmiş türlerin "dinamik olarak yazılan" senaryolarda kullanılması ve Document türünün kullanımı varsayılması amaçlanmıştır.

Sürüm 8.0-önizleme sürümünden itibaren temel sınıfların ve genel olmayan türetilmiş sınıfların tümü kaldırılmıştır. Dinamik olarak yazılan senaryolar için IndexBatch<Document>, DocumentSearchResult<Document>vb. kullanabilirsiniz.

GenişletilebilirEnum kaldırıldı

ExtensibleEnum temel sınıfı kaldırıldı. Bundan türetilen tüm sınıflar artık AnalyzerName, DataTypeve örneğin DataSourceType gibi yapılardır. Bunların Create yöntemleri de kaldırılmıştır. Yalnızca Create çağrılarını kaldırabilirsiniz çünkü bu türler string'lerden örtük olarak dönüştürülebilir. Bu, derleyici hatalarıyla sonuçlanırsa, dönüştürme işlecini türlerde ayrım yaparak açıkça çağırabilirsiniz. Örneğin, kodu şu şekilde değiştirebilirsiniz:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", AnalyzerName.Create("my_email_analyzer")) { IsSearchable = true }
    },
    ...
}

buna:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", (AnalyzerName)"my_email_analyzer") { IsSearchable = true }
    },
    ...
}

Bu türlerin isteğe bağlı değerlerini tutan özellikler, artık açıkça "null" atanabilir olarak tanımlandığından, isteğe bağlı olmaya devam ederler.

FacetResults ve HitHighlights kaldırıldı

FacetResults ve HitHighlights sınıfları kaldırıldı. Yüzey sonuçları artık IDictionary<string, IList<FacetResult>> ve vurgu özeti olarak IDictionary<string, IList<string>>olarak adlandırılıyor. Bu değişiklikle ortaya çıkan derleme hatalarını hızlıca çözmenin bir yolu, kaldırılan türleri kullanan her dosyanın en üstüne using adlar eklemektir. Örneğin:

using FacetResults = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<Models.FacetResult>>;
using HitHighlights = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<string>>;

SynonymMap olarak değiştirme

SynonymMap oluşturucusunun artık enumiçin bir SynonymMapFormat parametresi yoktur. Bu numaralandırma yalnızca bir değere sahipti ve bu nedenle gereksizdi. Bunun sonucunda derleme hataları görürseniz, SynonymMapFormat parametresine olan referansları kaldırmanız yeterlidir.

Çeşitli model sınıfı değişiklikleri

AutocompleteMode AutocompleteParameters özelliği artık null edilebilir değil. Bu özelliği nullatayan kodunuz varsa, bunu kaldırmanız yeterlidir ve özellik otomatik olarak varsayılan değere başlatılır.

IndexAction oluşturucusunun parametrelerinin sırası, bu oluşturucu artık otomatik olarak oluşturulduğu için değişti. Oluşturucuyu kullanmak yerine, IndexAction.Upload, IndexAction.Mergeve benzeri fabrika yöntemlerini kullanmanızı öneririz.

Önizleme özellikleri kaldırıldı

Sürüm 8.0-preview'dan sürüm 9'a yükseltiyorsanız, bu özellik hala önizleme aşamasında olduğundan müşteri tarafından yönetilen anahtarlarla şifrelemenin kaldırıldığını unutmayın. Özellikle, EncryptionKey ve Index'nin SynonymMap özellikleri kaldırılmıştır.

Uygulamanızın bu özelliğe sıkı bir bağımlılığı varsa Azure Search .NET SDK'sının 9. sürümüne yükseltemezsiniz. 8.0-preview sürümünü kullanmaya devam edebilirsiniz. Ancak, üretim uygulamalarında önizleme SDK'larının kullanılmasını önermeyebileceğimizi unutmayın. Önizleme özellikleri yalnızca değerlendirme amaçlıdır ve değişebilir.

Veri almada davranış değişikliği

Eğer türü (Document) olan örnekleri döndüren "dinamik olarak yazılan" Search, Suggest veya Get API'lerini kullanıyorsanız, artık boş JSON dizilerini string[] yerine object[] olarak seri durumdan çıkardıklarını unutmayın.

Sonuç

Azure Search .NET SDK'sini kullanma hakkında daha fazla ayrıntıya ihtiyacınız varsa .NET Nasıl Yapılırbölümüne bakın.

SDK ile ilgili geri bildirimlerinizi bekliyoruz. Sorunlarla karşılaşırsanız, Stack Overflowhakkında yardım isteyebilirsiniz. Bir hata bulursanız, Azure .NET SDK GitHub deposunda bir sorun bildirebilirsiniz. Sorun başlığınıza "[Azure Search]" ön ekini eklemeyi unutmayın.

Azure Search'i kullandığınız için teşekkür ederiz!