Using the *Specified Properties in Exchange 2010
Last modified: May 20, 2009
Applies to: Exchange Server 2007 | Exchange Server 2010
Many of the types that are created by the Microsoft Visual Studio 2005 or Visual Studio 2008 proxy generator include properties with names that are appended with "Specified". These properties are used along with the property of the same name that does not include the "Specified" suffix. The property without the suffix contains the data that is serialized into the request sent to the computer that is running Microsoft Exchange Server 2010 that has the Client Access server role installed. The *Specified property is used by the XmlSerializer to identify whether to serialize the property into the XML stream that is sent to the Client Access server. The *Specified property is used for optional value type properties. Required value type properties will not have the *Specified property, nor will optional or required reference type properties.
Example
The following code example sets the value of the Start property on a CalendarItemType.
CalendarItemType appt = new CalendarItemType();
appt.Start = System.DateTime.Parse("2007-03-29T14:00:00Z");
appt.StartSpecified = true;
This code indicates to the serializer that the XML element and value of the IsAllDayEvent property is added to the request that is sent to the Microsoft Exchange server.
Remarks
The *Specified properties represent optional value type elements as defined by the XML schema. These properties are optional based on the context in which they are used. So, for example, if you create a calendar item that is an all-day event, you do not need to set the end time. If you perform a GetItem operation on a calendar item, you may or may not receive the start and end time of the calendar item, depending on the response shape that is identified in the GetItem request. In these examples the start and end time properties are optional.
The following code example shows part of the CalendarItemType from the types.xsd schema file. This example includes the Start, End, OriginalStart, and IsAllDayEvent properties.
<xs:complexType name="CalendarItemType">
<xs:complexContent>
<xs:extension base="t:ItemType">
<xs:sequence>
<xs:element name="Start" type="xs:dateTime" minOccurs="0" />
<xs:element name="End" type="xs:dateTime" minOccurs="0" />
<xs:element name="OriginalStart" type="xs:dateTime" minOccurs="0" />
<xs:element name="IsAllDayEvent" type="xs:boolean" minOccurs="0" />
Because DateTime and Boolean values are value types and the minOccurs facet is set to zero, the Start, End, OriginalStart, and IsAllDayEvent properties are optional. If they were string types, there would be no *Specified properties, regardless of the minOccurs facet setting. This is because reference types can hold a null value to indicate that they are not there. Value types have no concept of null so the only way to indicate that they are not there is to use an additional external state to act like null for that property. The external state is defined by the *Specified property.
Note
You can ignore the *Specified properties when you are reading responses if you are not using the returned objects in a subsequent Web service request. If a property contains an optional value type, and the property is not included in the response as defined by the response shape, the property will contain the default values for the value type. For example, zero is the default for int and false is the default for bool.
If the *Specified property is not set to true, the request will be sent without the property. This can result in unpredictable Web service behavior.