Mengembangkan handler properti untuk Windows Search

Microsoft Windows Search menggunakan penangan properti untuk mengekstrak nilai properti dari item dan menggunakan skema sistem properti untuk menentukan bagaimana properti tertentu harus diindeks. Untuk membaca dan mengindeks nilai properti, handler properti dipanggil di luar proses oleh Windows Search untuk meningkatkan keamanan dan ketahanan. Sebaliknya, handler properti dipanggil dalam prosesnya oleh Windows Explorer untuk membaca dan menulis nilai properti.

Topik ini melengkapi topik Sistem Properti dengan informasi khusus untuk Windows Search dan berisi bagian berikut:

• Keputusan tentang Desain untuk Pengelola Properti
  • Keputusan Properti
  • DukunganFull-Text
  • Pertimbangan Implementasi Sistem Operasi
• Menulis File Deskripsi Properti
• Menerapkan handler properti
  • IInitializeWithStream
  • IPropertyStore
  • IPropertyStoreCapabilities
• Memastikan Item Anda Diindekskan
• Menginstal dan Mendaftarkan Handler Properti
• Pengujian dan Pemecahan Masalah Penanganan Properti
  • Pengujian Instalasi dan Penyiapan
  • Pemecahan Masalah Penangan Properti
• Menggunakan System-Supplied Handler Properti
• Topik terkait

Keputusan desain untuk penanganan properti

Menerapkan handler properti melibatkan langkah-langkah berikut:

1. Membuat keputusan desain mengenai properti yang ingin Anda dukung.
2. Membuat file Deskripsi Properti (.propdesc) untuk properti yang belum ada dalam sistem properti.
3. Menerapkan dan menguji handler properti.
4. Menginstal dan mendaftarkan pengelola properti dan file deskripsi properti.
5. Menguji penginstalan dan pendaftaran handler properti.

Sebelum memulai, Anda perlu mempertimbangkan pertanyaan desain berikut:

• Properti apa yang didukung/harus didukung format file?
• Apakah properti ini sudah ada dalam skema Sistem?
• Dapatkah saya menggunakan handler properti yang disediakan sistem yang ada?
• Properti mana yang dapat ditampilkan kepada pengguna akhir?
• Properti mana yang dapat diedit pengguna?
• Haruskah dukungan untuk pencarian teks lengkap berasal dari handler properti atau filter?
• Apakah saya perlu mendukung aplikasi warisan? Jika demikian, apa yang harus saya terapkan?

Setelah membuat keputusan ini, Anda dapat menulis deskripsi formal properti kustom Anda sehingga mesin Windows Search dapat mulai mengindeks file dan properti Anda. Deskripsi formal ini adalah file XML, yang dijelaskan dalam Skema Deskripsi Properti .

Keputusan properti

Saat mempertimbangkan properti mana yang akan didukung, Anda harus mengidentifikasi kebutuhan pengindeksan dan pencarian pengguna Anda. Misalnya, Anda mungkin dapat mengidentifikasi seratus properti yang berpotensi berguna untuk jenis file Anda, tetapi pengguna mungkin tertarik untuk mencari hanya segelintir. Selain itu, Anda mungkin ingin menampilkan yang berbeda, lebih besar atau lebih kecil, grup properti tersebut kepada pengguna di Windows Explorer, dan memungkinkan pengguna untuk mengedit hanya subset properti yang ditampilkan.

Jenis file Anda dapat mendukung properti kustom apa pun yang Anda tentukan, serta sekumpulan properti yang ditentukan sistem. Sebelum Anda membuat properti kustom, silakan tinjau Properti Sistem untuk melihat apakah properti yang ingin Anda dukung sudah ditentukan oleh properti sistem. Selalu pastikan Anda mendukung properti yang paling penting yang ditentukan sistem.

Sebaiknya gunakan matriks untuk membantu Anda merancang properti Anda:

