Tài liệu LINQ to SharePoint DSL Extension for Visual Studio 2010 ppt

 Developers can easily use LINQ to SharePoint  Developers can easily manage entities lists or content types to map or not  Developers can easily remove or add specific entities  Deve

LINQ to SharePoint DSL Extension

Version 1.3.2 2011/05/12

Powered for:

User Guide

License terms

Different license terms apply to different file types:

- Source code files are governed by the MICROSOFT PUBLIC LICENSE (Ms-PL) (INCLUDED BELOW)

- Binary files are governed by MSDN CODE GALLERY BINARY LICENSE (INCLUDED BELOW)

- Documentation files are governed by CREATIVE COMMONS ATTRIBUTION 3.0 LICENSE (INCLUDED BELOW)

MICROSOFT PUBLIC LICENSE (Ms-PL)

This license governs use of the accompanying software If you use the software, you accept this license If you do not accept the license, do not use the software

1 Definitions

The terms “reproduce,” “reproduction,” “derivative works,” and “distribution” have the same meaning here as under U.S copyright law

A “contribution” is the original software, or any additions or changes to the software

A “contributor” is any person that distributes its contribution under this license

“Licensed patents” are a contributor’s patent claims that read directly on its contribution

2 Grant of Rights

(A) Copyright Grant- Subject to the terms of this license, including the license conditions and limitations in section 3, each

contributor grants you a non-exclusive, worldwide, royalty-free copyright license to reproduce its contribution, prepare derivative works of its contribution, and distribute its contribution or any derivative works that you create

(B) Patent Grant- Subject to the terms of this license, including the license conditions and limitations in section 3, each contributor grants you a non-exclusive, worldwide, royalty-free license under its licensed patents to make, have made, use, sell, offer for sale, import, and/or otherwise dispose of its contribution in the software or derivative works of the contribution in the software

3 Conditions and Limitations

(A) No Trademark License- This license does not grant you rights to use any contributors’ name, logo, or trademarks

(B) If you bring a patent claim against any contributor over patents that you claim are infringed by the software, your patent license from such contributor to the software ends automatically

(C) If you distribute any portion of the software, you must retain all copyright, patent, trademark, and attribution notices that are present in the software

(D) If you distribute any portion of the software in source code form, you may do so only under this license by including a complete copy of this license with your distribution If you distribute any portion of the software in compiled or object code form, you may only do so under a license that complies with this license

I The software is licensed “as-is.” You bear the risk of using it The contributors give no express warranties, guarantees or conditions You may have additional consumer rights under your local laws which this license cannot change To the extent permitted under your local laws, the contributors exclude the implied warranties of merchantability, fitness for a particular purpose and non-

infringement

MSDN CODE GALLERY BINARY LICENSE

You are free to install, use, copy and distribute any number of copies of the software, in object code form, provided that you retain:

• all copyright, patent, trademark, and attribution notices that are present in the software,

• this list of conditions, and

• the following disclaimer in the documentation and/or other materials provided with the software

The software is licensed “as-is.” You bear the risk of using it No express warranties, guarantees or conditions are provided To the extent permitted under your local laws, the implied warranties of merchantability, fitness for a particular purpose and non-

infringement are excluded

This license does not grant you any rights to use any other party’s name, logo, or trademarks All rights not specifically granted herein are reserved

CREATIVE COMMONS ATTRIBUTION 3.0 LICENSE

THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE (“CCPL” OR

“LICENSE”) THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED

BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS

LICENSE TO THE EXTENT THIS LICENSE MAY BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS

CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS

1 Definitions

a “Collective Work” means a work, such as a periodical issue, anthology or encyclopedia, in which the Work in its entirety in

unmodified form, along with one or more other contributions, constituting separate and independent works in themselves, are assembled into a collective whole A work that constitutes a Collective Work will not be considered a Derivative Work (as defined below) for the purposes of this License

b “Derivative Work” means a work based upon the Work or upon the Work and other pre-existing works, such as a translation, musical arrangement, dramatization, fictionalization, motion picture version, sound recording, art reproduction, abridgment, condensation, or any other form in which the Work may be recast, transformed, or adapted, except that a work that constitutes a Collective Work will not be considered a Derivative Work for the purpose of this License For the avoidance of doubt, where the Work is a musical composition or sound recording, the synchronization of the Work in timed-relation with a moving image

(“synching”) will be considered a Derivative Work for the purpose of this License

c “Licensor” means the individual, individuals, entity or entities that offers the Work under the terms of this License

d “Original Author” means the individual, individuals, entity or entities who created the Work

e “Work” means the copyrightable work of authorship offered under the terms of this License

f “You” means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation

2 Fair Use Rights Nothing in this license is intended to reduce, limit, or restrict any rights arising from fair use, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws

3 License Grant Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below:

non-a to reproduce the Work, to incorporate the Work into one or more Collective Works, and to reproduce the Work as incorporated in the Collective Works;

