SPMetal
Applies to: SharePoint Foundation 2010
SPMetal is a command-line tool that generates entity classes, which provide an object-oriented interface to the Microsoft SharePoint Foundation content databases. These classes are primarily used in LINQ to SharePoint queries; but they are also used to add, delete, and change list items with concurrency conflict resolution. Finally, they can be used as an alternative to the regular SharePoint Foundation object model for referencing content.
The tool is included with SharePoint Foundation and is located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\BIN.
SPMetal is typically executed as a prebuild command in Microsoft Visual Studio because the code it generates is usually part of a solution that includes a new site type that is itself evolving during the development cycle. Because SPMetal overwrites the files it generates with each execution, for a given output path and against a given Web site, you should not make changes to these files. The classes it generates are partial, so you can add members to them in separate, manually created, code files.
If your solution is based on an existing site type, such as the Team Site that is included with SharePoint Foundation, and it references only lists that are always present in such sites and only fields (columns) that are always present in those lists, you can run SPMetal just once and make changes to the generated file that will not be overwritten.
For more information about the practicalities of using SPMetal, see How to: Use SPMetal.
Basic Syntax
SPMetal uses the basic syntax of other Windows command-line tools:
SPMetal [options]
Each option is preceded by a forward slash. Most options require values, in which case the option name is followed by a colon and the value follows the colon:
SPMetal /option1 /option2:value /option3:"value with a space"
Options can be in any order. Not every option is required, but if you include an option that takes a value, you must give it a value. If a value contains spaces, you must enclose the whole value in quotation marks (").
Using the "/?" option, by itself, displays some brief help about the tool to the standard output.
Command Line Options
The following table lists the options and their purpose.
Option |
Value definition |
Example |
Comments |
|---|---|---|---|
web |
The complete, absolute URL of the Web site whose data is modeled by the entity classes. |
/web:http://ContosoServer/Marketing |
Required. You can have port numbers in the server name; for example, /web:http://ContosoServer:5555/Marketing. Do not include the home page or any other page in the URL. |
code |
The relative or absolute path and file name of the output file. |
/code:MarketingSite.cs |
If this option is not used, the generated code is streamed to standard output. If no file name extension is specified or the file name extension is not either "cs" or "vb", the language option must be used. The file name (exclusive of the extension) is also used to form the beginning of the name of a class that derives from DataContext; in this example the class is named MarketingSiteDataContext. The derived class represents the lists and data of the whole Web site, so choose a file name that conveys that meaning. (You can override this naming behavior with an SPMetal Parameters XML file.) |
language |
The programming language of the generated code. |
/language:csharp |
The only possible values are "csharp" and "vb". If the value of the code option has either "cs" or "vb" as a file name extension, SPMetal can infer the language and the language option is not needed. |
namespace |
The namespace that contains the entity class declarations. |
/namespace:Contoso.TeamActivityReports |
If this option is not used, the generated code specifies no namespace and the compiled assembly treats the default namespace specified in the properties of the Visual Studio project as the namespace of the generated classes. |
useremoteapi |
No value. |
/useremoteapi |
This option signals that the value of the web parameter points to a server that is not the one on which SPMetal is running. One possible use for this parameter is to generate code against a Web site on an online deployment of SharePoint to which you intend to upload your solution as a sandboxed solution. |
user |
The user in whose context SPMetal executes. |
/user:Contoso\bob |
Use this option if you do not want SPMetal to run in your own context. Specify the domain. |
password |
The password for the user specified in the user option. |
/password:$5U+ryz |
Use in conjunction with the user option. |
serialization |
Specifies whether objects that instantiate the generated classes are serializable. |
/serialization:unidirectional |
The only possible values are "unidirectional" and "none". Specify "unidirectional" if you want the objects to be serializable. SPMetal adds appropriate attributes from the System.Runtime.Serialization namespace to the class and property declarations and adds handlers for the Deserializing event. If this option is not used, "none" is assumed. |
parameters |
Identifies the path and name of an XML file that contains overrides of SPMetal default settings. |
/parameters:MarketingSite.xml |
You typically will not reuse exactly the same parameters XML file for different Web sites, so name the file the same as the Web site. For more information about the parameters file, see Overriding SPMetal Defaults by Using a Parameters XML File. |
Example
Generate C# code:
SPMetal /web:http://ContosoServer/Marketing /code:MarketingSite.cs
Generate Visual Basic code with custom parameters settings:
SPMetal /web:http://ContosoServer/Marketing /code:MarketingSite.vb /parameters:MarketingSite.xml
Generate Visual Basic code from a specified user context:
SPMetal /web:http://ContosoServer/Marketing /code:MarketingSite.vb /user:Contoso\sally /password:7Yj38d