プロパティの取得と設定に関するヒント集

プロパティの値の取得と設定に関しては、以下のヒントを参考にしてください。

• アイテム オブジェクトに明示的に組み込まれているプロパティを取得、設定するには、 MailItem.Subject のように、親オブジェクトから直接プロパティを参照します。
• 明示的に組み込まれているプロパティやカスタム プロパティを列挙し、アイテムのカスタム プロパティを取得、設定するには、 ItemProperties および ItemProperty を使用します。ただし、 DocumentItem オブジェクトは対象外です。
• アイテムのカスタム プロパティを列挙、取得、および設定するには、 UserProperties および UserProperty を使用します。ただし、 DocumentItem オブジェクトは対象外です。
• PropertyAccessor を使用して、DocumentItem オブジェクトのカスタム プロパティ、Outlook オブジェクト モデルで公開されていない組み込みのアイテム レベルのプロパティ、または AddressEntry、AddressList、Attachment、ExchangeDistributionList、ExchangeUser、Folder、Recipient、Store の各オブジェクトのプロパティを取得および設定します。
• 複数のカスタム プロパティを設定または取得するには、パフォーマンス向上のために UserProperties オブジェクトの代わりに PropertyAccessor オブジェクトを使用します。
• カスタム プロパティを作成するか、カスタム プロパティにアクセスするには、MAPI proptag または ID 名前空間ではなく MAPI 文字列名前空間を使用すると便利です。 アドインの GUID を名前空間 GUID として使用します。
• 名前空間によりプロパティを参照する場合は、大文字小文字が区別されます。 たとえば、 n:schemas:contacts:givenName は有効な名前空間ですが、 urn:schemas:contacts:givenname は無効です。
• 複数のプロパティを取得または設定するには、パフォーマンスを向上させるために、 PropertyAccessor.GetProperty および PropertyAccessor.SetProperty を繰り返すのではなく、 PropertyAccessor.GetProperties および PropertyAccessor.SetProperties を使用します。
• アイテム レベルのカスタム プロパティの値が変更されたときに CustomPropertyChange イベントを発生させるためには、カスタム プロパティはアイテムの UserProperties コレクションにある必要があります。 SetProperty または SetProperties によって暗黙的に追加されたアイテム レベルのプロパティは、自動的にアイテムの UserProperties コレクションの一部にはなりません。 このプロパティを含めるには、明示的な UserProperties.Add が必要です。
• UserProperties.Add メソッドによって作成されたプロパティを最初に設定するには、 SetPropertiesPropertyAccessor オブジェクトの SetProperty メソッドの代わりに UserProperty.Value プロパティを使用します。

以下では、オブジェクトへのプロパティの保存に関するヒントを示します。

• アイテム オブジェクトに関しては、アイテムの Save メソッドを呼び出してアイテムを現在のフォルダーに保存すると、アイテムにプロパティが保存されます。
• Save メソッドを持たないアイテム レベル以外のオブジェクト (AddressList、Folder、Recipient、Store、PropertyAccessor.DeleteProperty、PropertyAccessor.DeleteProperties、SetProperty、SetPropertie を呼び出すと、プロパティが暗黙的にオブジェクトに保存されます。

このセクションでは、 PropertyAccessor を使用してプロパティを取得および設定する場合に、型変換を簡単に保つためのベスト プラクティスについて説明します。 PT_SYSTIMEなどの MAPI プロパティの種類の定義については、「プロパティの種類」を参照してください。

• ほとんどの Outlook の日付と時刻の値は協定世界時 (UTC) 形式で格納されますが、MAPI の種類 _SYSTIME のすべてのプロパティが常に UTC を返す保証はありません。 PT_SYSTIME のプロパティを取得すると、 VT_DATE 値が返されます。 PT_SYSTIME のプロパティを設定するときは、地域の日付と時刻の値ではなく、UTC 値として設定します。 GetProperty、SetProperty、GetProerties、および SetProperties メソッドはタイム ゾーン変換を実行しません。 タイム ゾーンを明示的に変換するには、ヘルパー メソッド PropertyAccessor.LocalTimeToUTC および PropertyAccessor.UTCToLocalTime を使用します。
• 複数値プロパティ (Microsoft Visual Basic 型 _ARRAY) は、プロパティ内の値と同じ数の要素を含む 2 次元配列として格納されます。 複数値のプロパティを取得すると、 ARRAY 値が返されます。 複数値を持つプロパティを設定するときは、プロパティに設定する値ごとに 1 つの要素を持つ 2 次元配列 (VT_ARRAY) を渡します。
• バイナリ プロパティ (MAPI 型 _BINARY) は、文字列ではなくバイトの配列として格納されます。 バイナリ プロパティを取得すると、 ARRAY 型の値が返されます。 GetProperty、SetProperty、GetProperties、および SetProperties メソッドは、バイナリ配列と文字列の間で変換を実行しません。 明示的に変換を実行するには、ヘルパー メソッド PropertyAccessor.BinaryToString および PropertyAccessor.StringToBinary を使用します。
• _OBJECTなど、特定の MAPI プロパティの種類は PropertyAccessor ではサポートされていません。 このようなプロパティを取得または設定しようとすると、"実行できません" エラーが発生します。
• MAPI proptag 名前空間で参照を使用してプロパティを取得または設定するときは、proptag で指定された種類が、プロパティの基になる種類と一致するようにします。 プロパティを取得または 設定 する 001E または 001F の型をVT_BSTRとして指定できる _STRING8 プロパティの場合を除き、プロパティの取得または設定には型強制が関与せず、型の不一致がある場合はエラーが返されます。
• プロパティを設定する場合、MAPI のプロップタグ名前空間のプロパティ参照よりも MAPI 文字列名前空間でプロパティ参照を使用する方が制限が少ない場合があります。 MAPI 文字列名前空間で プロパティを指定しても、プロパティの基になる型と一致する値は厳密には必要ありません。 たとえば、 _BSTR などの文字列値を渡して 、PT_SYSTIMEなどの日付/時刻プロパティを設定し、プロパティの型が値の型 ( STR) になります。

サポートとフィードバック

Office VBA またはこの説明書に関するご質問やフィードバックがありますか？ サポートの受け方およびフィードバックをお寄せいただく方法のガイダンスについては、Office VBA のサポートおよびフィードバックを参照してください。