b to create and reproduce Derivative Works provided that any such Derivative Work, including any translation in any medium, takes reasonable steps to clearly label, demarcate or otherwise identify that changes were made to the original Work For example, a translation could be marked “The original work was translated from English to Spanish,” or a modification could indicate “The original work has been modified.”;;

c to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission the Work including as incorporated in Collective Works;

d to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission Derivative Works

e For the avoidance of doubt, where the Work is a musical composition:

i Performance Royalties Under Blanket Licenses Licensor waives the exclusive right to collect, whether individually or, in the event that Licensor is a member of a performance rights society (e.g ASCAP, BMI, SESAC), via that society, royalties for the public

performance or public digital performance (e.g webcast) of the Work

ii Mechanical Rights and Statutory Royalties Licensor waives the exclusive right to collect, whether individually or via a music rights agency or designated agent (e.g Harry Fox Agency), royalties for any phonorecord You create from the Work (“cover version”) and distribute, subject to the compulsory license created by 17 USC Section 115 of the US Copyright Act (or the equivalent in other jurisdictions)

f Webcasting Rights and Statutory Royalties For the avoidance of doubt, where the Work is a sound recording, Licensor waives the exclusive right to collect, whether individually or via a performance-rights society (e.g SoundExchange), royalties for the public digital performance (e.g webcast) of the Work, subject to the compulsory license created by 17 USC Section 114 of the US Copyright Act (or the equivalent in other jurisdictions)

The above rights may be exercised in all media and formats whether now known or hereafter devised The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats All rights not

expressly granted by Licensor are hereby reserved

4 Restrictions The license granted in Section 3 above is expressly made subject to and limited by the following restrictions:

a You may distribute, publicly display, publicly perform, or publicly digitally perform the Work only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy or phonorecord of the Work You

distribute, publicly display, publicly perform, or publicly digitally perform You may not offer or impose any terms on the Work that restrict the terms of this License or the ability of a recipient of the Work to exercise the rights granted to that recipient under the terms of the License You may not sublicense the Work You must keep intact all notices that refer to this License and to the

disclaimer of warranties When You distribute, publicly display, publicly perform, or publicly digitally perform the Work, You may not impose any technological measures on the Work that restrict the ability of a recipient of the Work from You to exercise the rights granted to that recipient under the terms of the License This Section 4(a) applies to the Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Work itself to be made subject to the terms of this License If You create a Collective Work, upon notice from any Licensor You must, to the extent practicable, remove from the Collective Work any credit as required by Section 4(b), as requested If You create a Derivative Work, upon notice from any Licensor You must, to the extent practicable, remove from the Derivative Work any credit as required by Section 4(b), as requested

b If You distribute, publicly display, publicly perform, or publicly digitally perform the Work (as defined in Section 1 above) or any Derivative Works (as defined in Section 1 above) or Collective Works (as defined in Section 1 above), You must, unless a request has been made pursuant to Section 4(a), keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or (ii) if the Original Author and/or Licensor designate another party or parties (e.g a sponsor institute, publishing entity, journal) for attribution (“Attribution Parties”)

in Licensor’s copyright notice, terms of service or by other reasonable means, the name of such party or parties; the title of the Work

if supplied; to the extent reasonably practicable, the Uniform Resource Identifier, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and, consistent with Section 3(b) in the case of a Derivative Work, a credit identifying the use of the Work in the Derivative Work (e.g., “French translation of the Work by Original Author,” or “Screenplay based on original Work by Original Author”) The credit required by this Section 4(b) may

be implemented in any reasonable manner; provided, however, that in the case of a Derivative Work or Collective Work, at a

minimum such credit will appear, if a credit for all contributing authors of the Derivative Work or Collective Work appears, then as part of these credits and in a manner at least as prominent as the credits for the other contributing authors For the avoidance of doubt, You may only use the credit required by this Section for the purpose of attribution in the manner set out above and, by exercising Your rights under this License, You may not implicitly or explicitly assert or imply any connection with, sponsorship or endorsement by the Original Author, Licensor and/or Attribution Parties, as appropriate, of You or Your use of the Work, without the separate, express prior written permission of the Original Author, Licensor and/or Attribution Parties

5 Representations, Warranties and Disclaimer

UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND ONLY TO THE EXTENT OF ANY RIGHTS HELD IN THE LICENSED WORK BY THE LICENSOR THE LICENSOR MAKES NO REPRESENTATIONS OR

WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MARKETABILITY, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE,

NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU

6 Limitation on Liability EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU

ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES

7 Termination

a This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License Individuals or entities who have received Derivative Works (as defined in Section 1 above) or Collective Works (as defined in Section

1 above) from You under this License, however, will not have their licenses terminated provided such individuals or entities remain

in full compliance with those licenses Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License

b Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in

the Work) Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above

8 Miscellaneous

a Each time You distribute or publicly digitally perform the Work (as defined in Section 1 above) or a Collective Work (as defined in Section 1 above), the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted

