取得並設定屬性的最佳實作
請注意下列有關取得並設定屬性值最佳實作的建議:
- 直接以父物件為基礎參照屬性,取得並設定項目物件的明確內建屬性,例如 MailItem.Subject 。
- 使用 ItemProperties 及 ItemProperty 列舉明確的內建屬性和自訂屬性,取得並設定項目的自訂屬性 ( DocumentItem 物件除外)。
- 使用 UserProperties 及 UserProperty 列舉、取得並設定項目的自訂屬性 ( DocumentItem 物件除外)。
- 使用 PropertyAccessor 取得並設定 DocumentItem 物件的自訂屬性、未在 Outlook 物件模式中公開的內建項目層級屬性,或是下列物件的屬性: AddressEntry 、 AddressList 、 Attachment 、 ExchangeDistributionList 、 ExchangeUser 、 Folder 、 Recipient 和 Store 。
- 若要取得或設定多個自訂屬性,請使用 PropertyAccessor 物件,而不是 UserProperties 物件,以獲得更好的效能。
- 若要建立或存取自訂屬性,請使用適用 MAPI PropTag 或 ID 名稱空間的 MAPI 字串名稱空間。 將增益集的 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屬性,而不是PropertyAccessor物件的SetProperties和SetProperty方法。
本小節會說明有關在物件上儲存屬性的最佳作法:
- 針對項目物件,呼叫項目的 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 以明確執行任何轉換。
- PropertyAccessor不支援某些 MAPI 屬性類型,例如_OBJECT。 試圖取得或設定這類屬性會導致「不支援屬性作業」錯誤。
- 使用 MAPI PropTag 名稱空間中的參照來取得或設定屬性時,請確認 PropTag 中指定的類型與屬性的基礎類型相符。 除了 可 在 proptag 中指定 001E 或 001F 類型以取得或設定屬性為 VT_BSTR的_STRING8屬性以外,取得或設定屬性不會涉及任何類型強制型轉,而且如果類型不符,則會傳回錯誤。
- 設定屬性時,在 MAPI 字串名稱空間中使用屬性參照會比在 MAPI PropTag 名稱空間中的限制還要少。 在 MAPI 字串名稱空間中指定屬性並不會嚴格要求值與屬性的基礎類型一定要相符。 例如,您可以傳遞像 是 _BSTR 等字串值來設定日期時間屬性 ,例如 PT_SYSTIME,而屬性的類型會變成值的類型,也就是 STR。
支援和意見反應
有關於 Office VBA 或這份文件的問題或意見反應嗎? 如需取得支援服務並提供意見反應的相關指導,請參閱 Office VBA 支援與意見反應。