Untuk setiap properti ini, Anda perlu menentukan atribut apa yang harus dimilikinya lalu menjelaskannya secara formal dalam file XML Deskripsi Properti (.propdesc). Atribut mencakup jenis data properti, label, string bantuan, dan lainnya. Untuk properti yang dapat diindeks, Anda harus memberikan perhatian khusus pada atribut properti berikut yang ditemukan di elemen searchInfo XML dari file Deskripsi Properti.

Dukungan teks lengkap

Secara umum, pencarian teks lengkap didukung oleh komponen yang disebut filter ; namun, untuk jenis file berbasis teks dengan format file yang tidak rumit, handler properti mungkin dapat menyediakan fungsionalitas ini dengan lebih sedikit upaya pengembangan. Anda harus meninjau bagian Full-Text Konten untuk perbandingan fungsionalitas filter dan pengelola properti guna membantu Anda memutuskan apa yang terbaik untuk jenis file Anda. Hal yang sangat penting adalah bahwa filter dapat menangani beberapa pengidentifikasi kode bahasa (LCID) per file, sedangkan penangan properti tidak dapat.

Pertimbangan implementasi sistem operasi

Informasi implementasi untuk Windows 7

Di Windows 7 dan yang lebih baru, ada perilaku baru saat mendaftarkan handler properti, IFilter, atau ekstensi baru. Ketika handler properti baru dan/atau IFilter diinstal, file dengan ekstensi yang sesuai secara otomatis diindeks ulang.

Di Windows 7 disarankan agarIFilterdiinstal bersama dengan handler properti yang sesuai, dan bahwa IFilter didaftarkan sebelum handler properti. Pendaftaran handler properti memulai pengindeksan ulang segera dari file yang diindeks sebelumnya tanpa terlebih dahulu memerlukan boot ulang, dan memanfaatkan IFilter yang terdaftar sebelumnya untuk tujuan pengindeksan konten.

Jika hanya IFilter yang diinstal, tanpa handler properti yang sesuai, pengindeksan ulang otomatis terjadi baik setelah mulai ulang layanan pengindeksan, atau boot ulang sistem.

Untuk bendera deskripsi properti khusus untuk Windows 7, lihat topik referensi berikut:

• GETPROPERTYSTOREFLAGS
• PROPDESC_COLUMNINDEX_TYPE
• PROPDESC_SEARCHINFO_FLAGS

Informasi implementasi untuk Windows Vista dan yang lebih lama

Sebelum Windows Vista, filter memberikan dukungan untuk mengurai dan menghitung konten file dan properti. Dengan pengenalan sistem properti, penangan properti menangani properti file saat filter menangani konten file. Untuk Windows Vista, Anda hanya perlu mengembangkan implementasi parsial antarmuka IFilterdalam koordinasi dengan handler properti, seperti yang dijelaskan dalam Praktik Terbaik untuk membuat Handler Filter di Windows Search.

Walaupun sistem properti sudah termasuk dalam instalasi Windows Search untuk Windows XP, aplikasi pihak ketiga dan aplikasi lama mungkin mengharuskan filter untuk menangani baik konten maupun properti. Oleh karena itu, jika Anda mengembangkan pada platform Windows XP, Anda harus memberikan implementasi filter lengkap serta handler properti untuk jenis file atau properti kustom Anda.

Penulisan file deskripsi properti

Struktur file XML deskripsi properti (.propdesc) dijelaskan dalam topik propertyDescription . Yang menjadi minat khusus dalam pencarian adalah atribut dari elemen searchInfo. Setelah memutuskan properti mana yang akan didukung, Anda perlu membuat dan mendaftarkan file deskripsi properti untuk setiap properti. Saat Anda mendaftarkan file .propdesc, file tersebut disertakan dalam daftar deskripsi properti skema dan menjadi nama kolom dalam penyimpanan properti Mesin pencari.

Anda dapat mendaftarkan deskripsi properti kustom Anda menggunakan fungsi PSRegisterPropertySchema, API pembungkus yang memanggil subsistem skema milik IPropertySystem::RegisterPropertySchema. Fungsi ini memberitahu subsistem skema tentang penambahan file skema deskripsi properti (.propdesc), menggunakan jalur ke file .propdesc di komputer lokal, biasanya di direktori tempat aplikasi diinstal di bawah "Program Files". Biasanya, penyiapan atau aplikasi (misalnya, penginstal handler properti Anda) akan memanggil metode ini setelah menginstal file .propdesc.

