Tingkatkan ke Azure Search .NET SDK versi 9

Jika Anda menggunakan pratinjau versi 7.0 atau yang lebih lama dari Azure Search .NET SDK, artikel ini akan membantu Anda meningkatkan aplikasi untuk menggunakan versi 9.

Untuk panduan SDK yang lebih umum termasuk contoh, lihat Cara menggunakan Azure Search dari Aplikasi .NET.

Versi 9 dari Azure Search .NET SDK berisi banyak perubahan dari versi sebelumnya. Beberapa di antaranya melanggar perubahan, tetapi seharusnya hanya memerlukan perubahan yang relatif kecil pada kode Anda. Lihat langkah-langkah untuk meningkatkan petunjuk tentang cara mengubah kode Anda untuk menggunakan versi SDK baru.

Apa yang baru dalam versi 9

Versi 9 dari Azure Search .NET SDK menargetkan Azure Search REST API versi 2019-05-06, dengan fitur berikut:

• Pengayaan AI adalah kemampuan untuk mengekstrak teks dari gambar, blob, dan sumber data tidak terstruktur lainnya - memperkaya konten untuk membuatnya lebih mudah dicari dalam indeks Azure Search.
• Dukungan untuk jenis kompleks memungkinkan Anda memodelkan hampir semua struktur JSON berlapis dalam indeks Azure Search.
• Pelengkapan otomatis menyediakan alternatif untuk Suggest API untuk menerapkan pencarian saat Anda mengetik. Pelengkapan otomatis "melengkapi" kata atau frasa yang sedang diketik oleh pengguna.
• Mode penguraian JsonLines, bagian dari pengindeksan blob, membuat satu dokumen pencarian per entitas JSON yang dipisahkan oleh baris baru.

Fitur pratinjau baru di versi 8.0-preview

Pratinjau versi 8.0 dari Azure Search .NET SDK menargetkan API versi 2017-11-11-Preview. Versi ini mencakup semua fitur yang sama dari versi 9, ditambah:

• Kunci enkripsi yang dikelola pelanggan untuk enkripsi sisi layanan tidak aktif adalah fitur pratinjau baru. Selain enkripsi bawaan saat istirahat yang dikelola oleh Microsoft, Anda dapat menerapkan lapisan enkripsi tambahan di mana Anda adalah pemilik satu-satunya kunci.

Langkah-langkah untuk peningkatan

Pertama, perbarui referensi NuGet Anda untuk Microsoft.Azure.Search menggunakan Konsol Manajer Paket NuGet atau dengan mengklik kanan referensi proyek Anda dan memilih "Kelola Paket NuGet..." di Visual Studio.

Setelah NuGet mengunduh paket baru dan dependensinya, bangun kembali proyek Anda. Bergantung pada bagaimana kode Anda disusun, kode tersebut mungkin berhasil dibangun kembali. Jika demikian, Anda siap untuk pergi!

Jika build Anda gagal, Anda perlu memperbaiki setiap kesalahan tersebut. Lihat Perubahan yang melanggar kompatibilitas di versi 9 untuk melihat detail tentang cara mengatasi setiap potensi kesalahan build.

Anda mungkin melihat peringatan build tambahan yang terkait dengan metode atau properti usang. Peringatan akan mencakup instruksi tentang apa yang harus digunakan alih-alih fitur yang tidak digunakan lagi. Misalnya, jika aplikasi Anda menggunakan properti DataSourceType.DocumentDb, Anda harus mendapatkan peringatan yang mengatakan "Anggota ini sudah usang." Gunakan CosmosDb sebagai gantinya".

Setelah memperbaiki kesalahan atau peringatan build, Anda dapat membuat perubahan pada aplikasi untuk memanfaatkan fungsionalitas baru jika mau. Fitur baru di SDK dirinci dalam Apa yang baru dalam versi 9.

Memutus perubahan dalam versi 9

Ada beberapa perubahan mendasar dalam versi 9 yang mungkin memerlukan perubahan kode, selain itu juga mengonfigurasi ulang aplikasi Anda.

Properti yang tidak dapat diubah

Properti publik dari beberapa kelas model sekarang tidak dapat berubah. Jika Anda perlu membuat instans kustom kelas ini untuk pengujian, Anda dapat menggunakan konstruktor parameter baru:

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

Perubahan pada Bidang

Kelas Field sekarang telah berubah karena juga dapat mewakili bidang yang kompleks.

Properti berikut bool ini sekarang dapat diubah ke null:

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

Ini karena properti ini sekarang harus null dalam kasus bidang kompleks. Jika Anda memiliki kode yang membaca properti ini, ia harus siap untuk menangani null. Perhatikan bahwa semua properti Field lainnya selalu dan terus dapat bernilai null, dan beberapa di antaranya juga akan menjadi null dalam kasus bidang kompleks -- khususnya yang berikut ini:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

Konstruktor Field tanpa parameter telah dibuat internal. Mulai sekarang, setiap Field memerlukan nama eksplisit dan jenis data pada saat konstruksi.

Tipe batch yang disederhanakan dan tipe hasil

