Setting the Value of a Property
| Outlook Developer Reference |
Outlook provides several ways to set the value of a property:
| Object.Property | UserProperty.Value | ItemProperty.Value | PropertyAccessor.SetProperty | PropertyAccessor.SetProperties | |
| Action | Sets the value of the specified explicit built-in property. | Sets the custom item-level property with a given value. If the property doesn't exist, setting it will return an "Object variable or with block variable not set" error. | Sets the built-in or custom item-level property with a given value, provided the property is not a read-only or blocked property. Returns a runtime error if the property does not exist. | Sets the property specified by SchemaName with the given value, provided the property is not a read-only or blocked property. If the property does not exist, and if the provider and the parent object supports property creation, and a valid schema name is specified for the property, SetProperty creates the property. | For each property in SchemaNames, provided the property is not a read-only or blocked property, sets the property with the corresponding value in the Values array. If the property does not already exist, property creation as stated in the SetProperty column may take place. If the two arrays SchemaNames and Values do not match in size, then SetProperties will return an invalid argument error. |
| Applicable Objects | All objects in the Outlook object model. | All Outlook item objects except Microsoft Office document items (DocumentItem objects) | All Outlook item objects except Microsoft Office document items (DocumentItem objects) | Use ItemProperty to set explicit built-in item-level properties. Use SetProperty for DocumentItem properties, item-level properties without explicit names, custom prroperties, or properties of any of the following objects: AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient, and Store. | Same objects as stated in the SetProperty column. |
| Property Type Matching | As specified in the Outlook object model. | Returns a runtime error if the value does not match the property type. | Returns a runtime error if the value does not match the property type. | If SchemaName uses the MAPI proptag namespace, and Value does not match the property type indicated by the property tag, SetProperty will return a type mismatch runtime error. If SchemaName uses the MAPI string namespace, SetProperty will attept to coerce the type to match the property type. If the type coercion fails, then SetProperty will return a type mismatch runtime error. The PropertyAccessor does not support certain MAPI property types, for example, PT_OBJECT, and attempting to set the value of properties of such types will return "Property operation not supported" error. | Property type matching is similar to SetProperty as each property in SchemaNames is matched with the type of the value in the Values array. Any error including type mismatch error is returned in the Errors array. |
| Property Change Events | The PropertyChange event fires when a built-in item-level property changes. | The CustomPropertyChange event fires when the value of a custom item-level property changes. | The PropertyChange event fires when a built-in item-level property changes. The CustomPropertyChange event fires when the value of a custom item-level property changes, provided that the custom property is in the UserProperties collection for the item. Note that an item-level property added implicitly by PropertyAccessor.SetProperty or PropertyAccessor.SetProperties does not automatically become part of the item's UserProperties collection. | Changing non-item-level properties does not fire any event. Changing item-level properties fires the same events as stated in the ItemProperty.Value column. Note that an item-level property added implicitly by SetProperty or SetProperties does not automatically become part of the item's UserProperties collection. An explicit UserProperties.Add is required to include the property so that the CustomPropertyChange event will fire on property change. | For each property in the SchemaNames array, changing its value may fire an event depending on circumstances as described in the SetProperty column. |
| Security | No security restrictions. | Trusted and untrusted code can use UserProperty. | Trusted and untrusted code can use ItemProperty. | On a client computer without an appropriately set up antivirus software, untrusted code attempting to access the PropertyAccessor property of an item object will by default invoke the address book security warning. | Same security considerations as in the SetProperty column. |
| Performance | No performance overhead. Use this whenever the property is an explicit built-in property. | No performance overhead. Use this object whenever the property is a custom property at the item-level. | No performance overhead. Use this object whenever the property is a named item-level property. | Using the PropertyAccessor to access properties incurs performance overhead. For setting multiple properties, use SetProperties as opposed to repeated SetProperty. | Using the PropertyAccessor to access properties incurs performance overhead. For setting multiple properties, use SetProperties as opposed to repeated SetProperty. |
Remarks
Since the Value property is the default property for the ItemProperty and UserProperty objects, you do not necessarily have to explicitly specify the Value property when referring to the value of a property.
Similarly, the Find method is the default method for ItemProperties and UserProperties. You do not necessarily have to specify the Find method when referencing the value of a property.
See Also