Menerapkan handler properti

Mengembangkan handler properti melibatkan penerapan antarmuka berikut:

• IInitialzeWithStream: Menyediakan inisialisasi berbasis stream untuk handler properti Anda.
• IPropertyStore: Menghitung, mendapatkan, dan menetapkan nilai properti.
• IPropertyStoreCapabilities: Opsional. Mengidentifikasi apakah pengguna dapat mengedit properti dari antarmuka pengguna.

IInitializeWithStream

Seperti yang dijelaskan dalam topik Sistem Properti, kami sangat menyarankan untuk mengimplementasikan pengendali properti dengan IInitializeWithStream untuk melakukan inisialisasi berbasis aliran. Jika Anda memilih untuk tidak menerapkan IInitializeWithStream, handler properti harus memilih untuk tidak berjalan dalam proses isolasi dengan mengatur bendera DisableProcessIsolation pada kunci registri handler properti. Menonaktifkan isolasi proses umumnya hanya ditujukan untuk penangan properti lama dan harus sangat dihindari oleh kode baru apa pun.

IPropertyStore

Untuk membuat handler properti, Anda harus menerapkan antarmuka IPropertyStore dengan metode berikut.

Pertimbangan penting untuk menerapkan antarmuka ini disertakan dalam dokumentasiIPropertyStore.

IPropertyStoreCapabilities

Penangan properti dapat secara opsional mengimplementasikan antarmuka ini untuk menonaktifkan kemampuan pengguna untuk mengedit properti tertentu. Properti ini biasanya dapat diedit di halaman dan panel Detail tetapi mengeditnya tidak diizinkan di bawah handler properti penerapan. Menerapkan antarmuka ini dengan benar memberikan pengalaman pengguna yang lebih baik daripada alternatif—kesalahan run-time sederhana dari Shell.

Memastikan item Anda diindeks

Setelah Anda menerapkan handler properti Anda, pastikan item yang didaftarkan oleh handler tersebut dapat diindeks. Anda dapat menggunakan Catalog Manager untuk memulai pengindeksan ulang, dan Anda juga dapat menggunakan Crawl Scope Manager untuk menyiapkan aturan default yang menunjukkan URL yang Anda inginkan untuk dirayapi oleh Pengindeks. Opsi lain adalah mengikuti contoh kode ReIndex di Sampel Kode Pencarian Windows.

Untuk informasi lebih lanjut, lihat Menggunakan Pengelola Katalog dan Menggunakan Pengelola Ruang Lingkup Crawl.

Menginstal dan mendaftarkan handler properti

Dengan handler properti yang diimplementasikan, itu harus terdaftar dan ekstensi nama file yang terkait dengan handler. Contoh berikut menunjukkan kunci dan nilai registri yang diperlukan untuk melakukan ini.

HKEY_CLASSES_ROOT
   CLSID
      {<CLSID for property handler>}
         (Default) = <Property Handler Name>
         InProcServer32
            (Default) = <full path to property handler dll>
            ThreadingModel = <your threading model>

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows
            CurrentVersion
               PropertySystem
                  PropertyHandlers
                     <.fileextention>
                        (Default) = {<CLSID for property handler>}

Pengujian dan pemecahan masalah pengelola properti

Daftar berikut memberikan saran tentang jenis pengujian yang harus Anda lakukan:

• Uji untuk mendapatkan output dari setiap properti yang didukung oleh jenis file.
• Gunakan nilai properti besar, misalnya, gunakan metatag besar dalam dokumen HTML.
• Periksa apakah handler properti tidak membocorkan handel file dengan mengeditnya setelah mendapatkan output dari handler properti, atau dengan menggunakan alat seperti oh.exe sebelum dan sesudah menghitung properti file.
• Uji semua jenis file yang terkait dengan handler properti. Misalnya, periksa apakah filter HTML berfungsi dengan jenis file .htm dan .html.
• Uji dengan file yang rusak. Pengelola properti harus menangani kegagalan dengan baik.
• Jika aplikasi mendukung enkripsi, uji bahwa handler properti tidak menghasilkan teks terenkripsi.
• Jika handler properti Anda mendukung pencarian teks lengkap:
  • Gunakan beberapa karakter Unicode khusus dalam konten file dan uji outputnya.
  • Uji penanganan dokumen yang sangat besar untuk memastikan penangan properti bekerja seperti yang diharapkan.

Pengujian penginstalan dan penyiapan

Terakhir, Anda perlu menguji prosedur penginstalan dan penghapusan.

• Penginstalan harus pulih dari penginstalan yang gagal (misalnya, dari membatalkan lalu memulai ulang penyiapan).
• Penghapusan perangkat lunak harus menghapus semua file yang berkaitan dengan handler properti.
• Penghapusan tidak boleh menghapus file selain yang terkait dengan penginstalan handler properti.
• Kunci registri yang terkait dengan handler properti harus dihapus saat dihapus instalasinya.
• Proses pencopotan harus tetap berfungsi meskipun file dihapus dari direktori penginstalan.

Pemecahan masalah handler properti

Berikut ini adalah beberapa kesalahan umum yang dilakukan saat mengembangkan pengelola properti:

• Menginstal file .propdesc atau DLL di bawah direktori pengguna.
• Mendaftarkan komponen menggunakan jalur relatif.
• Mendaftarkan komponen di bawah HKEY_CURRENT_USER alih-alih HKEY_LOCAL_MACHINE.
• Lupa mengatur DisableProcessIsolation untuk handler non-stream.
• Menempatkan file uji di lokasi yang tidak diindeks.

Jika Anda mengalami kesulitan mengintegrasikan penangan properti dengan pengindeks, berikut adalah beberapa tips untuk membantu Anda menangani masalah:

• Pastikan bahwa deskripsi properti Anda (file.propdesc) ditandai isColumn="true", isViewable="true", dan isQueryable="true" sesuai.
• Verifikasi bahwa file .propdesc Anda berada di lokasi global.
• Verifikasi bahwa Anda mendaftarkan file .propdesc menggunakan jalur absolut.
• Verifikasi bahwa log peristiwa tidak merekam kegagalan apa pun terkait pendaftaran file .propdesc Anda.
• Verifikasi bahwa DLL Anda berada di lokasi global (dan bukan di bawah profil pengguna Anda).
• Verifikasi bahwa DLL Anda terdaftar di bawah HKEY_LOCAL_MACHINE\Software\Classes.
• Pastikan bahwa DLL Anda terregistrasi menggunakan jalur lengkap (atau string "REG_EXPAND_SZ" yang diperluas ke jalur absolut menggunakan variabel lingkungan yang diketahui oleh akun Sistem).
• Verifikasi bahwa handler properti Anda berfungsi di bawah Windows Explorer.
• Meskipun sebaiknya gunakan IInitializeWithStream, jika Anda harus menggunakan IInitializeWithFile atau IInitializeWithItem, verifikasi bahwa Anda menentukan DisableProcessIsolation.
• Verifikasi bahwa Panel Kontrol Opsi Pengindeksan mencantumkan tipe file Anda sebagai tipe file terindeks.
• Verifikasi bahwa file pengujian berada di lokasi terindeks.
• Verifikasi bahwa file pengujian telah dimodifikasi sejak Anda menginstal handler properti Anda.

Jika file pengujian Anda berada di lokasi terindeks dan pengindeks telah merayapi lokasi tersebut, Anda perlu memodifikasi file dalam beberapa cara untuk memicu pengindeksan ulang file.

Menggunakan handler properti yang disediakan sistem

Windows menyertakan sejumlah penangan properti yang disediakan sistem yang dapat Anda gunakan jika format tipe file Anda kompatibel. Jika Anda menentukan ekstensi file baru yang menggunakan salah satu format ini, Anda dapat menggunakan handler yang disediakan sistem dengan mendaftarkan pengidentifikasi kelas handler (CLSID) untuk ekstensi file Anda.

