This topic has not yet been rated - Rate this topic

Walkthrough: Creating a Data Source Extension

Visual Studio 2012

Visual Studio 2010

This walkthrough demonstrates how to create a data source extension for Visual Studio LightSwitch. A data source extension uses a custom domain service adapter class to work with other data sources. This enables you to access almost any data that is not in a data source natively supported by LightSwitch.

For extensibility, LightSwitch supports calling into a custom DomainService class as a kind of in-memory data adapter. LightSwitch calls the instance directly from its data service implementation to perform query and submit operations. The custom domain service is not exposed as a public service; therefore the [EnableClientAccess] attribute should not be applied. Using this mechanism, you can create a DomainService class that exposes entity types and implements the prescribed query, insert, update, and delete methods. LightSwitch infers a LightSwitch entity model based on the exposed entity types and infers an entity set based on the presence of a “default” query.

Creating a data source extension involves the following tasks:

Create a data source extension project.
Implement the data source class.
Create product and product category classes.
Test the data source extension.

Prerequisites

Visual Studio Professional 2012
Visual Studio 2012 SDK
LightSwitch Extensibility Toolkit for Microsoft Visual Studio 2012

Create a Data Source Extension Project

The first step is to create a project and add a LightSwitch Data Source template.

To create an extension project

On the menu bar in Visual Studio, choose File, New Project.
In the New Project dialog box, select the LightSwitch node, and then select LightSwitch Extension Library (Visual Basic) or LightSwitch Extension Library (C#).
In the Name field, type DataSourceExtension. This extension library name will appear on the Extensions tab of the LightSwitch Application Designer.
Choose the OK button to create a solution that contains the seven projects that are required for the extension.

To choose an extension type

In Solution Explorer, select the DataSourceExtension.Lspkg project.
On the menu bar, choose Project, Add New Item.
In the Add New Item dialog box, select LightSwitch Data Source.
In the Name field, enter XMLDataSource. This extension name will appear in the LightSwitch Attach Data Source Wizard.
Choose the OK button. An XMLDataSource.vb or XMLDataSource.cs file will be added to the DataSourceExtension.Server project in your solution.

Implement the Data Source Class

Most of the logic for your data source extension is contained in the XMLDataSource class that is created for you in the XMLDataSource.vb or XMLDataSource.cs file. The necessary references and Imports or using statements have already been added to the project. For an XML data source, you must add some more namespace references.

To add namespace references

In Solution Explorer, open the XMLDataSource.vb or XMLDataSource.cs file in the DataSourceExtension.Server project. Add the following Imports or using statements at the top of the file.
C#
VB
Copy
using System.Xml.Linq; using System.Configuration; using System.Web.Configuration;

Next, add a Description attribute to provide a description in the LightSwitch Attach Data Source Wizard.

To add a description attribute

Add the following just after the // TODO: Create methods containing your application logic. comment line.

//The description attribute will be displayed in the LightSwitch data attach wizard.
    [Description("Please provide the path to the XML file.")]

Next, specify the namespace.

To specify the namespace

Replace the existing namespace declaration with the following.
C#
VB
Copy
namespace DataSourceExtension.DataSources

Next, add code to set the file path and connection string.

To implement the initialize method

The following code retrieves the file name and connection string from the web.config file, verifies the file, and adds the XML elements if doing so is required. Add this code to the XMLDataSource class.

private XElement _db;
        private string _filePath;

        public override void Initialize(DomainServiceContext context)
        {
            base.Initialize(context);

            //Get the file path from config.
            if (WebConfigurationManager.ConnectionStrings[typeof(XMLDataSource).FullName] != null)
                _filePath = WebConfigurationManager.ConnectionStrings[typeof(XMLDataSource).FullName].ConnectionString;

            if (String.IsNullOrWhiteSpace(_filePath))
            {
                throw new Exception("The filepath must be provided in the web.config in the connection strings section under " + typeof(XMLDataSource).FullName);
            }
            else
            {
                if (!System.IO.File.Exists(_filePath))
                {
                    XElement x = new XElement("DataRoot");
                    x.Save(_filePath);
                }

                _db = XElement.Load(_filePath);

                //Verify the file.
                if (_db.Name != "DataRoot")
                    throw new Exception("Corrupt file.");

                //Add a product categories node if one does not exist.
                if (_db.Element("ProductCategories") == null)
                    _db.Add(new XElement("ProductCategories"));

                //Add a products node if one does not exist.
                if (_db.Element("Products") == null)
                    _db.Add(new XElement("Products"));
            }
        }

Next, implement the Submit method to save changes to the file.

To implement the submit method

Add the following code to the XMLDataSource class.

public override bool Submit(ChangeSet changeSet)
        {
            ChangeSet c = new ChangeSet(changeSet.ChangeSetEntries.OrderBy(entry => entry.Entity, new ProductEntitiesComparer()));

            Boolean baseResult = base.Submit(changeSet);
            if (baseResult)
            {
                _db.Save(_filePath);
                return true;
            }
            else
                return false;
        }

Note
You will see an error at this point because the ProductEntitiesComparer class is not yet implemented. You can ignore this error; you will implement the class later.

Next, implement two default query methods in the class; one for products and one for product categories.

To implement query methods

Add a new region to the XMLDataSource class.
C#
VB
Copy
#region Queries #endregion

Add the following code to the Queries region.

protected override int Count<T>(IQueryable<T> query)
        {
            return query.Count();
        }

        [Query(IsDefault = true)]
        public IQueryable<Product> GetProducts()
        {
            List<Product> products = new List<Product>();
            foreach (XElement pElem in _db.Descendants("Product"))
            {
                products.Add(GetProduct(pElem));
            }
            return products.AsQueryable();
        }

        [Query(IsDefault = true)]
        public IQueryable<ProductCategory> GetProductCategories()
        {
            List<ProductCategory> categories = new List<ProductCategory>();
            foreach (XElement catElem in _db.Descendants("ProductCategory"))
            {
                categories.Add(GetProductCategory(catElem));
            }

            return categories.AsQueryable();
        }

Note
You will see more errors at this point. You can ignore the errors; as soon as all of the code for the walkthrough has been added, the errors will be resolved.

Next, you will implement two custom queries. These will appear in the Data Sources node in LightSwitch at design time.

To implement custom queries

Add a CustomQueries region to the XMLDataSource class.
C#
VB
Copy
#region CustomQueries #endregion

Add the following code to the CustomQueries region.

//All query parameters need to be nullable. 
        public IQueryable<Product> GetProductsByCategory(Nullable<Guid> categoryID)
        {
            List<Product> products = new List<Product>();

            //Return no products if categoryID is as null.
            if (categoryID.HasValue)
            {
                foreach (XElement pElem in _db.Descendants("Product"))
                {
                    Product p = GetProduct(pElem);
                    if (p.CategoryID == categoryID.Value)
                    {
                        products.Add(p);
                    }
                }
            }
            return products.AsQueryable();
        }

        //Query that returns a single item.
        //Mark queries that return as single item as composable = false.
        [Query(IsComposable = false)]
        public Product GetProductByID(Nullable<Guid> productID)
        {
            Product product = null;

            //Only return a result if you are passed a value.
            if (productID.HasValue)
            {
                XElement pElem = (from XElement p in _db.Descendants("Product")
                                  where p.Element("ProductID").Value == productID.Value.ToString()
                                  select p).FirstOrDefault();
                if (pElem != null)
                {
                    product = GetProduct(pElem);
                }
            }
            return product;

        }

Next, define Update, Delete, and Insert methods for the product categories.

To add update, delete, and insert methods

Add a Category Update/Delete/Insert Methods region to the XMLDataSource class.
C#
VB
Copy
#region Category Update/Delete/Insert Methods #endregion

Add the following code to the Category Update/Delete/Insert Methods region.

public void InsertProductCategory(ProductCategory pc)
        {
            try
            {
                pc.CategoryID = Guid.NewGuid();
                XElement catElem = GetProductCategoryElem(pc);

                //Update the category ID on any related product entities.
                foreach (ChangeSetEntry e in ChangeSet.ChangeSetEntries)
                {
                    if (e.Entity is Product)
                    {
                        if (((Product)e.Entity).Category == pc)
                        {
                            ((Product)e.Entity).CategoryID = pc.CategoryID;
                        }
                    }
                }


                //Update the xml doc.
                _db.Element("ProductCategories").Add(catElem);
            }
            catch (Exception ex)
            {
                throw new Exception("Error inserting ProductCategory " + pc.CategoryName, ex);
            }
        }

        public void UpdateProductCategory(ProductCategory pc)
        {
            try
            {
                //Get existing item from the XML db.
                XElement storeCatElem =
                    (from c in _db.Descendants("ProductCategory")
                     where c.Element("CategoryID").Value == pc.CategoryID.ToString()
                     select c).FirstOrDefault();

                if (storeCatElem == null)
                {
                    //Category does not exist.  Indicate that the item has already been deleted.
                    ChangeSetEntry entry =
                        (from e in ChangeSet.ChangeSetEntries
                         where e.Entity == pc
                         select e).First();
                    entry.IsDeleteConflict = true;
                }
                else
                {
                    ProductCategory storeCategory = GetProductCategory(storeCatElem);

                    //Find entry in the changeset to compare original values.
                    ChangeSetEntry entry =
                        (from e in ChangeSet.ChangeSetEntries
                         where e.Entity == pc
                         select e).First();

                    //List of conflicting fields.
                    List<String> conflictMembers = new List<String>();

                    if (storeCategory.CategoryName != ((ProductCategory)entry.OriginalEntity).CategoryName)
                        conflictMembers.Add("CategoryName");
                    if (storeCategory.Description != ((ProductCategory)entry.OriginalEntity).Description)
                        conflictMembers.Add("Description");

                    //Set conflict members>
                    entry.ConflictMembers = conflictMembers;
                    entry.StoreEntity = storeCategory;

                    if (conflictMembers.Count < 1)
                    {
                        //Update the xml _db.
                        storeCatElem.ReplaceWith(GetProductCategoryElem(pc));
                    }
                }
            }
            catch (Exception ex)
            {
                throw new Exception("Error updating Category " + pc.CategoryID.ToString() + ":" + pc.CategoryName, ex);
            }
        }

        public void DeleteProductCategory(ProductCategory pc)
        {
            try
            {
                XElement storeCatElem =
                    (from c in _db.Descendants("ProductCategory")
                     where c.Element("CategoryID").Value == pc.CategoryID.ToString()
                     select c).FirstOrDefault();

                if (storeCatElem == null)
                {
                    //Category does not exist.  Indicate that the item has already been deleted.
                    ChangeSetEntry entry =
                        (from e in ChangeSet.ChangeSetEntries
                         where e.Entity == pc
                         select e).First();
                    entry.IsDeleteConflict = true;
                }
                else
                {
                    storeCatElem.Remove();
                }
            }
            catch (Exception ex)
            {
                throw new Exception("Error deleting Category " + pc.CategoryID.ToString() + ":" + pc.CategoryName, ex);
            }
        }

Next, implement a similar set of methods for products.

To add methods

Add a Product Update/Delete/Insert Methods region to the XMLDataSource class.
C#
VB
Copy
#region Product Update/Delete/Insert Methods #endregion

Add the following code to the Product Update/Delete/Insert Methods region.

public void InsertProduct(Product p)
        {
            try
            {
                p.ProductID = Guid.NewGuid();
                XElement productElem = GetProductElem(p);
                _db.Element("Products").Add(productElem);
            }
            catch (Exception ex)
            {
                throw new Exception("Error inserting Product " + p.ProductName, ex);
            }
        }

        public void UpdateProduct(Product p)
        {
            try
            {
                XElement storeProductElem =
                    (from c in _db.Descendants("Product")
                     where c.Element("ProductID").Value == p.ProductID.ToString()
                     select c).FirstOrDefault();

                if (storeProductElem == null)
                {
                    //Product does not exist.  Indicate that the item has already been deleted.
                    ChangeSetEntry entry =
                        (from e in ChangeSet.ChangeSetEntries
                         where e.Entity == p
                         select e).First();
                    entry.IsDeleteConflict = true;
                }
                else
                {
                    Product storeProduct = GetProduct(storeProductElem);

                    //Find the entry in the changeset to compare original values.
                    ChangeSetEntry entry =
                        (from e in ChangeSet.ChangeSetEntries
                         where e.Entity == p
                         select e).First();

                    //List of conflicting fields.
                    List<String> conflictMembers = new List<String>();

                    if (storeProduct.ProductName != ((Product)entry.OriginalEntity).ProductName)
                        conflictMembers.Add("ProductName");
                    if (storeProduct.CategoryID != ((Product)entry.OriginalEntity).CategoryID)
                        conflictMembers.Add("CategoryID");
                    if (storeProduct.QuantityPerUnit != ((Product)entry.OriginalEntity).QuantityPerUnit)
                        conflictMembers.Add("QuantityPerUnit");
                    if (storeProduct.UnitPrice != ((Product)entry.OriginalEntity).UnitPrice)
                        conflictMembers.Add("UnitPrice");
                    if (storeProduct.UnitsInStock != ((Product)entry.OriginalEntity).UnitsInStock)
                        conflictMembers.Add("UnitsInStock");
                    if (storeProduct.ReorderLevel != ((Product)entry.OriginalEntity).ReorderLevel)
                        conflictMembers.Add("ReorderLevel");
                    if (storeProduct.Discontinued != ((Product)entry.OriginalEntity).Discontinued)
                        conflictMembers.Add("Discontinued");

                    //Set conflict members.
                    entry.ConflictMembers = conflictMembers;
                    entry.StoreEntity = storeProduct;

                    if (conflictMembers.Count < 1)
                    {
                        //Update the xml _db.
                        storeProductElem.ReplaceWith(GetProductElem(p));
                    }
                }
            }
            catch (Exception ex)
            {
                throw new Exception("Error updating Product " + p.ProductID.ToString() + ":" + p.ProductName, ex);
            }
        }

        public void DeleteProduct(Product p)
        {
            try
            {
                XElement storeProductElem =
                    (from c in _db.Descendants("Product")
                     where c.Element("ProductID").Value == p.ProductID.ToString()
                     select c).FirstOrDefault();

                if (storeProductElem == null)
                {
                    //The product does not exist.  Indicate that the item has already been deleted.
                    ChangeSetEntry entry =
                        (from e in ChangeSet.ChangeSetEntries
                         where e.Entity == p
                         select e).First();
                    entry.IsDeleteConflict = true;
                }
                else
                {
                    //Remove it.
                    storeProductElem.Remove();
                }
            }
            catch (Exception ex)
            {
                throw new Exception("Error deleting Product " + p.ProductID.ToString() + ":" + p.ProductName, ex);
            }
        }

Next, add some helper functions.

To implement helper functions

Add a new region to the XMLDataSource class.
C#
VB
Copy
#region HelperFunctions #endregion

Add the following code to the Queries region.

private XElement GetProductElem(Product p)
        {
            XElement productElem = new XElement("Product",
                new XElement("ProductID", new object[] { new XAttribute("DataType", "Guid"), p.ProductID }),
                new XElement("ProductName", new object[] { new XAttribute("DataType", "String"), p.ProductName }),
                new XElement("CategoryID", new object[] { new XAttribute("DataType", "Guid"), p.CategoryID }),
                new XElement("QuantityPerUnit", new object[] { new XAttribute("DataType", "String"), p.QuantityPerUnit }),
                new XElement("UnitPrice", new object[] { new XAttribute("DataType", "Decimal"), p.UnitPrice }),
                new XElement("UnitsInStock", new object[] { new XAttribute("DataType", "Int32"), p.UnitsInStock }),
                new XElement("ReorderLevel", new object[] { new XAttribute("DataType", "Int32?"), p.ReorderLevel }),
                new XElement("Discontinued", new object[] { new XAttribute("DataType", "Boolean"), p.Discontinued })
                );
            return productElem;
        }

        private Product GetProduct(XElement pElem)
        {
            Product p = new Product();

            p.ProductID = new Guid(pElem.Element("ProductID").Value);
            p.ProductName = pElem.Element("ProductName").Value;
            p.CategoryID = new Guid(pElem.Element("CategoryID").Value);
            p.QuantityPerUnit = pElem.Element("QuantityPerUnit").Value;
            p.UnitPrice = decimal.Parse(pElem.Element("UnitPrice").Value);
            p.UnitsInStock = Int32.Parse(pElem.Element("UnitsInStock").Value);
            if (!String.IsNullOrWhiteSpace(pElem.Element("ReorderLevel").Value))
            {
                p.ReorderLevel = Int32.Parse(pElem.Element("ReorderLevel").Value);
            }
            p.Discontinued = Boolean.Parse(pElem.Element("Discontinued").Value);

            return p;
        }

        private ProductCategory GetProductCategory(XElement catElem)
        {
            ProductCategory pc = new ProductCategory();
            pc.CategoryID = new Guid(catElem.Element("CategoryID").Value);
            pc.CategoryName = catElem.Element("CategoryName").Value;
            pc.Description = catElem.Element("Description").Value;

            return pc;
        }

        private XElement GetProductCategoryElem(ProductCategory pc)
        {
            XElement catElem = new XElement("ProductCategory",
               new XElement("CategoryID", new object[] { new XAttribute("DataType", "Guid"), pc.CategoryID }),
               new XElement("CategoryName", new object[] { new XAttribute("DataType", "String"), pc.CategoryName }),
               new XElement("Description", new object[] { new XAttribute("DataType", "String"), pc.Description })
               );
            return catElem;
        }

Next, add a Comparer class to the XMLDataSource.vb or XMLDataSource.cs file.

To add the comparer class

The following code retrieves the file name and connection string from the web.config file, verifies the file, and adds the XML elements if it is required. Add the code after the XMLDataSource class, inside the DataSourceExtension.DataSources namespace.

public class ProductEntitiesComparer : Comparer<object>
    {
        public override int Compare(object x, object y)
        {
            if (x is Product && y is ProductCategory)
                return 1;
            else if (x is ProductCategory && y is Product)
                return -1;
            else
                return 0;
        }
    }

These steps conclude the XMLDataSource class. The code in this class not only has service connection related code, but also two queries, one to retrieve product by ID and another to get product by category. These queries can be used in a LightSwitch application as well.

The next step is to create two classes to store the Product and ProductCategory data.

Create Product and Product Category Classes

In addition to the XMLDataSource class, you will also need two more classes to represent the Product and ProductCategory entities. These two classes will be added to the DataSourceExtension.Server project.

To add the Product class

In Solution Explorer, choose the DataSourceExtension.Server project.
On the Project menu, choose Add Class.
In the Add New Item dialog box, choose the Name field, type Product, and then choose the Add button.

In the Product file, replace the existing contents with the following code.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;


namespace DataSourceExtension
{
    public class Product
    {
        [Key()]
        [ReadOnly(true)]
        [Display(Name = "Product ID")]
        [ScaffoldColumn(false)]
        public Guid ProductID { get; set; }

        [Required()]
        [Display(Name = "Product Name")]
        public string ProductName { get; set; }

        [Required()]
        [Display(Name = "Category ID")]
        public Guid CategoryID { get; set; }

        [Display(Name = "Quantity Per Unit")]
        public string QuantityPerUnit { get; set; }

        [Range(0, double.MaxValue, ErrorMessage = "The specified price must be greater than zero.")]
        [Display(Name = "Unit Price")]
        public Decimal UnitPrice { get; set; }

        [Display(Name = "Units In Stock")]
        [Range(0, Int32.MaxValue, ErrorMessage = "Cannot have a negative quantity of products.")]
        public Int32 UnitsInStock { get; set; }

        [Display(Name = "Reorder Level")]
        public Nullable<Int32> ReorderLevel { get; set; }

        [Display(Name = "Discontinued")]
        public Boolean Discontinued { get; set; }

        [Association("Product_Category", "CategoryID", "CategoryID", IsForeignKey = true)]
        [Display(Name = "Category")]
        public ProductCategory Category { get; set; }
    }
}

To add the ProductCategory class

In Solution Explorer, choose the DataSourceExtension.Server project.
On the Project menu, choose Add Class.
In the Add New Item dialog box, choose the Name field, type ProductCategory, and then choose the Add button.

In the ProductCategory file, replace the existing contents with the following code.

 using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace DataSourceExtension
{
    public class ProductCategory
    {
        [ReadOnly(true)]
        [Key()]
        [Display(Name = "Category ID")]
        [ScaffoldColumn(false)]
        public Guid CategoryID { get; set; }

        [Required()]
        [Display(Name = "Category Name")]
        public string CategoryName { get; set; }

        [Display(Name = "Description")]
        public String Description { get; set; }

        [Display(Name = "Products")]
        [Association("Product_Category", "CategoryID", "CategoryID")]
        public ICollection<Product> Products { get; set; }
    }
}

These steps conclude the code for the data source extension. Now you can test it in an experimental instance of Visual Studio.

Test the Data Source Extension

You can test the data source extension in an experimental instance of Visual Studio. If you have not already tested another LightSwitch extensibility project, you have to enable the experimental instance first.

To enable an experimental instance

In Solution Explorer, select the DataSourceExtension.Vsix project.
On the menu bar, choose Project, DataSourceExtension.Vsix Properties.
On the Debug tab, under Start Action, choose Start external program.
Enter the path of the Visual Studio executable, devenv.exe.
By default on a 32-bit system, the path is C:\Program Files\Microsoft Visual Studio 11.0\Common7\IDE\devenv.exe; on a 64-bit system, it is C:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\devenv.exe.
In the Command line arguments field, type /rootsuffix Exp as the command-line argument.
Note
All subsequent LightSwitch extensibility projects will also use this setting, by default.

Note
All subsequent LightSwitch extensibility projects will also use this setting, by default.

To test the data source extension

On the menu bar, choose Debug, Start Debugging. An experimental instance of Visual Studio opens.
In the experimental instance, on the menu bar, choose File, New Project.
In the New Project dialog box, select the LightSwitch node, and then select LightSwitch Application (Visual Basic) or LightSwitch Application (C#).
In the Name field, type DataSourceTest, and then choose the OK button to create a test project.
On the menu bar, choose Project, DataSourceTest Properties.
In the project designer, on the Extensions tab, check the DataSourceExtension check box.
On the menu bar, choose Project, Add Data Source.
In the Attach Data Source wizard, choose WCF RIA Service, and then choose the Next button.
Choose DataSourceExtension.DataSources.XMLDataSource, and then choose the Next button.
Expand the Entities node, and then choose both Product and ProductCategory.
In the Connection String field, type C:\Temp\Products.xml, and then choose the Finish button.
The data source is added to the Data Sources node in Solution Explorer. Notice that both the ProductCategory and Products tables appear, and the GetProductByID and GetProductsByCategory queries appear under Products.
Create an application that has screens that use the tables and the queries, and then run the application to observe the behavior.
Notice that the data source functions just like any other data source. This allows you to add, delete, and update data.

Next Steps

This concludes the data source walkthrough; you should now have a fully functioning data source extension that you can reuse in any LightSwitch project. This was just one example of a data source; you might want to create a data source that accesses a different type of data. The same basic steps and principles apply.

If you are going to distribute your extension, there are a couple more steps that you should take. To make sure that the information displayed for your extension in the Project Designer and in Extension Manager is correct, you can update the properties for the VSIX package. For more information, see How to: Set VSIX Package Properties. In addition, there are several things that you should consider if you are going to distribute your extension publicly. For more information, see How to: Distribute a LightSwitch Extension.

Tasks

How to: Set VSIX Package Properties

How to: Distribute a LightSwitch Extension

Concepts

LightSwitch Extensibility Toolkit for Visual Studio 2012

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)