Desenvolvendo manipuladores de propriedades para o Windows Search

  • Artigo

O Microsoft Windows Search usa manipuladores de propriedades para extrair os valores das propriedades dos itens e usa o esquema do sistema de propriedades para determinar como uma propriedade específica deve ser indexada. Para ler e indexar valores de propriedade, os manipuladores de propriedade são invocados fora do processo pelo Windows Search para aumentar a segurança e a robustez. Por outro lado, os manipuladores de propriedade são chamados em processo pelo Windows Explorer para ler e gravar valores de propriedade.

Este tópico complementa o tópico Sistema de Propriedades com informações específicas do Windows Search e contém as seguintes seções:

 

Decisões de projeto para manipuladores de propriedade

A implementação de manipuladores de propriedades envolve as seguintes etapas:

  1. Tomando decisões de design com relação às propriedades que você gostaria de dar suporte.
  2. Criando um arquivo de descrição de propriedade (.propdesc) para propriedades que ainda não estão no sistema de propriedades.
  3. Implementando e testando o manipulador de propriedades.
  4. Instalando e registrando o manipulador de propriedades e dos arquivos de descrição de propriedades.
  5. Testando a instalação e o registro do manipulador de propriedade.

Antes de começar, você precisa considerar as seguintes perguntas de design:

  • Quais são as propriedades que o formato de arquivo dá ou deveria dar suporte?
  • Essas propriedades já estão no esquema do sistema?
  • Posso usar um manipulador de propriedade fornecido pelo sistema existente?
  • Quais propriedades podem ser exibidas para os usuários finais?
  • Quais propriedades os usuários podem editar?
  • O suporte para pesquisa de texto completo deve vir de um manipulador de propriedade ou de um filtro?
  • Preciso dar suporte para aplicativos herdados? Em caso afirmativo, o que devo implementar?

Observação

Antes de continuar, confira Usando manipuladores de propriedades fornecidos pelo sistema para ver se você pode usar um manipulador de propriedades fornecido pelo sistema, economizando tempo e recursos de desenvolvimento.

 

Depois de tomar essas decisões, você poderá escrever descrições formais de suas propriedades personalizadas para que o mecanismo de pesquisa do Windows possa começar a indexar seus arquivos e propriedades. Essas descrições formais são arquivos XML, descritos no Esquema de Descrição da Propriedade.

Decisões sobre propriedades

Ao considerar quais propriedades devem dar suporte, é preciso identificar as necessidades de indexação e pesquisa dos usuários. Por exemplo, talvez você consiga identificar cem propriedades potencialmente úteis para o seu tipo de arquivo, mas os usuários podem estar interessados em pesquisar apenas algumas delas. Além disso, talvez você queira exibir um grupo diferente, maior ou menor, dessas propriedades para os usuários no Windows Explorer e permitir que os usuários editem apenas um subconjunto das propriedades exibidas.

Seu tipo de arquivo pode dar suporte a quaisquer propriedades personalizadas que você definir, bem como um conjunto de propriedades definidas pelo sistema. Antes de criar uma propriedade personalizada, revise Propriedades do Sistema para ver se a propriedade à qual você deseja dar suporte já está definida por uma propriedade do sistema. Certifique-se sempre de da suporte às propriedades mais importantes definidas pelo sistema.

Recomendamos o uso de uma matriz para ajudar você a projetar suas propriedades:

Nome da propriedade É indexável? Pode ser exibido? É editável?
propriedade1 S Y N
propriedade... S Y N
propriedade N N N

 

Para cada uma dessas propriedades, você precisa determinar quais atributos ela deve ter e, em seguida, descrevê-los formalmente em arquivos XML de descrição de propriedades (.propdesc). Os atributos incluem o tipo de dados da propriedade, o rótulo, a cadeia de caracteres de ajuda e muito mais. Para propriedades indexáveis, você deve prestar atenção especial aos seguintes atributos de propriedade encontrados no elemento searchInfo do arquivo Property Description (Descrição da propriedade).

