Como trabalhar com propriedades de documento no .NET
Como trabalhar com propriedades de documento em .NET
Todo documento do Word contém duas categorias de metadados — os campos padrão que o Word rastreia para cada arquivo e quaisquer valores definidos pela aplicação que um programa adicionou. Este guia mostra como ler e definir ambos com Aspose.Words FOSS para .NET, usando Document.BuiltInDocumentProperties e Document.CustomDocumentProperties, ambos construídos, em última análise, sobre a mesma representação DocumentProperty.
Guia passo a passo
Etapa 1: Ler e definir propriedades de documento incorporadas
Document.BuiltInDocumentProperties retorna uma coleção BuiltInDocumentProperties. Como se trata de um conjunto fixo e conhecido de propriedades, os valores são lidos e gravados como membros ordinários em vez de serem pesquisados por nome — por exemplo, BuiltInDocumentProperties.Author, .Title, .Subject, .Manager, .Company, .Category, .Keywords e .Comments para campos descritivos, ou .CreatedTime, .LastSavedTime, .LastPrinted e .LastSavedBy para carimbos de tempo. Estatísticas como .Characters, .CharactersWithSpaces, .Lines e .Bytes também são expostas dessa forma, juntamente com .Template e .HyperlinkBase.
Etapa 2: Adicionar uma propriedade de documento personalizada
Document.CustomDocumentProperties retorna uma coleção CustomDocumentProperties para metadados definidos pela aplicação que não fazem parte do conjunto interno do Word. Chame uma das sobrecargas Add(name, value) com um nome e um valor tipado — string, número, booleano ou data, dependendo de qual sobrecarga corresponde ao tipo do valor — para criar uma nova propriedade.
Etapa 3: Vincular uma Propriedade Personalizada ao Conteúdo do Documento
Em vez de um valor estático, uma propriedade personalizada pode rastrear um intervalo de conteúdo marcado por bookmark para que seu valor permaneça sincronizado com esse conteúdo. Chame CustomDocumentProperties.AddLinkToContent(name, linkSource), passando o nome de um bookmark como linkSource, em vez de sincronizar manualmente uma propriedade estática sempre que o conteúdo vinculado mudar.
Etapa 4: Procurar, Verificar e Remover Propriedades
Tanto BuiltInDocumentProperties quanto CustomDocumentProperties derivam da classe abstrata DocumentPropertyCollection, portanto são inspecionados da mesma forma: indexar por nome (por exemplo, properties[name]) recupera uma propriedade, Contains(name) verifica se ela existe, IndexOf(name) devolve sua posição e Count informa quantas propriedades a coleção contém. Chame Contains(name) antes de indexar por nome quando uma propriedade personalizada pode não existir, para evitar tratar uma propriedade ausente como um caminho de exceção. Remova uma propriedade com Remove(name) ou RemoveAt(index), ou limpe todas as propriedades da coleção com Clear().
Etapa 5: Ler o Valor de uma Propriedade Personalizada sem Conhecer seu Tipo Antecipadamente
Um DocumentProperty possui um Name, um Value sem tipo e um Type — um valor enum PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray ou Other. Como Value não tem tipo, use o acessador tipado correspondente em vez de fazer cast direto: ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() ou ToString(). Verifique IsLinkToContent e LinkSource para descobrir se uma propriedade está vinculada ao conteúdo do documento (consulte a Etapa 3) em vez de conter um valor estático.
Etapa 6: Verificar o Estado de Proteção de um Documento
BuiltInDocumentProperties.Security relata um valor DocumentSecurity que descreve os metadados de proteção armazenados do documento: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced ou ReadOnlyExceptAnnotations. Leia esta propriedade antes de decidir se é necessário algum processamento adicional relacionado à proteção em um documento carregado.
Problemas Comuns e Correções
Indexando um CustomDocumentProperties coleção por nome não retorna nada utilizável. A propriedade não existe neste documento. Chame Contains(name) primeiro, ou adicione a propriedade com a sobrecarga apropriada. Add(name, value) sobrecarga.
Ler o valor de uma propriedade personalizada devolve o tipo errado. DocumentProperty.Value não tem tipo object; o chamador assumiu um tipo que não corresponde Type. Use o acessador tipado correspondente (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) com base em DocumentProperty.Type.
O valor de uma propriedade personalizada vinculada parece desatualizado. A propriedade está vinculada via AddLinkToContent, e o conteúdo marcado mudou. Confirme o linkSource marcador ainda marca o intervalo que deve alimentar o valor da propriedade.
Estatísticas de palavras, como Characters or Lines não correspondem ao conteúdo atual real do documento. As estatísticas internas refletem os metadados armazenados, não uma contagem ao vivo. Recalcule e atualize os valores relevantes BuiltInDocumentProperties valores se for necessária uma contagem atualizada.
Perguntas Frequentes
Como leio ou defino o autor e o título do documento?
Use Document.BuiltInDocumentProperties.Author e .Title diretamente — são propriedades de string comuns na coleção BuiltInDocumentProperties acessada a partir de Document.BuiltInDocumentProperties.
Como adiciono metadados específicos da aplicação que não são uma propriedade padrão do Word?
Use Document.CustomDocumentProperties.Add(name, value) com o nome e o valor da propriedade; a sobrecarga correspondente de Add é selecionada com base no tipo do valor.
Qual é a diferença entre BuiltInDocumentProperties e CustomDocumentProperties?
BuiltInDocumentProperties é o conjunto fixo de campos de metadados padrão do Word, acessado como membros nomeados. CustomDocumentProperties é uma coleção nomeada e aberta de valores DocumentProperty para metadados definidos pela aplicação, acessada por nome via indexador (por exemplo, properties[name]) e Contains.
Como faço uma propriedade personalizada acompanhar um trecho de conteúdo do documento em vez de um valor estático?
Use CustomDocumentProperties.AddLinkToContent(name, linkSource), passando um nome de marcador como linkSource; o valor da propriedade então reflete esse conteúdo marcado.
Como verifico se um documento está protegido por senha?
Leia Document.BuiltInDocumentProperties.Security, um valor DocumentSecurity; PasswordProtected indica que os metadados armazenados do documento declaram proteção por senha.