Dalam pratinjau versi 7.0 dan versi-versi sebelumnya, berbagai kelas yang membungkus grup dokumen disusun menjadi hierarki kelas paralel.

• DocumentSearchResult dan DocumentSearchResult<T> diwariskan dari DocumentSearchResultBase
• DocumentSuggestResult dan DocumentSuggestResult<T> diwariskan dari DocumentSuggestResultBase
• IndexAction dan IndexAction<T> diwariskan dari IndexActionBase
• IndexBatch dan IndexBatch<T> diwariskan dari IndexBatchBase
• SearchResult dan SearchResult<T> diwariskan dari SearchResultBase
• SuggestResult dan SuggestResult<T> diwariskan dari SuggestResultBase

Tipe turunan tanpa parameter tipe generik dimaksudkan untuk digunakan dalam skenario "bertipedinamika" dan di mana penggunaan tipe Document diasumsikan.

Dimulai dengan pratinjau versi 8.0, kelas dasar dan kelas turunan non-generik semuanya telah dihapus. Untuk skenario yang ditik secara dinamis, Anda dapat menggunakan IndexBatch<Document>, DocumentSearchResult<Document>, dan sebagainya.

Dihapus ExtensibleEnum

Kelas ExtensibleEnum dasar telah dihapus. Semua kelas yang berasal darinya sekarang adalah struktur, seperti AnalyzerName, , DataTypedan DataSourceType misalnya. Metode mereka Create juga telah dihapus. Anda hanya dapat menghapus panggilan ke Create karena jenis ini secara implisit dapat dikonversi dari string. Jika itu menghasilkan kesalahan kompilasi, Anda dapat secara eksplisit memanggil operator konversi melalui casting untuk memperjelas tipe. Misalnya, Anda dapat mengubah kode seperti ini:

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

untuk yang ini:

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

Properti yang menyimpan nilai opsional dari jenis ini sekarang secara eksplisit diketik sebagai nullable agar tetap bersifat opsional.

FacetResults dan HitHighlights Telah Dihapus

Kelas FacetResults dan HitHighlights telah dihapus. Hasil faset sekarang di ketik sebagai IDictionary<string, IList<FacetResult>> dan tekan sorotan sebagai IDictionary<string, IList<string>>. Cara cepat untuk mengatasi kesalahan build yang diperkenalkan oleh perubahan ini adalah dengan menambahkan using alias di bagian atas setiap file yang menggunakan jenis yang dihapus. Contohnya:

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

Ganti ke SynonymMap

Konstruktor SynonymMap tidak lagi memiliki parameter enum untuk SynonymMapFormat. Enum ini hanya memiliki satu nilai, dan oleh karena itu berlebihan. Jika Anda melihat kesalahan build sebagai akibat dari ini, cukup hapus referensi ke parameter SynonymMapFormat.

Perubahan kelas model lain-lain

Properti AutocompleteMode dari AutocompleteParameters tidak lagi dapat bernilai null. Jika Anda memiliki kode yang menetapkan properti ini ke null, Anda cukup menghapusnya dan properti akan secara otomatis diinisialisasi ke nilai default.

Urutan parameter ke IndexAction konstruktor telah berubah sekarang karena konstruktor ini dibuat secara otomatis. Alih-alih menggunakan konstruktor, sebaiknya gunakan metode pabrik seperti IndexAction.Upload, IndexAction.Merge, dan sebagainya.

Fitur pratinjau yang dihapus

Jika Anda meningkatkan dari versi 8.0-pratinjau ke versi 9, ketahuilah bahwa enkripsi dengan kunci yang dikelola pelanggan telah dihapus karena fitur ini masih dalam pratinjau. Secara khusus, properti EncryptionKey dari Index dan SynonymMap telah dihapus.

Jika aplikasi Anda memiliki dependensi keras pada fitur ini, Anda tidak akan dapat meningkatkan ke versi 9 dari Azure Search .NET SDK. Anda dapat terus menggunakan versi 8.0-preview. Namun, perlu diingat bahwa kami tidak merekomendasikan penggunaan SDK pratinjau dalam aplikasi produksi. Fitur pratinjau hanya untuk evaluasi dan dapat berubah.

Perubahan perilaku dalam pengambilan data

Jika Anda menggunakan "pengolahan tipe dinamis" Search, Suggest, atau Get API yang mengembalikan instans jenis Document, ketahuilah bahwa mereka sekarang melakukan deserialisasi array JSON kosong ke object[] alih-alih string[].

Kesimpulan

Jika Anda memerlukan detail lebih lanjut tentang cara menggunakan Azure Search .NET SDK, lihat panduan cara .NET .

Kami menyambut umpan balik Anda tentang SDK. Jika Anda mengalami masalah, jangan ragu untuk meminta bantuan kami pada Stack Overflow. Jika Anda menemukan bug, Anda dapat mengajukan masalah di repositori GitHub SDK .NET Azure. Pastikan untuk memulai judul masalah Anda dengan "[Azure Search]".

Terima kasih telah menggunakan Azure Search!