Anda dapat menggunakan CLSID yang tercantum dalam tabel berikut untuk mendaftarkan penangan properti yang disediakan sistem untuk jenis format file Anda.

Sebelum membuat properti kustom, Anda harus yakin tidak ada properti yang ditentukan sistem yang dapat Anda gunakan sebagai gantinya. Anda dapat menghitung properti yang ditentukan sistem dengan memanggil PSEnumeratePropertyDescriptions atau menggunakan alat baris perintah prop.exe.

Skema sistem menentukan bagaimana properti ini berinteraksi dengan pengindeks, dan Anda tidak dapat mengubahnya. Selain itu, aplikasi yang Anda gunakan untuk membuat, mengedit, dan menyimpan jenis file Anda juga harus sesuai dengan perilaku tertentu. Misalnya, jika aplikasi menerapkan penyimpanan aman (di mana file sementara dibuat selama pengeditan, dan kemudian ReplaceFile() digunakan untuk menukar versi baru untuk yang lama), aplikasi harus mentransfer semua properti dari file asli ke file baru. Kegagalan untuk dilakukan berarti file kehilangan properti yang ditambahkan oleh pengguna atau aplikasi lain.

Contoh

Berikut ini menunjukkan registrasi handler OLE DocFile yang disediakan sistem untuk jenis file dengan ekstensi .OLEDocFile.

HKEY_CLASSES_ROOT
   SystemFileAssociations
      .OLEDocFile
         shellex
            {BB2E617C-0920-11d1-9A0B-00C04FC2D6C1}
               (Default) = {9DBD2C50-62AD-11d0-B806-00C04FD706EC}

Berikut ini menunjukkan pendaftaran informasi daftar properti sehingga properti file .OLEDocFile ditampilkan pada tab dan panel Detail.

HKEY_CLASSES_ROOT
   SystemFileAssociations
      .OLEDocFile
         ExtendedTileInfo = prop:System.ItemType;System.Size;System.DateModified;System.Author;System.OfflineAvailability
         FullDetails = prop:System.PropGroup.Description;System.Title;System.Subject;
System.Keywords;System.Category;System.Comment;System.PropGroup.Origin;
System.Author;System.Document.LastAuthor;System.Document.RevisionNumber;
System.Document.Version;System.ApplicationName;System.Company;System.Document.Manager;
System.Document.DateCreated;System.Document.DateSaved;System.Document.DatePrinted;
System.Document.TotalEditingTime;System.PropGroup.Content;System.ContentStatus;
System.ContentType;System.Document.PageCount;System.Document.WordCount;
System.Document.CharacterCount;System.Document.LineCount;
System.Document.ParagraphCount;System.Document.Template;System.Document.Scale;
System.Document.LinksDirty;System.Language;System.PropGroup.FileSystem;
System.ItemNameDisplay;System.ItemType;System.ItemFolderPathDisplay;
System.DateCreated;System.DateModified;System.Size;System.FileAttributes;
System.OfflineAvailability;System.OfflineStatus;System.SharedWith;
System.FileOwner;System.ComputerName
         InfoTip = prop:System.ItemType;System.Size;System.DateModified;System.Document.PageCoun
         PerceivedType = document
         PreviewDetails = prop:*System.DateModified;System.Author;System.Keywords;
*System.Size;System.Title;System.Comment;System.Category;
*System.Document.PageCount;System.ContentStatus;System.ContentType;
*System.OfflineAvailability;*System.OfflineStatus;System.Subject;
*System.DateCreated;*System.SharedWith

Topik terkait

Referensi

Pemetaan Properti

Konseptual

Praktik Terbaik untuk Membuat Handler Filter di Windows Search

Proses Pengindeksan

Mengembangkan Handler Protokol

Properti System-Defined untuk Format File Kustom

Sumber Daya Lain

Sistem Properti

Properti Sistem

Sampel Kode Pencarian Windows