How to: Use SPMetal
Applies to: SharePoint Foundation 2010
This article describes how to use the SPMetal command-line tool to generate entity class declarations for your Microsoft SharePoint Foundation solutions.
To set up your development project to use SPMetal
Add the path to SPMetal.exe to the end of the Windows %PATH% environment variable on your development computer. It is usually %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\BIN.
On the Start menu of your Windows Server computer, right-click Computer, and then click Properties.
In the System dialog box, click Advanced System Settings.
In the System Properties dialog box, click the Advanced tab, and then click Environment Variables.
In the System variables list, highlight Path, and then click Edit.
In the Edit System Variable dialog box, add a semi-colon at the end of the Variable value, and then add the path to the folder that contains SPMetal.exe. Click OK three times.
Note
If Microsoft Visual Studio is open when you perform this step, you must close and restart it before it can recognize the new %PATH% variable.
Create a SharePoint Foundation website on your development computer to serve as a test bed against which you will develop your LINQ to SharePoint code. To the extent that you can determine it at the current state of development; it should have the same lists, columns, and lookup fields as the final site type you intend to include with your solution. The SPMetal tool will read this information. However, you can rerun the tool, so it is possible to change the design as your project evolves.
Open your Visual Studio project, and add a text file to the project with the name Prebuild.bat.
Open Prebuild.bat, if it is not already open, and add the following lines.
Echo Off SET SPLANGEXT=cs Echo Backing up previous version of generated code ... IF NOT EXIST .\PreviousVersionGeneratedCode MkDir .\PreviousVersionGeneratedCode IF EXIST SiteName.%SPLANGEXT% xcopy /Y/V SiteName.%SPLANGEXT% .\PreviousVersionGeneratedCode Echo Generating code ... SPMetal /web:http://MyServer/MySite /code:SiteName.%SPLANGEXT%Make the following changes to the code, as needed:
Replace "cs" with "vb" in the second line, if you are using Microsoft Visual Basic.
Replace "MyServer/MySite" with the path to the website on your development computer against which you will be running LINQ to SharePoint code.
Replace "SiteName" in all three locations with the name of the website. In addition to being a file name, this string becomes part of a class name that represents all of the lists and data on the website. Use a string that conveys that the class represents the whole website; for example, the "MySite" that appears at the end of the URL, or possibly the value of the PlaceHolderPageTitle content placeholder on the home page.
This batch file saves the previous version of the generated code, so that you can compare it with the new version when you need to for debugging.
Save the file, but do not save the file by clicking the Save or Save All Files button on the toolbar, or by selecting Save on the File menu. The default encoding for text files in Visual Studio is not compatible with system batch files. Instead, on the File menu, select Save Prebuild.bat as. In the Save File As dialog box, click the down arrow on the Save button. Select Save with encoding. In the Advanced Save Options dialog box, select Unicode (UTF-8 without signature) – codepage 65001 in the Encoding drop-down list, and then click OK. Be sure to select the "without signature" version of UTF-8.
Tip
If you accidentally save the file the wrong way, reopen it and make a small change, such as adding a space character, and resave it the correct way. It will not actually be resaved if you do not make a change.
In Solution Explorer, right-click the project name, and then select Properties. Open the Build Events tab.
In the Pre-build event command line box (not Post-build), enter the following two lines.
cd $(ProjectDir) Prebuild.batClick Save All.
After you build the project for the first time, a SiteName.cs (or SiteName.vb) file is in the project directory in Windows, but not in Solution Explorer. Add it to the project as an Existing Item.
Each time you rebuild your project, SPMetal regenerates the declarations of entity classes and their properties. Because the generated file is overwritten each time, you should not make any changes to it. However, the classes that are generated by SPMetal are marked "partial", so you can add more members to them in a separate manually created code file that is not overwritten by SPMetal.
Configuring SPMetal
The previous procedure uses only the minimal SPMetal parameters that are needed to generate a code file, and it assumes that you want SPMetal to use its default settings in determining which lists and columns it should model in the generated code. The following procedure is about varying how SPMetal works.
To adjust the SPMetal parameters and default settings
To specify a namespace for the generated classes, or to specify whether objects created from them are serializable, or to specify that the URL in the /web switch is a remote computer (that is, not the development computer), add /namespace, /serialization, or /useremoteapi options to the SPMetal command line in the prebuild.bat file. For more information about these options, see SPMetal.
To execute SPMetal in a user context other than your own, add /user and /password options to the SPMetal command line in the prebuild.bat. For more information about these options, see SPMetal.
To use a file name extension other than "cs" or "vb" for the generated code file, add a /language option to the SPMetal command line in your prebuild.bat. For more information about this option, see SPMetal.
Inspect the generated file after the first execution of SPMetal and again after you have made the final changes to the lists, content types, and fields (columns) of the website. In any of the following circumstances, the default behavior of SPMetal may create code that does not meet your needs or is harmful to code readability. In such cases, consider creating an SPMetal parameters XML file and adding a /parameters option to the SPMetal command line in your prebuild.bat. For more information about the default behavior of XPMetal, the parameters XML file, or the /parameters option; see, respectively, SPMetal Default Code Generation Rules, Overriding SPMetal Defaults by Using a Parameters XML File, and SPMetal.
One or more of the properties that represent lists has an inappropriate name.
You need to include or exclude a different set of lists, content types, and columns from the default set that SPMetal models.