SPMetal Default Code Generation Rules
Applies to: SharePoint Foundation 2010
This topic specifies the default rules that SPMetal follows when it generates code. You can change some of this behavior by creating an SPMetal parameters file and adding a /parameters option to the SPMetal command line. For more information about this kind of customization, see Overriding SPMetal Defaults by Using a Parameters XML File and SPMetal.
In the following sections, rules that are marked with an asterisk (*) cannot be overridden.
Any rule that can be overridden is followed by an indication of the XML markup that overrides it.
Class That Represents the Website
*One class that inherits from the DataContext class is generated to represent the website data as a whole.
*The class is marked partial (Partial in Microsoft Visual Basic).
The class is marked public (Public in Visual Basic). (Override with the AccessModifier attribute of the <Web> element.)
The class is named FileNameDataContext, where FileName is the name of the file (exclusive of the file name extension) that is specified by the /code option on the SPMetal command line. For example, if "/code:Personnel.vb" is on the command line, the class is named PersonnelDataContext. (Override with the Class attribute of the <Web> element.)
Properties That Represent Lists
A property is generated (in the DataContext-derived class) for every non-hidden list in the website. (Override with the <ExcludeList> or <ExcludeOtherLists> elements.)
*The type of the property is EntityList<TEntity>.
*The property is marked public (Public in Visual Basic).
No property is generated for hidden lists. (Override with an <IncludeHiddenLists> element or a <List> element whose Name attribute is assigned to a hidden list.)
A property that represents a list has the same name as the list with the following exceptions.
If there are spaces in the list name, they are removed from the property name.
If the first letter of the list name is lowercase, it is capitalized in the property name.
List Name
Property Name
Announcements
Announcements
Team Members
TeamMembers
lentils
Lentils
(Override with the Member attribute of the <List> element.)
TEntity, the type parameter of the EntityList<TEntity> property, is the content type class that is generated for the list. See Classes That Represent Content Types later in this topic. In general, if more than one content type is associated with the list, TEntity is a common denominator content type. Often the common denominator class is just the basic Item content type of Microsoft SharePoint Foundation. (Override with the Type attribute of the <List> element.)
Important
There is one exception to the usual rule that a common denominator content type is used whenever the list has more than one content type. SharePoint Foundation adds a basic Folder content type to all lists (in addition to the basic Item content type). However, by default, SPMetal does not count the Folder content type when it is determining whether the list has more than one content type. Therefore, if the Folder content type is the only additional content type, the TEntity of the EntityList<TEntity> property is the full specific content type for the list, such as Announcement for the Announcements list and CalendarEvent for the Calendar list. You can override this default behavior.
Classes That Represent Content Types
A content type class is generated to represent the basic SharePoint Foundation Item content type. (Override with an <ExcludeContentType> element for the content type and for each content type class that inherits from it.)
For any list (that has not been excluded from code generation), a content type class is generated for every defined content type assigned to the list. (Override with the <ExcludeContentType> or <ExcludeOtherContentTypes> elements.)
For any defined content type, including the basic Item content type, the generated class has the same name as the content type. (Override with the Class attribute of a <ContentType> element.)
*For any list that does not use a defined content type (and that has not been excluded from code generation), but to which one or more columns have been added, a class is generated to represent the implied content type.
The class that represents an implied content type is named ProcessedListNameBaseContentType, where ProcessedListName is the same name that is generated for the property that represents the list (see Properties That Represent Lists earlier in this topic). BaseContentType is the name of the defined content type from which the implied content type is derived. This is usually "Item", but in some cases, it is the name of some other defined content type. For example, if the defined content type Issue is added to a list called Tasks, and then one column from that content type is removed from the list, the class that represents this new implied content type is called TasksIssue. (Override with the Class attribute of a <ContentType> element.)
Important
The implied content type is not yet named when the parameter.xml file is read, so you cannot use "ProcessedListNameBaseContentType" as the value of any attribute of any element in the parameters.xml file. For example, you cannot get SPMetal to define the EntityList<TEntity><T> property that represents a Team Members list as EntityList<TeamMembersItem>, where TeamMembersList is the implied content type of the list, by creating a <List> element for the list and setting its Type parameter to "TeamMembersItem". This would produce an error from SPMetal because it has not yet generated the name "TeamMembersItem" at the time it reads the parameters XML file. If you need to treat the members of a list as objects of the implied type, you can use the Cast<TResult>(IQueryable) method in the call to GetList<T>(String) and have it return an anonymous type. For example, var teamMembers = teamWebSite.GetList<Item>("TeamMembers").Cast<TeamMembersItem>();.
*If a content type inherits from another content type, the generated class that represents the former inherits from the class that represents the latter.
*The content type classes are marked partial (Partial in Visual Basic).
The content type classes are marked public (Public in Visual Basic). (Override with the AccessModifier attribute of a <ContentType> element.)
No class is generated for hidden content types. (Override with an <IncludeHiddenContentTypes> element or a <ContentType> element whose Name attribute is assigned to a hidden content type.)
*The class that represents the basic Item content type implements ITrackEntityState, ITrackOriginalValues, INotifyPropertyChanged and INotifyPropertyChanging.
Properties That Represent List Columns
A property is generated (in a content type class) for every non-hidden field (column) in the content type. (Override with the <ExcludeColumn> or <ExcludeOtherColumns> elements.)
*The property is marked public (Public in Visual Basic).
The property has the same name as the column it represents. (Override with the Member attribute of a <Column> element.)
*Spaces in a column name are removed.
*If the first word in the column name is lowercase, it is uppercase in the property name.
The type of a column property is determined from the property of the field in accordance with the mapping presented in Type Mapping: From LINQ to SharePoint Provider to .NET. (Override with the Type attribute of a <Column> element.)
No property is generated for columns that are on the list, but not in the content type. (Override with the Name attribute of a <Column> element.)
If the content type derives from another content type and a field that is in the parent content type was removed from the child content type, then a property is generated for the field in both the parent and child content type classes. In the parent class, the property is marked with the virtual keyword. In the child content type, the property is overridden and both the set and get accessors contain a single line that throws a InvalidOperationException with a message that explains that the field was removed from the content type. In addition, the overridden property is decorated with the RemovedColumnAttribute.
No property is generated for hidden columns, except the hidden "Id" and "Version" columns. (Override with the <IncludeHiddenColumns> element.)
Enumerations and Classes That Represent Options for a Choice or MultiChoice Field
For every Choice field that does not allow "Fill-in" choices, an enumerated class is generated. (Override with the Type attribute of a <Column> element.)
For every MultiChoice field that does not allow "Fill-in" choices and that has fewer than 31 choices, an enumerated class that is decorated with the [Flags] attribute is generated. (Override with the Type attribute of a <Column> element.)
*"Invalid" and "None" are added as possible values to the enumerations in both.
*For every Choice or MultiChoice field that does allow "Fill-in" choices, a sealed class is generated with a String constant for each defined value.
EntityRef<T>, EntitySet<T>, and LookupList<T> Fields That Represent Lookup List Relations
*For every column that is a lookup to a field on another list and that does not allow multiple values, the property that represents the column wraps a private field of type EntityRef<TEntity>, where TEntity is the content type of the lookup list.
*For every column that is a lookup to a field on another list and that does allow multiple values and is looking up to a list that is represented by SPMetal-generated code, the property that represents the column wraps a private field of type EntitySet<TEntity>, where TEntity is the content type of the lookup list.
* For every column that is a lookup to a field on another list and that does allow multiple values and is looking up to a list that is not represented by SPMetal-generated code, such as a target list that is hidden or is excluded from code generation by SPMetal’s configuration file, two private LookupList<T> are generated. One of these fields holds the current values of the lookup field (which are a subset of the target column), the other holds the IDs of the list items from which the current values are taken. These two private fields are each wrapped by a public property of type IList<T>.
See Also
Reference
Microsoft.SharePoint.Linq.CodeGeneration