How to manage LINQ to SharePoint entities with LINQ to SharePoint DSL Extension (part 2)
This second post is about how to manage your entities in your schema. This tutorial explains how to create new entities, to modify mapped properties, content types, etc. in the new Visual Studio entity designer. Note that you can add new entities in your schema thanks to the Visual Studio ToolBox panel, which contains all the things that you can add in LINQ to SharePoint DSL data model.
The model: a LINQ data context graphical editor
When you're opening a LINQ to SharePoint data model file, you can design the entities managed by LINQ. All the designable surface represents your LINQ to SharePoint DataContext. If you're clicking on a white space in your model, the Property windows of Visual Studio provides you the way to edit the data context settings, for example:
The context has 4 properties:
- Data Context Name: name of the data context class (keep empty to use the file name)
- Description: description appended to the data context class code
- Namespace: namespace of the generated classes (keep empty to use the current assembly namespace)
- Site Url: URL of the SharePoint site synchronized with the current schema
In your model, you could have 3 kinds of entities inside: content types, lists and enumerations. On each entity, you can edit the settings, add or remove mapped properties and change the relations inside the model (between lists, content types, enumerations, etc.).
The content types editor
The content types appear with the green color in your model. When you're clicking on content type shape, you can also modify the settings of this entity with the Visual Studio property panel, for example:
For each content type, you can modifiy the following properties:
- Name: the name of the Dot Net Entity
- Description: The description of the class in code file
- ID: SharePoint content type ID (for example for Item: 0x01, see this link for Content type IDs management documentation: http://msdn.microsoft.com/en-us/library/aa543822.aspx)
- Mapped Name: The name of this entity in SharePoint
- Parent content type: The parent content type (mandatory for all the content types expected the root Item content type)
- Used In Lists: Collection of lists (optional). This collection is helpful for two reasons:
- You can use it to declare a list not used as entity in the schema.
- You can use to declare that you want to use this content type for a specific list already mapped.
The lists editor
In your model, all the entities mapped to a list appears as blue shape. If you're clicking on a list shape, these properties are available to edit in the Visual Studio Properties panel:
For each list, you can modify the following properties:
- Name: Name of the entity
- Content type: the parent content type
- Description: the description of the class
- Mapped List Name: Name of the list in the SharePoint web site
How to manage the mapped properties for content types and lists
The content types and the lists shapes have mapped properties. The mapped properties are the .NET classes properties mapped on SharePoint fields.
You can add a mapped property on a list or a content by clicking on the shape, right click, and click on "Add a new mapped property", as followed in this screenshot:
When you're clicking on a mapped property, you can edit all the settings in the Visual Studio Properties panel:
The editable settings on a mapped property are:
- Property Name: Name of the property in dot net code. The name value must match with dot net naming convention.
- Description: Description of this property in the class
- Entity type: Dot Net type of this property.
- Enumeration type: Name of the Enumeration if the Entity type is Enum
- Field Internal Name: Internal Name of the mapped column in SharePoint
- SharePoint Field type: SharePoint type of this column (see next chapter for complete types mapping table)
- Allow Multiple Values: Specifies if this field allows multiple values
- Read Only: Specifies if this field is read only or not
- Required: Specifies if this field is required or not
All the translation between SharePoint fields types and .Net entity properties types follow the type mapping list available in SPMetal documentation on the MSDN web site:
The enumerations editor
When in SharePoint you have a column of type "Choice", this column is mapped with a property which has a dedicated enum type. The enumeration type appears in the designer like brown shapes, as followed:
An enumeration entity has got values which correspond to the available choices in the SharePoint fields. For each value, if you're clicking on it in the designer, you can change the name of this value in the .Net enum type, and the value of this choice in the SharePoint field:
Save and test your model
When you're saving a model, a validator is directly runed to check that your schema respects all the rules to generate the code. If you have some errors during the saving process, you must resolve it. If you don't resolve it, the generated code will have problems. All the errors appear in the Visual Studio error panel. The LINQ to SharePoint DSL Extension documentation provides all the errors that could append on a model.
If you save your model without errors, the code will be automatically generated in an attached source code file (for example if you are in a C# project with a model called MySharePointSite.l2sp, the code will be generated in a file called MySharePointSite.l2sp.cs available under the model item in the Visual Studio Solution Explorer.
In the next part of these articles, I will explain how to work with the relations in your model.