Bagikan melalui


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 proses 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 Desain untuk Penangan 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 penangan 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?

Catatan

Sebelum melanjutkan, lihat Menggunakan Penangan Properti yang Disediakan Sistem untuk melihat apakah Anda dapat menggunakan handler properti yang disediakan sistem, menghemat waktu dan sumber daya pengembangan Anda.

 

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:

Nama properti Apakah dapat diindeks? Apakah dapat ditampilkan? Apakah dapat diedit?
property1 Y Y N
Properti... Y Y N
propertyn N N N

 

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 XML searchInfo dari file Deskripsi Properti.

Atribut Deskripsi
inInvertedIndex Opsional. Menunjukkan apakah nilai properti string harus dipecah menjadi kata-kata dan setiap kata yang disimpan dalam indeks terbalik. Indeks terbalik memungkinkan pencarian kata dan frasa yang efisien atas nilai properti menggunakan CONTAINS atau FREETEXT (misalnya, SELECT ... WHERE CONTAINS "sometext"). Jika diatur ke FALSE, pencarian dilakukan terhadap seluruh string. Sebagian besar properti string harus mengatur ini ke TRUE; properti non-string harus mengatur ini ke FALSE. Defaultnya adalah FALSE.
isColumn Opsional. Menunjukkan apakah properti harus disimpan dalam database Pencarian Windows sebagai kolom. Menyimpan properti sebagai kolom memungkinkan pengambilan, pengurutan, pengelompokan, dan pemfilteran (yaitu, menggunakan predikat apa pun kecuali CONTAINS atau FREETEXT) pada seluruh nilai kolom. Properti yang ditampilkan kepada pengguna harus mengatur ini ke TRUE kecuali properti tekstual yang sangat besar (seperti isi dokumen) yang akan dicari dalam indeks terbalik. Defaultnya adalah FALSE.
isColumnSparse Opsional. Menunjukkan apakah properti tidak membutuhkan spasi jika nilainya NULL. Properti non-jarang membutuhkan ruang untuk setiap item, bahkan jika nilainya ADALAH NULL. Jika properti multinilai, atribut ini selalu TRUE. Atribut ini harus FALSE hanya jika ada nilai untuk setiap item. Defaultnya adalah TRUE.
columnIndexType Opsional. Untuk mengoptimalkan kueri, mesin Windows Search dapat membuat indeks sekunder untuk properti yang memiliki isColumn=TRUE. Ini membutuhkan lebih banyak pemrosesan dan ruang disk selama pengindeksan, tetapi meningkatkan performa selama kueri. Jika properti cenderung diurutkan, dikelompokkan, atau difilter (yaitu, menggunakan =, !=, <, >, LIKE, MATCHES) sering oleh pengguna, atribut ini harus diatur ke "OnDisk". Defaultnya adalah "NotIndexed". Nilai berikut ini valid:
  • NotIndexed: Tidak ada indeks sekunder yang dibuat.
  • OnDisk: Membuat dan menyimpan indeks sekunder pada disk.
maxSize Opsional. Menunjukkan ukuran maksimum yang diizinkan untuk nilai properti yang disimpan dalam database pencarian Windows. Batas ini berlaku untuk elemen indvidual dari vektor, bukan vektor secara keseluruhan. Nilai di luar ukuran ini dipotong. Defaultnya adalah "128" (byte).
Saat ini, Windows Search tidak menggunakan maxSize saat menghitung jumlah data yang diterimanya dari file. Sebaliknya, batas yang digunakan Windows Search adalah produk dari ukuran file dan MaxGrowFactor (ukuran file N * MaxGrowFactor) yang dibaca dari registri di HKEY_LOCAL_MACHINE->Software->Microsoft->Windows Search->Gathering Manager->MaxGrowFactor. MaxGrowFactor default adalah empat (4). Akibatnya, jika jenis file Anda cenderung kecil dalam ukuran total tetapi memiliki properti yang lebih besar, Windows Search mungkin tidak menerima semua data properti yang ingin Anda keluarkan. Namun, Anda dapat meningkatkan MaxGrowFactor agar sesuai dengan kebutuhan Anda.

 

Catatan

Untuk atribut columnIndexType, manfaat kueri yang lebih cepat perlu ditimbang terhadap waktu pengindeksan dan biaya ruang yang lebih besar yang dapat dikeluarkan indeks sekunder. Namun, biaya ini hanya dibayar untuk item yang memiliki nilai non-null, jadi untuk sebagian besar properti dapat mengatur atribut ini ke "OnDisk".

 

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, penangan properti mungkin dapat menyediakan fungsionalitas ini dengan upaya pengembangan yang lebih sedikit. Anda harus meninjau bagian Konten Teks Lengkap untuk perbandingan fungsionalitas filter dan handler properti untuk membantu Anda memutuskan apa yang terbaik untuk jenis file Anda. Kepentingan tertentu adalah fakta bahwa filter dapat menangani beberapa pengidentifikasi kode bahasa (LCID) per file sementara penangan properti tidak dapat.

Catatan