Atributo Descrição
inInvertedIndex Opcional. Indica se um valor de propriedade de cadeia de caracteres deve ser dividido em palavras e cada palavra armazenada no índice invertido. O índice invertido permite a busca eficiente de palavras e frases sobre o valor da propriedade usando CONTAINS ou FREETEXT (por exemplo, SELECT ... WHERE CONTAINS "algumtexto"). Se definido como FALSE, as pesquisas serão feitas em relação à cadeia de caracteres inteira. A maioria das propriedades de cadeia de caracteres deve ser definida como TRUE; as propriedades que não são de cadeia de caracteres devem ser definidas como FALSE. O padrão é FALSE.
isColumn Opcional. Indica se a propriedade deve ser armazenada no banco de dados do Windows Search como uma coluna. O armazenamento da propriedade como uma coluna permite recuperar, classificar, agrupar e filtrar (ou seja, usar qualquer predicado, exceto CONTAINS ou FREETEXT) no valor total da coluna. As propriedades exibidas ao usuário devem ser definidas como TRUE, a menos que se trate de uma propriedade textual muito grande (como o corpo de um documento) que seria pesquisada no índice invertido. O padrão é FALSE.
isColumnSparse Opcional. Indica se uma propriedade não ocupa espaço se o valor for NULL. Uma propriedade não esparsa ocupa espaço para cada item, mesmo que o valor seja NULL. Se a propriedade for de vários valores, esse atributo será sempre TRUE. Esse atributo deve ser FALSE somente se um valor estiver presente para cada item. O valor padrão é TRUE.
columnIndexType Opcional. Para otimizar a consulta, o mecanismo Windows Search pode criar índices secundários para propriedades que tenham isColumn=TRUE. Isso requer mais processamento e espaço em disco durante a indexação, mas melhora o desempenho durante a consulta. Se a propriedade tende a ser classificada, agrupada ou filtrada (ou seja, usando =, !=, <, >, LIKE, MATCHES) com frequência pelos usuários, esse atributo deve ser definido como "OnDisk". O padrão é "NotIndexed". Os seguintes valores são válidos:
  • NotIndexed: nenhum índice secundário foi criado.
  • OnDisk: criar e armazenar um índice secundário no disco.
maxSize Opcional. Indica o tamanho máximo permitido para o valor da propriedade armazenado no banco de dados de pesquisa do Windows. Esse limite se aplica aos elementos individuais de um vetor, não ao vetor como um todo. Os valores além desse tamanho são truncados. O padrão é "128" (bytes).
Atualmente, o Windows Search não usa o maxSize ao calcular a quantidade de dados que aceita de um arquivo. Em vez disso, o limite que o Windows Search usa é o produto do tamanho do arquivo e o MaxGrowFactor (tamanho do arquivo N * MaxGrowFactor) lido do registro em HKEY_LOCAL_MACHINE->Software->Microsoft->Windows Search->Gathering Manager->MaxGrowFactor. O MaxGrowFactor padrão é quatro (4). Consequentemente, se o seu tipo de arquivo tende a ser pequeno em tamanho total, mas tem propriedades maiores, o Windows Search pode não aceitar todos os dados de propriedade que você deseja emitir. No entanto, você pode aumentar o MaxGrowFactor para atender às suas necessidades.

 

Observação

Para o atributo columnIndexType, o benefício de consultas mais rápidas precisa ser ponderado em relação ao maior tempo de indexação e aos custos de espaço em que os índices secundários podem incorrer. No entanto, esse custo só é pago para itens que tenham um valor diferente de nulo, portanto, para a maioria das propriedades, esse atributo pode ser definido como "OnDisk".

 

Suporte de texto completo

De modo geral, a pesquisa de texto completo tem suporte por componentes chamados filtros; no entanto, para tipos de arquivos baseados em texto com formatos de arquivo descomplicados, os manipuladores de propriedades podem ser capazes de fornecer essa funcionalidade com menos esforço de desenvolvimento. Consulte a seção Conteúdo do texto completo para obter uma comparação da funcionalidade do filtro e do manipulador de propriedades para ajudar você a decidir o que é melhor para o seu tipo de arquivo. De particular importância é o fato de que os filtros podem lidar com vários identificadores de código de idioma (LCIDs) por arquivo, enquanto os manipuladores de propriedades não podem.

Observação

Como os manipuladores de propriedades não podem dividir o conteúdo em partes da mesma forma que os filtros, os arquivos grandes (mesmo que sejam formatos de arquivo simples) devem ser completamente carregados na memória.

 

Considerações sobre a Implementação do SO

Informações sobre a implementação para o Windows 7

