Поделиться через

Best Practices for Getting and Setting Properties

  • Статья

Помните о следующих рекомендациях по получению и настройке значений свойств:

  • Ссылка на свойство непосредственно от родительского объекта, чтобы получить и задать явные встроенные свойства объектов элементов, например MailItem.Subject.
  • Используйте ItemProperties и ItemProperty для явного перечисления встроенных свойств и настраиваемых свойств, а также получения и задания настраиваемых свойств для элементов (за исключением объекта DocumentItem ).
  • Используйте UserProperties и UserProperty для перечисления, получения и задания настраиваемых свойств для элементов (за исключением объекта DocumentItem ).
  • Используйте PropertyAccessor , чтобы получить и задать настраиваемые свойства для объекта DocumentItem , встроенные свойства уровня элементов, которые не предоставляются в объектной модели Outlook, или свойства для следующих объектов: AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient и Store.
  • Чтобы получить или задать несколько настраиваемых свойств, используйте объект PropertyAccessor вместо объекта UserProperties для повышения производительности.
  • Чтобы создать пользовательские свойства или получить доступ к ней, используйте пространство имен строки MAPI для удобства через пространство имен MAPI proptag или id. Используйте GUID надстройки в качестве GUID пространства имен.
  • При ссылке на свойства по пространствам имен следует учитывать, что в таких ссылках учитывается регистр. Например, если n:schemas:contacts:givenName является допустимым пространством имен, urn:schemas:contacts:givenname не является.
  • Чтобы получить или задать несколько свойств, используйте PropertyAccessor.GetProperties и PropertyAccessor.SetProperties, а не повторяющиеся свойства PropertyAccessor.GetProperty и PropertyAccessor.SetProperty для повышения производительности.
  • Чтобы событие CustomPropertyChange срабалось при изменении значения настраиваемого свойства уровня элемента, пользовательское свойство должно находиться в коллекции UserProperties элемента. Свойство уровня элемента, добавляемое неявно SetProperty или SetProperties , не становится частью коллекции UserProperties элемента автоматически. Для его включения требуется явное значение UserProperties.Add .
  • Чтобы впервые задать свойство, созданное методом UserProperties.Add , используйте свойство UserProperty.Value вместо методов SetProperties и SetProperty объекта PropertyAccessor .

В этом разделе описаны рекомендации по сохранению свойств объекта:

  • Для объектов элементов вызов метода Save элемента для сохранения элемента в текущей папке также сохраняет его свойства в элементе.
  • Для объектов уровня элементов, у которых нет метода Save (AddressList, Folder, Recipient и Store, вызов PropertyAccessor.DeleteProperty, PropertyAccessor.DeleteProperties, SetProperty или SetPropertie неявно сохранит свойства объекта .

В этом разделе описаны рекомендации по упрощению преобразования типов при использовании PropertyAccessor для получения и задания свойств. Определения типов свойств MAPI, таких как PT_SYSTIME, см. в разделе Типы свойств.

  • Хотя большинство значений даты и времени Outlook хранятся в формате UTC, нет никакой гарантии, что все свойства типа MAPI _SYSTIME всегда будут возвращать utc. При получении свойства PT_SYSTIME возвращается значение VT_DATE . При задании свойства PT_SYSTIME убедитесь, что свойство задано как значение в формате UTC, а не как локальное значение даты и времени. Методы GetProperty, SetProperty, GetProerties и SetProperties не выполняют преобразование часового пояса. Используйте вспомогательные методы PropertyAccessor.LocalTimeToUTC и PropertyAccessor.UTCToLocalTime для явного преобразования часового пояса.
  • Многозначное свойство (тип Microsoft Visual Basic _ARRAY) хранится в виде двумерного массива, содержащего то же количество элементов, что и значения в свойстве. При получении многозначного свойства возвращается значение ARRAY . При задании многозначного свойства передайте двумерный массив (VT_ARRAY) с одним элементом для каждого значения, которое необходимо задать для свойства.
  • Двоичное свойство (тип MAPI _BINARY) хранится в виде массива байтов, а не строки. При получении двоичного свойства возвращается значение типа ARRAY. Методы GetProperty, SetProperty, GetProperties и SetProperties не выполняют преобразование между двоичным массивом и строкой. Используйте вспомогательные методы PropertyAccessor.BinaryToString и PropertyAccessor.StringToBinary для явного выполнения любого преобразования.
  • Некоторые типы свойств MAPI, например _OBJECT, не поддерживаются PropertyAccessor. Попытка получить или задать такие свойства приведет к ошибке "операция свойства не поддерживается".
  • При получении или задании свойства с помощью ссылки в пространстве имен протага MAPI убедитесь, что тип, указанный в proptag, соответствует базовому типу свойства. За исключением случаев свойства _STRING8 , в котором можно указать тип 001E или 001F в proptag, чтобы получить или задать свойство в качестве VT_BSTR, получение или задание свойства не требует приведения типа, и при несоответствии типов будет возвращена ошибка.
  • При задании свойства может быть менее строго использовать ссылку на свойство в пространстве имен строки MAPI, чем в пространстве имен proptag MAPI. Указание свойства в пространстве имен строки MAPI не требует строгого соответствия значения базовому типу свойства. Например, можно передать строковое значение, например _BSTR , чтобы задать свойство даты и времени, например PT_SYSTIME, и тип свойства становится типом значения, то есть STR.

Поддержка и обратная связь

Есть вопросы или отзывы, касающиеся Office VBA или этой статьи? Руководство по другим способам получения поддержки и отправки отзывов см. в статье Поддержка Office VBA и обратная связь.