Karena penangan properti tidak dapat memotong konten seperti yang dapat dilakukan filter, file besar (bahkan jika format file yang tidak rumit) harus dimuat sepenuhnya ke dalam memori.

 

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 agar IFilter diinstal bersama dengan handler properti yang sesuai, dan bahwa IFilter terdaftar 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 restart layanan pengindeksan, atau boot ulang sistem.

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

Informasi Implementasi untuk Windows Vista dan Sebelumnya

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 Penangan Filter di Windows Search.

Meskipun sistem properti juga disertakan dengan penginstalan Windows Search untuk Windows XP, aplikasi pihak ketiga dan warisan mungkin mengharuskan filter menangani konten dan 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.

 

Menulis File Deskripsi Properti

Struktur file XML deskripsi properti (.propdesc) dijelaskan dalam topik propertyDescription . Minat khusus untuk pencarian adalah atribut 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 IPropertySystem subsistem skema::RegisterPropertySchema. Fungsi ini menginformasikan subsistem skema dari penambahan file skema deskripsi properti (.propdesc), menggunakan jalur file ke file .propdesc pada komputer lokal, biasanya direktori penginstalan aplikasi di bawah "File Program". 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 aliran dari 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 menerapkan handler 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.

Metode Deskripsi
Menjalankan Menyimpan perubahan properti ke file.
GetAt Mengambil kunci properti dari array properti item.
GetCount Mendapatkan jumlah properti yang dilampirkan ke file.
GetValue Mengambil data untuk properti tertentu.
SetValue Mengatur nilai properti baru atau mengganti atau menghapus nilai yang sudah ada.

 

 

 

Pertimbangan penting untuk menerapkan antarmuka ini disertakan dalam dokumentasi IPropertyStore.

Catatan

Jika handler properti Anda memancarkan beberapa nilai untuk properti yang sama untuk item tertentu, hanya nilai terakhir yang dikeluarkan yang disimpan dalam katalog.

 

 

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 menerapkan handler properti, Anda ingin memastikan item yang didaftarkan handler Anda untuk diindeks. Anda dapat menggunakan Pengelola Katalog untuk memulai pengindeksan ulang, dan Anda juga dapat menggunakan Pengelola Lingkup Perayapan untuk menyiapkan aturan default yang menunjukkan URL yang Anda inginkan untuk dirayapi oleh Pengindeks. Opsi lain adalah mengikuti sampel kode ReIndex di Sampel Kode Pencarian Windows.

Untuk informasi lebih lanjut, lihat Menggunakan Pengelola Katalog dan Menggunakan Manajer Lingkup Perayapan.

 

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

 

Penangan Properti Pengujian dan Pemecahan Masalah

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

  • Uji 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. Handler properti harus gagal dengan anggun.
  • 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 berfungsi seperti yang diharapkan.

Pengujian Penginstalan dan Penyiapan

Terakhir, Anda perlu menguji rutinitas penginstalan dan penghapusan instalan.

  • Penginstalan harus pulih dari penginstalan yang gagal (misalnya, dari membatalkan lalu memulai ulang penyiapan).
  • Hapus instalan harus menghapus semua file yang terkait dengan handler properti.
  • Hapus instalasi tidak boleh menghapus file selain yang terkait dengan penginstalan handler properti.
  • Kunci registri yang terkait dengan handler properti harus dihapus saat dihapus instalasinya.
  • Hapus instalan harus berfungsi meskipun file dihapus dari direktori penginstalan.

Pemecahan Masalah Handler Properti

Berikut ini adalah beberapa kesalahan umum yang dilakukan saat mengembangkan penangan 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 pengujian di lokasi yang tidak terinstans.

Jika Anda mengalami masalah saat menangani properti Anda bekerja dengan pengindeks, berikut adalah beberapa tips untuk membantu Anda memecahkan masalah:

  • Verifikasi bahwa deskripsi properti Anda (file.propdesc) ditandai isColumn="true", isViewable="true", dan isQueryable="true" sebagaimana mewajibkan.
  • 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 dari mendaftarkan file .propdesc Anda.
  • Verifikasi bahwa DLL Anda berada di lokasi global (dan bukan di bawah profil pengguna Anda).
  • Verifikasi bahwa DLL Anda terdaftar di HKEY_LOCAL_MACHINE\Software\Classes.
  • Verifikasi bahwa DLL Anda terdaftar menggunakan jalur lengkap (atau REG_EXPAND_SZ string 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 Opsi Pengindeksan Panel Kontrol mencantumkan jenis file Anda sebagai jenis 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.

Format CLSID
OLE DocFile {8d80504a-0826-40c5-97e1-ebc68f953792}
Simpan XML Permainan {ECDD6472-2B9B-4b4b-AE36-F316DF3C8D60}
Handler XPS/OPC {45670FA8-ED97-4F44-BC93-305082590BFB}
XML {c73f6f30-97a0-4ad1-a08f-540d4e9bc7b9}

 

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 pendaftaran 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 Detail dan panel.

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

 

Referensi

Pemetaan Properti

Konseptual

Praktik Terbaik untuk Membuat Handler Filter di Windows Search

Proses Pengindeksan

Mengembangkan Handler Protokol

Properti yang Ditentukan Sistem untuk Format File Kustom

Sumber Daya Lainnya

Sistem Properti

Properti Sistem

Sampel Kode Pencarian Windows