to You under this License

b Each time You distribute or publicly digitally perform a Derivative Work, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License

c If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable

d No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent

e This License constitutes the entire agreement between the parties with respect to the Work licensed here There are no

understandings, agreements or representations with respect to the Work not specified here Licensor shall not be bound by any additional provisions that may appear in any communication from You This License may not be modified without the mutual written agreement of the Licensor and You

Table of Contents

1 Introduction 1-111.1 Overview 1-111.2 Project information 1-111.3 Opportunities for Visual Studio 2010 developers 1-111.4 Goals 1-121.5 Non-Goals 1-121.6 Support 1-121.7 New features in this version 1-12

2 Installation 2-142.1 Pre-requirements 2-142.2 Installation 2-142.3 Uninstallation 2-18

3 Documentation 3-203.1 How build a new schema 3-203.1.1 Step 1: Add a new VS Item template 3-203.1.2 Step 2: Select a template model 3-213.1.3 Step 3: Authentication 3-223.1.4 Step 4: Content types and lists entities selection 3-253.2 Manage the schema 3-273.2.1 Solution Explorer 3-273.2.2 Design Area 3-273.2.3 Toolbox 3-293.2.4 LINQ to SharePoint explorer 3-293.3 Export a schema as picture 3-303.4 Update a schema from an existing site 3-313.5 Code generation 3-343.5.1 Code generation options 3-343.5.2 Generate code with LINQ to SharePoint DSL code generator 3-343.5.3 Generate code with SPMETAL 3-353.6 Manage the Data Context 3-423.7 Manage Lists and content types 3-433.7.1 Inheritance model 3-433.7.2 Content type 3-433.7.3 List 3-453.7.4 Enumeration 3-463.8 Mapped properties 3-483.8.1 Edit the mapping properties data 3-483.8.2 SharePoint and Net type mapping 3-493.9 Manage relations 3-503.9.1 Relational model 3-503.9.2 List to list association 3-513.9.3 List to content type association 3-523.9.4 Content type to list association 3-533.9.5 Content type to content type association 3-553.10 Error Panel 3-563.11 Using generated output code (without the repository generator) 3-593.12 Export a schema to SharePoint definitions 3-60

3.12.1 How it’s working 3-603.12.2 Advanced settings 3-653.13 Repository Layer Generator 3-713.13.1 Repository pattern layer overview 3-713.13.2 Repository implementation with LINQ to SharePoint DSL Extension 3-713.13.3 How to create the repository layer 3-753.13.4 How to use the generated code 3-793.14 AdventureWorks LT sample kit 3-853.14.1 AdventureWorks LT sample kit overview 3-853.14.2 Adventure Works LT data model 3-863.14.3 Adventure Works LT Sample kit pages 3-87

4 Annexes & links 4-894.1 LINQ to SharePoint DSL Extension for VS2010 4-894.2 Microsoft SharePoint 4-894.3 LINQ to SharePoint 4-894.4 SPMETAL 4-894.5 Screencasts & tutorials 4-89

Index

C# sample: Create new entity 3-80 C# sample: Delete an entity 3-80 C# sample: How build direct LINQ queries thanks to the “All” property 3-81 C# sample: How extends the repository class 3-84 C# sample: How extends the repository interface 3-84 C# sample: How use the repository extended methods 3-84 C# sample: How use the repository helper methods 3-83 C# sample: Sample of repository pattern use 3-75 C# sample: Update an entity 3-80 C# sample: Use the factory pattern 3-79 C# sample: Working with LINQ queries 3-59 C# sample: Working with relations 3-59 Picture: Add a new Enumeration Value 3-46 Picture: Add a new mapped property 3-49 Picture: Adventure Works LT LINQ to SharePoint DSL Data model 3-86 Picture: Adventure Works LT screenshot to browse sub categories 3-87 Picture: Adventure Works LT screenshot to browse the models list from a category 3-88 Picture: Adventure Works LT screenshot to browse top level categories 3-87 Picture: Adventure Works LT screenshot to view available products from a model 3-88 Picture: C# custom tool to generator code 3-34 Picture: Check installation (1) 2-17 Picture: Check installation (2) 2-17 Picture: Choose a template data model 3-21 Picture: Choose lists and content types to export as definitions 3-61 Picture: Choose the content types, lists, and columns to map 3-26 Picture: Choose the output export mode 3-62

Picture: Choose the remote events that you want to synchronize with your current schema 3-31

Picture: Configure Advanced Settings for definitions 3-61 Picture: Configure the export as Visual Studio SharePoint items mode 3-63

