通过

获取和设置属性的最佳做法

  • 项目

获取和设置属性值时请牢记以下最佳做法建议：

  • 直接从父对象引用属性以获取和设置项目对象的显式内置属性，例如 MailItem.Subject 。
  • 使用 ItemProperties 和 ItemProperty 枚举显式内置属性和自定义属性，并获取和设置项目的自定义属性（ DocumentItem 对象除外）。
  • 使用 UserProperties 和 UserProperty 枚举、获取和设置项目的自定义属性（ DocumentItem 对象除外）。
  • 使用 PropertyAccessor 获取和设置 DocumentItem 对象的自定义属性、Outlook 对象模型中未公开的内置项目级属性或以下对象的属性： AddressEntry 、 AddressList 、 Attachment 、 ExchangeDistributionList 、 ExchangeUser 、 Folder 、 Recipient 和 Store 。
  • 要获取或设置自定义的多个属性，使用 PropertyAccessor 对象而不是 UserProperties 对象更好的性能。
  • 若要创建或访问自定义属性，使用 MAPI 字符串命名空间要比使用 MAPI 属性标记 (proptag) 命名空间或标识命名空间方便。 使用加载项的 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 方法创建一个属性，而不是 SetProperties 和 PropertyAccessor 对象的 SetProperty 方法中使用 UserProperty.Value 属性。

本部分说明在对象上保存属性的最佳做法：

  • 对于项目对象，调用项目的 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 方法不执行时区转换。 使用 Helper 方法 PropertyAccessor.LocalTimeToUTC 和 PropertyAccessor.UTCToLocalTime 可执行显式时区转换。
  • Microsoft Visual Basic 类型 (多值属性 _ARRAY) 存储为二维数组，其中包含与 属性中的值相同数量的元素。 获取多值属性将返回 ARRAY 值。 设置多值属性时，请传递一个二维数组 (VT_ARRAY)，其中对您要为属性设置的每个值都对应有一个元素。
  • MAPI 类型 (二进制属性 _BINARY) 存储为字节数组，而不是字符串。 获取二进制属性将返回 ARRAY 类型的值。 GetProperty、SetProperty、GetProperties 和 SetProperties 方法不执行二进制数组和字符串之间的任何转换。 使用 Helper 方法 PropertyAccessor.BinaryToString 和 PropertyAccessor.StringToBinary 可以显式地执行任何转换。
  • PropertyAccessor 不支持某些 MAPI 属性类型，例如_OBJECT。 尝试获取或设置此类属性会产生"不支持属性操作"错误。
  • 在使用 MAPI 属性标记命名空间中的引用获取或设置属性时，请确保属性标记中指定的类型与属性的基础类型相匹配。 除了 _STRING8 属性的情况，你可以在 proptag 中指定类型 001E 或 001F，以获取或设置 属性作为VT_BSTR，获取或设置属性不涉及任何类型强制，如果类型不匹配，将返回错误。
  • 在设置属性时，使用 MAPI 字符串命名空间中的属性引用要比使用 MAPI 属性标记命名空间中的属性引用具有更少的限制。 在 MAPI 字符串命名空间中指定属性并不严格要求属性值与属性的基础类型相匹配。 例如，可以传递 _BSTR 等字符串值来设置日期时间属性（如 PT_SYSTIME），属性的类型将成为值的类型，即 STR。

支持和反馈

有关于 Office VBA 或本文档的疑问或反馈？ 请参阅 Office VBA 支持和反馈，获取有关如何接收支持和提供反馈的指南。