Práticas recomendadas para obter e definir propriedades

Lembre-se das seguintes práticas recomendadas para obter e definir valores de propriedades:

• Faça referência a uma propriedade diretamente do objeto pai para obter e definir propriedades internas explícitas de objetos de item, por exemplo, MailItem.Subject.
• Use ItemProperties e ItemProperty para enumerar propriedades internas explícitas e propriedades personalizadas e obter e definir propriedades personalizadas para itens (exceto para objeto DocumentItem ).
• Use UserProperties e UserProperty para enumerar, obter e definir propriedades personalizadas para itens (exceto para o objeto DocumentItem ).
• Use PropertyAccessor para obter e definir propriedades personalizadas para o objeto DocumentItem , propriedades internas no nível do item que não são expostas no modelo de objeto do Outlook ou propriedades para os seguintes objetos: AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient e Store.
• Para obter ou definir várias propriedades personalizadas, use o objeto PropertyAccessor, em vez do objeto UserProperties para um melhor desempenho.
• Para criar ou acessar propriedades personalizadas, use o namespace da sequência de caracteres de MAPI por conveniência em relação à proptag de MAPI ou ao namespace de identificação. Use o GUID de seu suplemento como GUID do namespace.
• Ao se referir a propriedades por namespaces, lembre-se de que essas referências diferenciam maiúsculas de minúsculas. Por exemplo, enquanto n:schemas:contacts:givenName é um namespace válido, urn:schemas:contacts:givenname não é.
• Para obter ou definir várias propriedades, use PropertyAccessor.GetProperties e PropertyAccessor.SetProperties, em vez de PropertyAccessor.GetProperty e PropertyAccessor.SetProperty, para melhor desempenho.
• Para que o evento CustomPropertyChange seja acionado quando for alterado o valor de uma propriedade personalizada de item, ela deverá estar na coleção UserProperties do item. Uma propriedade no nível do item adicionada implicitamente por SetProperty ou SetProperties não se torna automaticamente parte da coleção UserProperties do item. Um UserProperties.Add explícito é necessário para incluí-lo.
• Para definir uma propriedade criada pelo método UserProperties pela primeira vez, use a propriedade UserProperty.Value em vez das SetProperties e os métodos de SetProperty do objeto PropertyAccessor.

Esta seção descreve as práticas recomendadas para salvar propriedades em um objeto:

• Para objetos de item, chamar o método Save do item para salvar o item na pasta atual também salva suas propriedades no item.
• Para objetos não nível de item que não têm um método Save (AddressList, Folder, Recipient e Store, chamando PropertyAccessor.DeleteProperty, PropertyAccessor.DeleteProperties, SetProperty ou SetPropertie salvará implicitamente as propriedades no objeto.

Esta seção descreve as melhores práticas para manter a conversão de tipo simples ao usar o PropertyAccessor para obter e definir propriedades. Para definições de tipos de propriedade MAPI, como PT_SYSTIME, consulte Tipos de Propriedade.

• Embora a maioria dos valores de data e hora do Outlook sejam armazenados no formato UTC (Tempo Universal Coordenado), não há garantia de que todas as propriedades do tipo MAPI _SYSTIME sempre retornarão UTC. A obtenção de uma propriedade PT_SYSTIME retornará um valor VT_DATE. Ao definir uma propriedade PT_SYSTIME, certifique-se de defini-la como valor UTC em vez de valor de data e hora locais. Os métodos GetProperty, SetProperty, GetProerties e SetProperties não executam a conversão de fuso horário. Use os métodos auxiliares PropertyAccessor.LocalTimeToUTC e PropertyAccessor.UTCToLocalTime para executar a conversão explícita de fuso horário.
• Uma propriedade de vários valores ( _ARRAY de tipo do Microsoft Visual Basic) é armazenada como uma matriz bidimensional que contém o mesmo número de elementos que há valores na propriedade. Obter uma propriedade com vários valores retornará um valor ARRAY . Ao definir uma propriedade com valores múltiplos, passe uma matriz bidimensional (VT_ARRAY) com um elemento para cada valor que deseje definir na propriedade.
• Uma propriedade binária (tipo MAPI _BINARY) é armazenada como uma matriz de bytes em vez de uma cadeia de caracteres. Obter uma propriedade binária retornará um valor do tipo ARRAY. Os métodos GetProperty, SetProperty, GetProperties e SetProperties não executam nenhuma conversão entre matriz binária e cadeia de caracteres. Use os métodos auxiliares PropertyAccessor.BinaryToString e PropertyAccessor.StringToBinary para executar explicitamente qualquer conversão.
• Certos tipos de propriedade MAPI, como _OBJECT, não têm suporte do PropertyAccessor. A tentativa de obter ou definir essas propriedades resultarão em um erro do tipo "sem suporte para a operação de propriedade".
• Ao obter ou definir uma propriedade usando uma referência no namespace da proptag de MAPI, certifique-se de que o tipo especificado na proptag corresponda ao tipo subjacente da propriedade. Exceto para o caso de uma propriedade _STRING8 em que você pode especificar um tipo de 001E ou 001F no proptag para obter ou definir a propriedade como um VT_BSTR, obter ou definir uma propriedade não envolve qualquer coerção de tipo e um erro será retornado se houver uma incompatibilidade de tipo.
• Ao definir uma propriedade, talvez seja menos restritivo usar uma referência a propriedade no namespace da sequência de caracteres de MAPI do que uma no namespace da proptag de MAPI. A especificação da propriedade no namespace da sequência de caracteres de MAPI não exige estritamente que o valor corresponda ao tipo subjacente da propriedade. Por exemplo, você pode passar um valor de cadeia de caracteres como _BSTR para definir uma propriedade date-time, como PT_SYSTIME, e o tipo da propriedade se torna o tipo do valor, que é STR.

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.