Picture: Connect to SharePoint by anonymous mode 3-23 Picture: Connect to SharePoint by claim authentication mode 3-23 Picture: Connect to SharePoint in Office 365 BETA (1/2) 3-24 Picture: Connect to SharePoint in Office 365 error 3-25 Picture: Content types advanced settings form 3-70 Picture: Content types advanced settings link 3-70 Picture: Content types and lists inheritance model 3-43 Picture: Customize the VS toolbars 3-28 Picture: Display the DSL Designer toolbar in Visual Studio 3-28 Picture: Edit a Content Type to Content Type association 3-56 Picture: Edit enumeration properties 3-46 Picture: Edit enumeration values properties 3-46 Picture: Edit mapped property data 3-48 Picture: Edit properties of a Content Type entity 3-43 Picture: Edit properties of a Content type to list association 3-54 Picture: Edit properties of a List entity 3-45 Picture: Edit properties of a List to content type association 3-53 Picture: Edit properties of a List to List association 3-51 Picture: Edit properties of the DataContext 3-42 Picture: Error when launching SPMETAL without a web site specified 3-38 Picture: Export successful window 3-63 Picture: Export to SharePoint definitions 3-60

Picture: Fill credentials to refresh schema 3-32

Picture: General view of the designer 3-27 Picture: Generated definitions in the Visual Studio projects 3-64 Picture: l2sp.mapping file attached to a schema 3-64 Picture: LINQ to SharePoint Data Model item template 3-20 Picture: List fields edit advanced settings form 3-69 Picture: List instance advanced settings form 3-65 Picture: List instance default data advanced settings form 3-67 Picture: List schema default data advanced settings form 3-68 Picture: List template advanced settings form 3-66 Picture: MSI Installer (1) 2-14 Picture: MSI Installer (2) 2-15 Picture: MSI Installer (3) 2-15 Picture: MSI Installer (4) 2-16 Picture: MSI Installer (5) 2-16 Picture: Repository pattern wizard model browser 3-77 Picture: Repository pattern wizard model form 3-76 Picture: Select data to remove in an existing schema 3-33 Picture: Select new data to import in an existing schema 3-33 Picture: Specify the SharePoint site credentials 3-22 Picture: SPMETAL generation failed output 3-41 Picture: SPMETAL generation output 3-40 Picture: SPMETAL generation settings 3-38 Picture: SPMETAL generation succeeded output 3-40 Picture: SPMETAL generation under process 3-41 Picture: SPMETAL generation warning 3-39 Picture: SPMETAL menu items commands added by LINQ to SharePoint DSL Extension 3-36

Picture: SPMETAL parameter file in the Solution Explorer 3-37

Picture: SPMETAL parameter file succeeded message 3-36

Picture: the “Save as picture” menu item 3-30

Picture: the ”Update from site” menu item 3-31

Picture: the items of the LINQ to SharePoint toolbox 3-29 Picture: the LINQ to SharePoint Model Explorer 3-29

Picture: the Save model as image dialog window 3-30

Picture: Uninstallation (1) 2-18 Picture: Uninstallation (2) 2-18 Picture: Uninstallation (3) 2-18 Picture: Uninstallation (4) 2-19

Picture: Update modifications summary 3-33

Picture: Visual Studio Error panel 3-57 Picture: Zooming toolbar 3-28 Table: Dot net and SharePoint types mapping table 3-50 Table: Multiplicity table 3-50 Table: Repository methods from property type table 3-82 Table: Schema errors table 3-58

1 I NTRODUCTION

The LINQ to SharePoint 2010 DSL intends to developers to model and manage LINQ to SharePoint entities of their SharePoint 2010

sites This new feature is an extension to Visual Studio 2010 With this tool, it’s become possible to add a new kind of item in a VS

project, that we name a LINQ to SharePoint schema

Please note that the LINQ to SharePoint DSL Extension for VS2010 is not officially supported by Microsoft

This project is distributed as is, without guarantees This project is developed by Microsoft Consulting Services developers

Support is provided only via the Issue tracker and the discussion forum in this project space

Home site http://archive.msdn.microsoft.com/linq2spdsl/

Issue Tracker http://code.msdn.microsoft.com/linq2spdsl/WorkItem/List.aspx

Discussion forum http://code.msdn.microsoft.com/linq2spdsl/Thread/List.aspx

1.3 O PPORTUNITIES FOR V ISUAL S TUDIO 2010 DEVELOPERS

SharePoint 2010 offers many new opportunities to developers and especially with LINQ to SharePoint This technology brings a greater flexibility to the development model to exploit more easily the data contains in the SharePoint lists Now to make a query in

a SharePoint list is as easy as making a query within a database table, thanks to a real object relational mapping process Unfortunately, entities generation is made exclusively with the command line tool SPMETAL, which is very different from the way to design data in Entity Framework directly with Visual Studio 2010

This tool is made to design the SharePoint entities as Entity framework entities, thanks to a Visual Studio extension This process mode is more integrated with the Visual Studio 2010 SharePoint developments tools, more powerful and more flexible for the SharePoint developers

Thanks this tool, VS2010 developers can acquire the following benefits:

 To use lists SharePoint is also easy as to use a table in a database

 A better experience in the LINQ entities design process

 Quicker SharePoint data access implementation: divide the implementation time between 5 and 10 with LINQ to