No Windows 7 e posterior, há um novo comportamento ao registrar um manipulador de propriedade, IFilter ou nova extensão. Quando um novo manipulador de propriedades e/ou IFilter é instalado, os arquivos com as extensões correspondentes são automaticamente reindexados.

No Windows 7, recomenda-se que um IFilter seja instalado em conjunto com seus manipuladores de propriedades correspondentes e que o IFilter seja registrado antes do manipulador de propriedades. O registro do manipulador de propriedades inicia a reindexação imediata de arquivos indexados anteriormente sem exigir uma reinicialização e aproveita todos os IFilteres registrados anteriormente para fins de indexação de conteúdo.

Se apenas um filtro IFilter estiver instalado, sem um manipulador de propriedade correspondente, a reindexação automática ocorrerá após a reinicialização do serviço de indexação ou a reinicialização do sistema.

Para obter os sinalizadores de descrição de propriedade específicos do Windows 7, confira os seguintes tópicos de referência:

Informações sobre a implementação para o Windows Vista e versões anteriores

Antes do Windows Vista, os filtros forneciam suporte para analisar e enumerar o conteúdo e as propriedades dos arquivos. Com a introdução do sistema de propriedades, os manipuladores de propriedades tratam das propriedades do arquivo, enquanto os filtros tratam do conteúdo do arquivo. Para o Windows Vista, você precisa desenvolver apenas uma implementação parcial da interface IFilter em coordenação com um manipulador de propriedades, conforme descrito em Melhores Práticas para a Criação de Manipuladores de Filtros no Windows Search.

Embora o sistema de propriedades também esteja incluído na instalação do Windows Search para o Windows XP, aplicativos de terceiros e herdados podem exigir que os filtros manipulem tanto o conteúdo quanto as propriedades. Portanto, se estiver desenvolvendo na plataforma Windows XP, deverá fornecer uma implementação completa do filtro, bem como um manipulador de propriedade para o seu tipo de arquivo ou propriedade personalizada.

 

Gravando Arquivos de Descrição de Propriedades

A estrutura dos arquivos XML de descrição de propriedades (.propdesc) é descrita no tópico propertyDescription. Os atributos do elemento searchInfo são de especial interesse para a pesquisa. Uma vez decidido quais propriedades darão suporte, é necessário criar e registrar arquivos de descrição de propriedades para cada uma delas. Quando você registra seus arquivos .propdesc, eles são incluídos na lista de descrição de propriedades do esquema e se tornam nomes de colunas no armazenamento de propriedades do mecanismo de busca.

Você pode registrar suas descrições de propriedades personalizadas usando a função PSRegisterPropertySchema, uma API de encapsulamento que chama o IPropertySystem::RegisterPropertySchema do subsistema de esquema. Essa função informa o subsistema de esquema sobre a adição de arquivos de esquema de descrição de propriedades (.propdesc), usando o(s) caminho(s) do(s) arquivo(s) .propdesc no computador local, geralmente o diretório de instalação do aplicativo em "Arquivos de Programas". Normalmente, uma configuração ou aplicativo (por exemplo, o instalador do manipulador de propriedades) chamará esse método depois de instalar o(s) arquivo(s) .propdesc.

 

Implementando Manipuladores de Propriedade

O desenvolvimento de um manipulador de propriedades envolve a implementação das seguintes interfaces:

  • IInitialzeWithStream: fornece a inicialização baseada em fluxo do seu manipulador de propriedade.
  • IPropertyStore: enumera, obtém e define os valores da propriedade.
  • IPropertyStoreCapabilities: Opcional. Identifica se os usuários podem editar uma propriedade a partir de uma interface do usuário.

IInitializeWithStream

Conforme descrito no tópico Property System, é altamente recomendável implementar manipuladores de propriedade com IInitializeWithStream para fazer a inicialização baseada em fluxo. Se você optar por não implementar o IInitializeWithStream, o manipulador de propriedades deverá optar por não executar o processo de isolamento definindo o sinalizador DisableProcessIsolation na chave de registro do manipulador de propriedades. A desativação do isolamento do processo é geralmente destinada apenas aos manipuladores de propriedades herdadas e deve ser evitada com veemência por qualquer código novo.

IPropertyStore

Para criar um manipulador de propriedades, você deve implementar a interface IPropertyStore com os seguintes métodos.

