Overriding SPMetal Defaults by Using a Parameters XML File

  • Article

Applies to: SharePoint Foundation 2010

This topic explains how you can use a file of XML markup to change the default behavior of SPMetal with respect to the code that it generates, including the lists, content types, and columns that it models in the generated code.

The formal reference for the XML markup that is used in the file begins in the topic SPMetal Parameters XML.

SPMetal Parameters XML File

An SPMetal parameters XML file contains XML markup that tells SPMetal certain details about the code it should generate. In particular, it specifies what lists, content types, and fields (columns) should be modeled in the code. The file is passed to SPMetal by the /parameters command-line option. For more information about the SPMetal command-line options, see SPMetal.

SPMetal Defaults

SPMetal does not require a parameters XML file. In the absence of one, it uses its default rules. If a parameters file is used, SPMetal uses its default rules except where they are explicitly contradicted by the parameters file. For more information about these rules, see SPMetal Default Code Generation Rules.

Changing the Default Behavior

This section explains how you can change some of the default behavior of SPMetal by using the markup in a parameters XML file.

Web Element

The top level element is <Web>. Set its Class attribute if you do not want to use the name that SPMetal would give by default to the DataContext-derived class that represents all the website’s content. Set its AccessModifier attribute to "Internal" if you want the class that is generated to be internal (Friend in Microsoft Visual Basic). The default is Public.

List Element

If you want to change how SPMetal generates a property to represent a list, add a <List> element as a child to the <Web> element. You can also add a <List> element to force SPMetal to generate a class for a list that it would not model by default, such as a hidden list. Set its mandatory Name attribute to the name of the list.

If you do not want to use the name that SPMetal would give by default to the property that represents the list, use the Member attribute to specify an alternative name. For example, by default, SPMetal uses "Calendar" as the property name for a Calendar list. You can change this to ScheduledEvents by using the markup <List Name="Calendar" Member="ScheduledEvents"/>.

If you do not want the type of items in the list to be what SPMetal would designate by default, set the Type parameter to a different type. For example, you might create (in a separate code file) a class that is just like the class that SPMetal would create as the list item type, except that it has one extra writable property. You could designate your class to be the list item type and have calling code that writes to that property of the list items that are returned by a LINQ query.

Note

Do not use the Type attribute of <List> to simply rename the class that SPMetal generates for the list item type. Instead, use the Class attribute of a <ContentType> element that is a child of the <List> element. See ContentType Element later in this topic.

There are two possible child elements to the <List> element: <ContentType> and <ExcludeContentType>. These function identically to the elements of the same names that are children of the <Web> element, except that they apply to content types that are scoped to a list instead of the whole site.

ExcludeList

Add this child element to the <Web> element to block SPMetal from generating a property for a particular list. Set the required Name attribute to the name of the list.

ExcludeOtherLists

Add this child element to the <Web> element to block SPMetal from generating properties for any lists that are not explicitly represented by <List> elements. You cannot have this element and an <IncludeHiddenLists> element.

IncludeHiddenLists

Add this child element to the <Web> element to force SPMetal to generate properties for all the hidden lists. You cannot have this element and an <ExcludeOtherLists> element.

ContentType Element

If you want to change how SPMetal generates a class to represent a content type, add a <ContentType> element as a child to the <Web> element (or <List> element). You can also add a <ContentType> element to force SPMetal to generate a class for a content type that it would not model by default, such as a hidden content type. Set the mandatory Name attribute of the <ContentType> element to the name of the content type. (Use "Item" as the name of the basic SharePoint Foundation content type.)

If you do not want to use the name that SPMetal would give by default to the class that represents the content type, use the Class attribute to specify an alternative name. For example, if the website has a Team Members list and columns were added to it, by default, SPMetal creates a TeamMembersItem class to be the type for the list items, and it specifies this as the type parameter for the EntityList<TEntity> property that represents the list. You can change the type parameter to something more readable, such as TeamMember, by using the following markup:

<List Name="Team Members">
    <ContentType Name="Item" Class="TeamMember" />
</List>

Set the AccessModifier attribute to "Internal" if you want the class that is generated to be internal (Friend in Visual Basic). The default is Public. There are no other options.

Column Element

Add this child element to the <ContentType> element to force SPMetal to create a property that represents a field (column) that it would not model by default, such as a hidden field. Set the required Name attribute to the internal name of the field. If the parent <ContentType> element is a child of a <List> element, you can also have <Column> elements that represent fields that are in the list, but not in the content type itself, which can occur if a column has been added to a list.

If you do not want to use the name that SPMetal would give by default to the property that represents the field, use the Member attribute to specify an alternative name.

If the field is a choice field and you want the type of the property that models the field to be String even if the field does not allow "Fill-in" choices, set the Type attribute to "String". (By default, SPMetal generates a declaration of an enum class using the allowed values specified in the column definition for any choice column that does not allow "Fill-in" choices.) For more information about how LINQ to SharePoint maps SharePoint Foundation field types onto Microsoft .NET Framework 3.5 data types, see Type Mapping: From LINQ to SharePoint Provider to .NET.

ExcludeColumn Element

Add this child element to the <ContentType> element to block SPMetal from generating a property for a particular field (column). Set the required Name attribute to the internal name of the field.

ExcludeOtherColumns Element

Add this child element to the <ContentType> element to block SPMetal from generating properties for any columns that are not explicitly represented by <Column> elements. You cannot have this element and an <IncludeHiddenColumns> element.

IncludeHiddenColumns Element

Add this child element to the <ContentType> element to force SPMetal to generate properties for all the hidden fields of the content type. You cannot have this element and an <ExcludeOtherColumns> element.

ExcludeContentType

Add this child element to the <Web> element (or <List> element) to block SPMetal from generating a class for a particular content type. Set the required Name attribute to the name of the content type.

Note

You cannot block class generation for a content type if other content type classes are being generated that will inherit from the blocked class. For example, if you tried to block class generation for the basic unnamed SharePoint Foundation content type (which is called "Item") with a <ExcludeContentType Name="Item" /> element, you would also have to add <ExcludeContentType /> elements for every content class that inherits from Item.

ExcludeOtherContentTypes

Add this child element to the <Web> element to block SPMetal from generating classes for any content types that are not explicitly represented by <ContentType> elements. You cannot have this element and an <IncludeHiddenContentTypes> element.

IncludeHiddenContentTypes

Add this child element to the <Web> element to force SPMetal to generate classes for all the hidden content types. You cannot have this element and an <ExcludeOtherContentTypes> element.

Example of an SPMetal Parameters XML File

<?xml version="1.0" encoding="utf-8"?>
<Web AccessModifier="Internal" xmlns="https://schemas.microsoft.com/SharePoint/2009/spmetal">
  <ContentType Name="Contact" Class="Contact">
    <Column Name="ContId" Member="ContactId" />
    <Column Name="ContactName" Member="ContactName1" />
    <Column Name="Category" Member="Cat" Type="String"/>
    <ExcludeColumn Name="HomeTelephone" />
  </ContentType>
  <ExcludeContentType Name="Order"/>
  <List Name="Team Members" Type="TeamMember">
    <ContentType Name="Item" Class="TeamMember" />
  </List>
</Web>

See Also

Tasks

How to: Use SPMetal

Reference

SPMetal

Concepts

SPMetal Parameters XML Schema

SPMetal Default Code Generation Rules

Type Mapping: From LINQ to SharePoint Provider to .NET