SharePoint DSL + LINQ to SharePoint versus a full Server OM API Implementation

 Developers can easily use LINQ to SharePoint

 Developers can easily manage entities (lists or content types to map or not)

 Developers can easily remove or add specific entities

 Developers can easily manage entities properties: name, description, inheritance…

 Developers can easily manage mapping process with SharePoint content types or lists columns of each entity properties

 Developers can easily manage relations 0-1, 1-N or N-N between entities

 Developers can design C# or VB.net classes without use spmetal.exe

 Developers can design a mapping schema without an existing SharePoint site

 Developers can generate a complete repository pattern from a LINQ to SharePoint schema (model) This repository pattern

implements automatically classes, interfaces and helpers methods to manage entity with pre-generated LINQ procedures

 Developers can have a complete “model-first” experience by generating lists and content types SharePoint XML

definitions automatically from a schema

1.4 G OALS

LINQ to SharePoint DSL project contains the following features:

 Visual Studio 2010 Extension to manage *.l2sp schema files and generate code

 New “LINQ to SharePoint Data Model” Visual Studio item type

 New “LINQ to SharePoint Data Model Repository Generator” Visual Studio item type

 Wizard to build a mapping model

 Predefined SharePoint site models including blank model, team site, publishing site, enterprise wiki, blog, document workspace…

 Wizard to automatically load the model from an existing SharePoint 2010 web site

 Visual LINQ to SharePoint entities designer

 Replacing SPMetal.exe generation with an automatic generation of code thanks T4 text templating technology

 Support C# or VB.net

The LINQ to SharePoint DSL extension create a new file type in Visual Studio with extension *.l2sp

Visual Studio manages 3 files:

 File.l2sp: contains the LINQ to SharePoint diagram data

 File.l2sp.cs: contains the C# classes generate from the diagram

 File.l2sp.diagram: contains the UI diagram data

1.5 N ON -G OALS

This tool is not intended to replace the standard use of the Microsoft.SharePoint.Linq API The code generate by this tool want to be 100% standard with LINQ entities, as SPMETAL generated classes This tool is not intended to install an external component in your SharePoint servers; this tool is only a SharePoint developer tool to install on the development computers

Please note that the LINQ to SharePoint DSL Extension for VS2010 is not officially supported by Microsoft

This project is distributed as is, without guarantees This project is developed by Microsoft Consulting Services developers

Support is provided only via the Issue tracker and the discussion forum in this project space

1.7 N EW FEATURES IN THIS VERSION

LINQ to SharePoint Data

Model Repository

Generator

New Visual Studio item template to add a TT file in a Csharp or VB.Net project This item generates all classes and interfaces to implement a repository pattern This repository pattern is automatically generated from

a *.l2sp file (LINQ to SharePoint Data model)

1.3.0

Export to lists and content

types definitions (schema

and instance)

New feature to export a LINQ to SharePoint model elements (content types and lists) as SharePoint definitions items This feature will generate Visual Studio items to add in a Visual Studio project, as lists instances and schema and content types definitions

NOTE: This feature is still in BETA mode in this version

1.3.0

Browse and import

SharePoint site with