Método Descrição
Confirmar Salva uma alteração de propriedade no arquivo.
GetAt Recupera uma chave de propriedade da matriz de propriedades de um item.
GetCount Obtém o número de propriedades anexadas ao arquivo.
GetValue Recupera os dados de uma propriedade específica.
SetValue Define um novo valor de propriedade ou substitui ou remove um valor existente.

 

 

 

Considerações importantes sobre a implementação dessa interface estão incluídas na documentação IPropertyStore.

Observação

Se o seu manipulador de propriedades emitir vários valores para a mesma propriedade de um determinado item, somente o último valor emitido será armazenado no catálogo.

 

 

IPropertyStoreCapabilities

Os manipuladores de propriedades podem, opcionalmente, implementar essa interface para desativar a capacidade do usuário de editar propriedades específicas. Essas propriedades são normalmente editáveis na página e no painel Detalhes, mas sua edição não é permitida no manipulador de propriedades de implementação. A implementação correta dessa interface fornece uma experiência melhor do usuário ao invés da alternativa de um simples erro em tempo de execução do Shell.

 

Como garantir que seus itens sejam indexados

Agora que você implementou o seu manipulador de propriedades, é preciso garantir que os itens para os quais o manipulador está registrado sejam indexados. Você pode usar o Gerenciador de Catálogos para iniciar a reindexação e também pode usar o Gerenciador de Escopo de Rastreamento para configurar regras padrão indicando os URLs que você deseja que o Indexador rastreie. Outra opção é seguir o exemplo de código ReIndex em Amostras de código do Windows Search.

Para obter mais informações, confira Usando o Gerenciador de Catálogos e Usando o Gerenciador de Escopo de Rastreamento.

 

Instalando e Registrando manipuladores de propriedade

Com o manipulador de propriedades implementado, ele deve ser registrado e sua extensão de nome de arquivo deve ser associada ao manipulador. O exemplo a seguir mostra as chaves e os valores do registro necessários para fazer isso.

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

 

Testando e Solucionando Problemas de Manipuladores de Propriedades

A lista a seguir fornece recomendações sobre os tipos de testes que você deve realizar:

  • Teste a obtenção de saída de cada uma das propriedades com suporte pelo tipo de arquivo.
  • Use valores de propriedade grandes, por exemplo, use uma metatag grande em documentos HTML.
  • Verifique se o manipulador de propriedades não vaza os manipuladores de arquivos editando-o após obter a saída do manipulador de propriedades ou usando uma ferramenta como oh.exe antes e depois de enumerar as propriedades do arquivo.
  • Teste todos os tipos de arquivos associados ao manipulador de propriedades. Por exemplo, verifique se o filtro HTML funciona com os tipos de arquivo .htm e .html.
  • Teste com arquivos corrompidos. O manipulador de propriedades deve falhar suavemente.
  • Se um aplicativo der suporte à criptografia, teste se o manipulador de propriedade gera texto criptografado.
  • Se o seu manipulador de propriedades der suporte à pesquisa de texto completo:
    • Use vários caracteres Unicode especiais no conteúdo do arquivo e teste a saída deles.
    • Teste o tratamento de documentos muito grandes para garantir que o manipulador de propriedades funcione conforme o esperado.

Testes de Instalação e Configuração

Por fim, você precisa testar suas rotinas de instalação e desinstalação.

  • A instalação deve se recuperar de instalações com falha (por exemplo, do cancelamento e da reinicialização da instalação).
  • A desinstalação deve excluir todos os arquivos associados ao manipulador de propriedades.
  • A desinstalação não deve excluir outros arquivos além daqueles associados à instalação do manipulador de propriedades.
  • As chaves de registro associadas ao manipulador de propriedades devem ser removidas quando desinstaladas.
  • A desinstalação deve funcionar mesmo que os arquivos sejam excluídos do diretório de instalação.

Solução de problemas com manipuladores de propriedades

A seguir, alguns erros comuns cometidos durante o desenvolvimento de manipuladores de propriedade:

  • Instalando arquivos .propdesc ou DLLs em um diretório de usuário.
  • Registrando componentes usando caminhos relativos.
  • Registrando componentes em HKEY_CURRENT_USER em vez de HKEY_LOCAL_MACHINE.
  • Esquecendo de definir DisableProcessIsolation para manipuladores que não são de fluxo.
  • Colocando o arquivo de teste em um local não indexado.

Se você estiver tendo problemas para fazer com que o manipulador de propriedades funcione com o indexador, aqui estão algumas dicas para ajudar você a solucionar problemas:

  • Verifique se as descrições das propriedades (arquivos .propdesc) estão marcadas como isColumn="true", isViewable="true" e isQueryable="true", conforme apropriado.
  • Verifique se os arquivos .propdesc estão em um local global.
  • Verifique se você registrou seus arquivos .propdesc usando caminhos totalmente qualificados.
  • Verifique se o log de eventos não registrou nenhuma falha no registro do seu arquivo .propdesc.
  • Verifique se suas DLLs estão em um local global (e não no seu perfil de usuário).
  • Verifique se suas DLLs estão registradas em HKEY_LOCAL_MACHINE\Software\Classes.
  • Verifique se suas DLLs estão registradas usando caminhos completos (ou strings REG_EXPAND_SZ que se expandem para caminhos absolutos usando variáveis de ambiente conhecidas pela conta do sistema).
  • Verifique se o manipulador de propriedades funciona no Windows Explorer.
  • Embora recomendemos o uso de IInitializeWithStream, se for necessário usar IInitializeWithFile ou IInitializeWithItem, verifique se você especificou DisableProcessIsolation.
  • Verifique se o Painel de Controle de Opções de Indexação lista o seu tipo de arquivo como um tipo de arquivo indexado.
  • Verifique se o arquivo de teste está em um local indexado.
  • Verifique se o arquivo de teste foi modificado desde que você instalou o manipulador de propriedades.

Se seu arquivo de teste estiver em um local indexado e o indexador já tiver rastreado esse local, você precisará modificar o arquivo de alguma forma para acionar a reindexação do arquivo.

 

Usando os Manipuladores de Propriedades Fornecidos pelo Sistema

O Windows inclui vários manipuladores de propriedades fornecidos pelo sistema que você pode usar se o formato do seu tipo de arquivo for compatível. Se você definir uma nova extensão de arquivo que use um desses formatos, poderá usar os manipuladores fornecidos pelo sistema registrando o identificador de classe do manipulador (CLSID) para sua extensão de arquivo.

Você pode usar o CLSID listado na tabela a seguir para registrar os manipuladores de propriedade fornecidos pelo sistema para o seu tipo de formato de arquivo.

Formatar CLSID
Arquivo DocFile OLE {8d80504a-0826-40c5-97e1-ebc68f953792}
Salvar XML do jogo {ECDD6472-2B9B-4b4b-AE36-F316DF3C8D60}
Manipulador de XPS/OPC {45670FA8-ED97-4F44-BC93-305082590BFB}
XML {c73f6f30-97a0-4ad1-a08f-540d4e9bc7b9}

 

Antes de criar uma propriedade personalizada, você deve ter certeza de que não há uma propriedade definida pelo sistema que possa ser usada em seu lugar. Você pode enumerar as propriedades definidas pelo sistema chamando PSEnumeratePropertyDescriptions ou usando a ferramenta de linha de comando prop.exe.

O esquema do sistema define como essas propriedades interagem com o indexador, e você não pode alterar isso. Além disso, o aplicativo que você usa para criar, editar e salvar seu tipo de arquivo também precisa estar em conformidade com determinado comportamento. Por exemplo, se o aplicativo implementar o salvamento seguro (por meio do qual um arquivo temporário é criado durante a edição e, em seguida, ReplaceFile() é usado para trocar a nova versão pela antiga), ele deverá transferir todas as propriedades do arquivo original para o novo arquivo. Se isso não for feito, o arquivo perderá as propriedades adicionadas pelos usuários ou por outros aplicativos.

 

Exemplo

A seguir, é mostrado o registro do manipulador OLE DocFile fornecido pelo sistema para um tipo de arquivo com extensão .OLEDocFile.

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

A seguir, mostramos o registro das informações da lista de propriedades para que as propriedades dos arquivos .OLEDocFile sejam exibidas na guia e no painel Detalhes.

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

 

Referência

Mapeamentos de Propriedades

Conceitual

Melhores práticas para a Criação de Manipuladores de Filtros no Windows Search

O Processo de Indexação

Desenvolver manipuladores de protocolo

Propriedades definidas pelo sistema para formatos de arquivos personalizados

Outros recursos

Sistema de Propriedade

Propriedades do sistema

Amostras de Código do Windows Search