(to import or update a

Support anonymous remote connection to the scanned SharePoint site 1.3.2

Office 365 BETA remote

connection support

Support connection with Microsoft Online Services ID on Office 365 BETA web site

1.3.2

2 I NSTALLATION

2.1 P RE - REQUIREMENTS

These features are required to install the LINQ to SharePoint DSL:

.Net Framework Framework 3.5SP1 or + EN

Visual Studio 2010 Visual Studio 2010 RTM (but not Express editions) English

SharePoint 2010 SharePoint 2010 RTM (SharePoint foundations or SharePoint server) English

SharePoint is not required for the installation of this extension but is necessary for use some features of the LINQ to SharePoint DSL Extension

2.2 I NSTALLATION

To install the LINQ to SharePoint DSL Extension, please follow the following steps:

1 Download and copy on your hard drive LINQ to SharePoint DSL Extension.v1.1.msi

2 Close all opened instances of Visual Studio 2010

3 Double click on the downloaded MSI file

4 The MSI Installer appears, click Next

Picture: MSI Installer (1)

5 Confirm installation and click next:

Picture: MSI Installer (2)

6 Accept license conditions and click next:

Picture: MSI Installer (3)

Picture: MSI Installer (4)

Picture: MSI Installer (5)

7 Click the Close button

8 To check that the extension is well done installed, open Visual Studio 2010 and open the tools file menu and click on the

“Extension Manager” menu item:

Picture: Check installation (1)

9 In the VS Extension Manager, you must see the new LINQ to SharePoint DSL Extension installed Note: you can’t uninstall the extension from these screen, read the next chapter for more information

Picture: Check installation (2)

2.3 U NINSTALLATION

1 Open the “program and feature” screen to uninstall programs

2 Localize the “LINQ to SharePoint Extension for Visual Studio 2010” and click Uninstall:

Picture: Uninstallation (1)

3 Click Yes:

Picture: Uninstallation (2)

Picture: Uninstallation (3)

4 If Visual Studio is opened and use the extension, you will be invited to close the application:

Picture: Uninstallation (4)

5 That’s done

3 D OCUMENTATION

3.1 H OW BUILD A NEW SCHEMA

3.1.1 Step 1: Add a new VS Item template

The LINQ to SharePoint DSL extension provides a new Visual Studio Item template

1 Create a new project in C# or VB.Net or open an existing one

2 Right click on a project name

3 Click on Add > Add new item

4 Choose the “LINQ to SharePoint Data Model” item template in SharePoint > 2010 templates folder

5 In the “Name” textbox, write the name of your new L2SP schema file (for example TeamSite.l2sp)

6 Click on the Add button

Picture: LINQ to SharePoint Data Model item template

3.1.2 Step 2: Select a template model

You can choose the model type from templates or choose to generate a new model from an existing site

If you choose a model, the wizard finishes and creates the schema file

If you choose the “Generate from site” option, the wizard will go in the second step

If you want to use an existing SharePoint site:

1 Click on “Generate from site” item

2 Click on Next button

Picture: Choose a template data model

3.1.3 Step 3: Authentication

You can use a remote SharePoint web site as the template of your new model The LINQ to SharePoint DSL Extension will use the SharePoint Client OM API to browse the site and get entities to map To do that, you must specify the SharePoint connection credentials, thanks to the site URL, the user name and the user password

You can use 4 different modes to connect to the remote web site:

1 With windows account (current user or a specified account)

2 With Form Based Authentication (with claims based authentication)

3 Anonymous

4 Claims based for Office 365 remote web sites

To connect to the remote web site, follow these steps:

1 In the first textbox, write you SharePoint web site url (for example: http//sharepoint2010/)

2 Choose default credentials if you want to use the current user id, and go the step 5 In you want to specify custom credentials, click on the radio button

3 In the credentials block, write the full login (for example: contoso\UserLogin)

4 In the last textbox, write the password

5 Click on “Next >” button

Picture: Connect to SharePoint by classical mode

Picture: Connect to SharePoint by claim FBA authentication mode

Picture: Connect to SharePoint by anonymous mode

If you want to use the Office 365 remote connection mode, you don’t need to insert your password in the current form:

Picture: Connect to SharePoint in Office 365 BETA (1/2)

When you’re clicking on the Next button, a new form with the web browser is opened on your SharePoint for Office 365 web site When you logged in this form, the web browser will be automatically closed and the site scanning process will be launched NOTE: This connection will use the credentials cookie called “FedAuth” saved in the web form by the claims authentication process to connect to the remote web site This mode could be use also with other compatible connection providers

Picture: Connect to SharePoint in Office 365 BETA (1/2)

If you click on Sign-in button with valid credentials, the pop up window will be closed automatically

If you cancel the form or if your credentials are wrong, you have the following error “(403) forbidden”:

Picture: Connect to SharePoint in Office 365 error

3.1.4 Step 4: Content types and lists entities selection

LINQ to SharePoint DSL Extension provides the way to select entities to map thanks to a properties viewer

The content type hierarchy appears in a treeview on the left

You can decide to keep or to remove an entity from the schema by select or unselect a checkbox of the treeview nodes

If you unselect a node, all the children will be unselected in the same time

Some mandatory content types can’t be removed : Item, Document and Folder

If you click on a tree node, the fields to map are displayed in the right list, with this pattern:

[Name] ((SharePoint Internal Name])

This list shows all the fields contained in the selected entity By default, the hidden fields are unselected

Picture: Choose the content types, lists, and columns to map

Select your data for your schema, and click on the Finish button

3.2 M ANAGE THE SCHEMA

3.2.1 Solution Explorer

In the Visual Studio 2010 solution explorer, the new 3 files types appear:

 The *.l2sp file is the schema data: if you open it (double click on the name), this file will be displayed in the design area

 The *.l2sp.cs file: contains all the generated source code (in a C# project)

 The *.l2sp.diagram: contains the UI data (internal, do not edit)

3.2.2 Design Area

The LINQ to SharePoint DSL Extension provides a new graphical interface to manage your schema in Visual Studio:

Picture: General view of the designer

LINQ to SharePoint DSL offers 3 new windows inside VS when you open a L2SP schema:

 The design area: to manage all content types, lists and relations

 The toolbox: to add new shapes in the schema

 The LINQ to SharePoint Explorer : to browse the schema entities tree

When you open a schema in VS2010, a new DSL toolbar appears in VS toolbars This toolbar looks it:

Picture: Zooming toolbar

This toolbar enables the zooming features on your schema

If you this toolbar is not present in your VS toolbars, follow these steps:

1 On toolbar, click on the “More” button, click on “Add or Remove Buttons”, and “Customize”:

Picture: Customize the VS toolbars

2 Click on the “Toolbars” tab, select the “Dsl Designer” toolbar, and click on “Close” button:

Picture: Display the DSL Designer toolbar in Visual Studio

3.2.3 Toolbox

Picture: the items of the LINQ to SharePoint toolbox

The LINQ to SharePoint toolbox contains the following tools, organized by 3 categories:

The entity tools

 Enumeration: to add an enumeration shape (an enumeration is the type associated with a SharePoint choice field)

 Content Type Entity: to add a Content type shape

 List Item Entity: to add a List shape

The inheritance tools

 Content type Inheritance: to add inheritance between 2 content types

 List Inheritance: to add inheritance between a content type and a list

The relational tools

 List to list relation: to add a relation between two lists

 List to content type relation: to add a list to content type relation

 Content type to list relation: to add a content type to list relation

 Content type to content type relation: to add a content type to content type relation

To add a tool in your schema, just drag and drop tool from the toolbox to the design area

3.2.4 LINQ to SharePoint explorer

The new Visual Studio LINQ 2 SharePoint Explorer window enables to consult the current schema data tree with all the entities

Picture: the LINQ to SharePoint Model Explorer

3.3 E XPORT A SCHEMA AS PICTURE

To export a schema as an image, follow these steps:

1 Right click somewhere on an empty space in an opened schema, and click on “Save as picture” menu item:

Picture: the “Save as picture” menu item

2 The following windows appears:

Picture: the Save model as image dialog window

3 If you want to change the bitmap location or to choose a different image format, click on the “Browse” button You can

choose the following formats: BITMAP (*.bmp), JPEG (*.jpg), ENHANCED METAFILE (*.emf) or PORTABLE NETWORK

3.4 U PDATE A SCHEMA FROM AN EXISTING SITE

The LINQ to SharePoint DSL Extension provides the way to check and modify a schema from an existing web site

To use this feature, please follow these steps:

1 Right click somewhere on an empty space in an opened schema, and click on “Update from site” menu item:

Picture: the ”Update from site” menu item

2 You must choose the events to synchronize with the current schema You can choose the kind of objects (content types,

lists or columns) that you want to detect as new and import in you schema, or to detected objects that has been deleted in the remote web site:

Picture: Choose the remote events that you want to synchronize with your current schema

3 Specify the SharePoint site url, and fill your credentials (classical mode or claims based authentication):

Picture: Fill credentials to refresh schema

4 Click on Next and wait during site loading

5 The wizard will show you the number of detected objects detect to be imported, the total of objects that could be imported and all the data to remove:

Picture: Update modifications summary

6 If you want to manage the new data to import in your schema, click on “Select new data…” button

7 The following screen will appears All the new content types, lists or columns importable will be selectable in the tree view hierarchy The default one will be automatically checked, but you can also select another data:

Picture: Select new data to import in an existing schema

8 If you want to manage the data to remove in your schema, click on “Select removed data…” button

9 The following screen will appears All the new content types, lists or columns removable will be selectable in the tree view hierarchy The default one will be automatically checked, but you can also select another data:

Picture: Select data to remove in an existing schema

10 Click on Finish button to applying modifications to your schema

3.5 C ODE GENERATION

3.5.1 Code generation options

There is two ways to generate the classes/entities code:

 With LINQ to SharePoint DSL generator

 With SPMETAL.EXE official generator

3.5.2 Generate code with LINQ to SharePoint DSL code generator

LINQ to SharePoint DSL Extension includes a native code generator from a schema This feature uses T4 technology to build the current code file, without connection to a SharePoint site This method is fast and is the same generation way of LINQ to Entities

This method is the default one when you’re creating a new schema

BE CAREFUL: This generation method is not the official way The official supported way is SPMETAL.EXE

See the next chapter for more information about SPMETAL generation

LINQ to SharePoint DSL Extension uses a custom tool to build the code file The code generation is directly done when you’re saving

changes in the schema file (L2SP schema)

A custom tool is a memory program registered to each l2sp files If you’re clicking on a l2sp file in the Visual Studio solution explorer, you can view and change the used custom tool in the Properties window, as following:

Picture: C# custom tool to generator code

TIP: The code generated by LINQ to SharePoint DSL Extension contains the following header in code file:

// -// Copyright (c) 2010, Microsoft Corporation

//

// THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF

// ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY

// IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR

// PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT

// -// Autogenerated by LINQ to SharePoint DSL Extension for VS2010

// Schema file: MySharePointSite3.l2sp

// Generation date: Sunday November 14 2010 11:46

// -// Note: Do not edit this file or modifications

// will be automatically removed

// -3.5.3 Generate code with SPMETAL

SPMETAL.EXE is a command line tool provided with SharePoint 2010 (SharePoint Server or Microsoft SharePoint Foundation) This command line tool is installed on your computer ONLY if SharePoint is installed

SPMETAL is installed in the following directory on each Windows systems:

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\BIN\SPMETAL.EXE SPMETAL browse an existing web site to generate entities and then the generation process is longer than DSL Extension

The LINQ to SharePoint DSL Extension contains the following features to work with SPMETAL:

 Feature to export a schema in a SPMETAL parameter file: All the lists, content types and columns (properties) are

automatically export in an XML file This file will be used to keep your schema modifications during the code generation of SPMETAL This file will be automatically named like ‘SCHEMA-NAME.l2sp.spmetal.xml’

 Feature to launch and manage directly in Visual Studio 2010 SPMETAL This feature provides new menu items and

windows to launch SPMETAL directly in VISUAL STUDIO from a selected schema

 Feature to configure advanced settings: to use a specific account to the connection and/or use the remote API

All this features are available in the context menu when you’re right-clicking on the schema or on the l2sp item in the Visual Studio solution explorer:

Picture: SPMETAL menu items commands added by LINQ to SharePoint DSL Extension

To generate a SPMETAL parameter file, please follow these steps:

1 Click on “Generate SPMETAL parameter file” in the context menu of a l2sp schema (see previous screenshot in chapter

“How it’s working”)

2 If the generation is succeeded, the following message appears:

Picture: SPMETAL parameter file succeeded message

3 You can notice that a new file in a now attach on your l2sp node in Visual Studio solution explorer, with the new extension

“*.l2sp.spmetal.xml”:

Picture: SPMETAL parameter file in the Solution Explorer

The XML parameter file contains definitions from content types, lists or columns mapping, as you can see in the following sample:

<?xml version= 1.0" encoding= utf-8"?>

<Web xmlns:xsi= http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd= http://www.w3.org/2001/XMLSchema"AccessModifier= Public" Class= MySharePointSite3"

xmlns= http://schemas.microsoft.com/SharePoint/2009/spmetal"

<List Name= Links" Member= LinksItem"

<ContentType Name= Link" Class= LinksItem"

<Column Name= URLwMenu2" Member= URL3" />

</ContentType>

</List>

<ExcludeOtherLists />

<ContentType Name= Item" Class= Item"

<Column Name= ContentType" Member= ContentType" />

<Column Name= Title" Member= Title" />

<ExcludeOtherColumns />

</ContentType>

<ContentType Name= Document" Class= Document"

<Column Name= Created_x0020_By" Member= DocumentCreatedBy" />

<Column Name= Modified_x0020_By" Member= DocumentModifiedBy" />

<Column Name= FileLeafRef" Member= Name" />

<ExcludeOtherColumns />

</ContentType>

<ContentType Name= Link" Class= Link"

<Column Name= Comments" Member= Comments" />

<Column Name= URL" Member= URL" />

<Column Name= URLwMenu" Member= URL1" />

<Column Name= URLNoMenu" Member= URL2" />

<ExcludeOtherColumns />

</ContentType>

<ExcludeOtherContentTypes />

</Web>

You can configure advanced settings to change some SPMETAL launching parameters Please follow these steps to do that:

1 Click on “SPMETAL generation settings” in the context menu of a l2sp schema (see previous screenshot in chapter “How

it’s working”)

2 Fill the settings form:

Picture: SPMETAL generation settings

3 Click on OK or Cancel

These parameters match with the SPMETAL command line tool parameters For more information about this parameters, please consult the following link: http://msdn.microsoft.com/en-us/library/ee538255.aspx

To launch the SPMETAL code generation from a schema, please follow these steps:

1 Click on “Launch SPMETAL classes generation” in the context menu of a l2sp schema (see previous screenshot in chapter

“How it’s working”)

2 An error could occur if you didn’t specify a SharePoint web site in your current Data Context:

Picture: Error when launching SPMETAL without a web site specified

To set the site URL on the current schema, please refer to chapter “Manage the Data Context”

3 If you’re parameter file is older than the current schema, the extension will ask to you if you want to update the parameter file

4 The following warning screen will appears:

Picture: SPMETAL generation warning

This warning screen appears to notice the following things:

 You must have SharePoint installed to use it (and then SPMETAL.EXE available)

 You must have right access on the source file (.*.l2sp.cs in C# and *.l2sp.vb in VB) If you’re using a source

controller (like TFS or SVN), you must check out the file first

 If you want to use SPMETAL as the default generator, you must remove the Custom Tool on the current schema,

as explained in the screenshot The SPMETAL generation process will write the source file that is used by LINQ to

SharePoint DSL Extension Also, if you modify your current schema and, then when you save it the code generated

by SPMETAL will be erased by the LINQ to SharePoint DSL Extension generator So to change this comportment, remove the custom tool as explained

5 If you want to escape this warning screen the next time, un check the check box on the bottom

6 Click on OK if you want to continue or Cancel to cancel

7 In the Visual Studio 2010 output window, you can see that there is a new build panel called SPMETAL This new panel shows the SPMETAL command line parameters:

Picture: SPMETAL generation output

If the generation succeeded, the output is:

Picture: SPMETAL generation succeeded output

If the generation failed, the output is: