August 2011

Volume 26 Number 08

Visual Studio LightSwitch - Advanced Programming Made Easy With Visual Studio Lightswitch

By Beth Massi | August 2011

Visual Studio LightSwitch is a new product in the Visual Studio family aimed at developers who want to quickly create data-centric business applications for the desktop and the cloud. LightSwitch is an extensible development environment that simplifies the development process because it lets you concentrate on the business logic while it takes care of a lot of the remaining work. LightSwitch is perfect for small business or departmental productivity applications that need to be done fast.

It’s easy to quickly get up and running in LightSwitch so you can focus on features important to your business. You don’t necessarily need to write code to get a LightSwitch application up and running, but you’ll quickly realize that code is necessary for business rules, screen workflows and other user productivity features specific to your business requirements. Moreover, you can download and install LightSwitch extensions from the Visual Studio Gallery that add features to your application that aren’t available out of the box. You can even create extensions yourself using Visual Studio Professional or higher. It’s a good bet that the community will be creating some interesting extensions for LightSwitch!

This article is aimed at the professional developer using LightSwitch to speed up development of a typical data-centric business application, or enhancing a LightSwitch application that was initially built by someone else. I’m going to walk through some of the more advanced development and customization techniques available to LightSwitch developers. I’ll show you how to work with LightSwitch APIs, create custom screen layouts, use advanced query processing, write complex business rules, and use and create LightSwitch extensions. You’ll see that programming even the more advanced features of a LightSwitch business application is simplified dramatically because LightSwitch handles all the plumbing for you. You can download the sample application I’ll be discussing at

If you’re not familiar with creating a basic application using LightSwitch, I encourage you to take a look at some of the resources available on the LightSwitch Developer Center at

Architecture Overview

Before we dive into advanced LightSwitch development, it’s important to understand the architecture of a LightSwitch application. LightSwitch applications are based on Silverlight and a solid .NET application framework using well-known patterns and best practices, like n-tier application layering and Model-View-ViewModel (MVVM), as well as technologies like the Entity Framework and WCF RIA Services (see Figure 1). The LightSwitch team made sure not to invent new core technologies, such as a new data-access or UI layer; instead we created an application framework and development environment around these existing Microsoft .NET Framework-based technologies that lots of developers are already building on today.

LightSwitch Application Architecture

Figure 1 LightSwitch Application Architecture

This architecture means LightSwitch applications can be deployed as desktop applications, with the ability to integrate with hardware devices such as a scanner or bar code reader, as well as other applications like Microsoft Word and Excel; or they can be deployed as browser-based applications when broader reach is required. You can also host LightSwitch applications in a variety of ways, including with Azure.

LightSwitch is all about data and screens. The data in a screen is managed by a data workspace, which is responsible for fetching entities from a data service in the middle tier via queries, for tracking changes, and for sending updates back through the save pipeline to the middle-tier data service. When you execute the save command, it invokes the data service with one change set, which runs in one update transaction against the data source. You can have multiple data sources in LightSwitch (and even relate entities across data sources). Each data source you bring into your LightSwitch application has its own data workspace. From the data workspace, you can access all the queries and update operations against the data source. Entities themselves also expose underlying details, such as their entity state and original and current values.

Visual Studio LightSwitch is its own edition of Visual Studio. Its entire development environment is streamlined to focus on building LightSwitch applications. Even with just the LightSwitch edition installed, developers have access to all the LightSwitch APIs, the Silverlight and .NET frameworks, custom screen layouts and screen workflows, complex validation, the save pipeline and access control hooks. You can write complex and composite LINQ queries and use COM interop, as well as access both client and server project code.

However, if you already have Visual Studio Professional or higher installed, LightSwitch will integrate into those editions and LightSwitch applications will show up as just another project template in the New Project dialog. In addition, you also have the ability to create custom controls and extensions for LightSwitch.

Customization and Extensibility Points

LightSwitch allows a wide spectrum of customization, from simple code customization all the way to authoring full-blown extensions and distributing them to other LightSwitch developers.

There are a lot of built-in hooks to write code in LightSwitch for entities, queries and screens. At the top of each designer you’ll see a “Write Code” drop-down button that shows the method hooks available. This is how you write validation and security rules, as well as how you tap into the save pipeline and query processing. Some code you write runs on the server, some on the client and some runs on both. Typically LightSwitch developers don’t need to know where their code is running; LightSwitch takes care of all of that for you. However, if you want to provide additional functionality and need to write specific code on the client or the server, you need to know a little bit about the structure of a LightSwitch solution.

When you look at a LightSwitch application in the Solution Explorer, by default you’re in “Logical View.” However, you can see the actual project and file structure if you select “File View,” as shown in Figure 2.

Flip to File View to See the Physical Structure

Figure 2 Flip to File View to See the Physical Structure

In File View you can see the Client and Server projects and, under those, a UserCode folder where all the code you write through the LightSwitch development environment is physically placed. You can add your own code files and classes here and call them from your LightSwitch code. Just keep in mind that the client is running under the Silverlight framework and the server is running under the full .NET Framework 4. I’ll show you a couple of examples later.

The next level of customization is authoring custom controls and custom data sources and using them directly in your LightSwitch project. For instance, you may choose to create your own special Silverlight control that provides some specific functionality and then use that on your LightSwitch screens. If you have Visual Studio Professional or higher, you have access to the Silverlight class library project template and you can simply build your own control library and use it in LightSwitch. You can also create WCF RIA Services to connect to data sources not supported out of the box in LightSwitch. However, in order to make these custom controls and data sources available to someone who only has the Visual Studio LightSwitch edition installed, you package them up into a LightSwitch extension.

There are six extensibility points in LightSwitch:

  1. Custom Control A control extension consists of one or more Silverlight controls, which can bind to a single scalar value or a collection of data. It can also group other controls together. A control extension can be a single control; for example, a star-rating control or gauge or even a map control. It could also be a group of controls; for example, shipping information.
  2. Screen Template When creating a screen, you’re presented with a list of templates. A screen template extension creates a new template that can be added to the list. This allows a custom screen to specify a layout for the controls contained within the screen.
  3. Business Type Business types are unique to LightSwitch; they allow you to provide canned validation and formatting for entity properties. When you build this type of extension, you define an editor control and formatting as well as validation for the type. For instance, Phone Number and Email Address are built-in business types in LightSwitch and can be configured declaratively via the properties window. You could create a business type for Social Security Number or Packaging SKU that comes with specific validation and formatting.
  4. Shell A shell provides the look and feel of the app—its “skin.” It can also provide navigation, commands and screens. It’s totally up to you to decide how to use the shell to present these—or not present them.
  5. Theme Themes provide the color palette for a LightSwitch application. The font styles and brush colors you specify in a theme are applied to the built-in shell, or to a custom shell you build yourself.
  6. Custom Data Sources All applications need some kind of data source. LightSwitch lets you connect to databases, SharePoint lists and WCF RIA Services. With this extension type, you can connect to external data sources using WCF RIA Services.

To build extensions, you need Visual Studio Professional or higher, the Visual Studio SDK and the LightSwitch Extensibility Toolkit. Extensions are distributed just like any other Visual Studio extension via VSIX packages, and deployed to the Visual Studio Gallery. You can then install them using the Extension Manager, which is also included with Visual Studio LightSwitch.

Now that you understand the architecture, solution structure and spectrum of extensibility in LightSwitch applications, let’s dive into some advanced features of the Contoso Construction sample application. I built the entire application without any specific custom control or data source customizations, so it requires only Visual Studio LightSwitch. However, I did install and use publicly available extensions to enhance the application, and I’ll walk through how they work later.

The Contoso Construction Application

When you log into the Contoso Construction application, the first thing you’re presented with is a tailored home screen that displays common tasks, your appointments for the day and current projects, as shown in Figure 3. The application tracks customers and their construction projects as well as materials used on the projects. It also allows users to manage photos taken for each project and to schedule appointments between employees and customers.

The Contoso Construction Application Home Screen
(click to zoom)

Figure 3 The Contoso Construction Application Home Screen

When you select a project, the Project Details screen opens, displaying a tab control with its related children, the project’s materials and pictures. Saving pictures into the database with LightSwitch is handled automatically when you specify that a property of an entity be of the built-in type Image—which comes with a picture editor and display.

The Project Details screen also has a button on the ribbon to generate a project status report. It uses COM to automate Microsoft Word to send the project and materials list to the document. Other features of the application include e-mail integration on the server to send appointments to customers and employees, audit trails, reports with aggregate queries, and a custom query builder. LightSwitch already has built-in support for exporting data in grids to Excel. The Contoso Construction application also has an import feature that lets users upload materials data from spreadsheets directly into the screen. Let’s walk through some of the more advanced pieces of the application to see how they were built.

Complex Screen Layouts

When building screens in LightSwitch, every control in the content tree must be bound to a data item. The data item can be a field on an entity, a collection of entities or any other data item you add to the ViewModel. The screen templates help guide you in setting up a layout and all the data binding for a particular type of screen—be that a search screen, a details screen, a new data screen or any other type of screen. Some screens work with single entities and others work with collections of entities. The Search Screen, Editable Grid Screen, and List and Details Screen templates work with collections of entities returned from a query that you can define. The Edit Details Screen works with a specific entity and it passes a parameter into the query that’s the unique ID of the entity to retrieve.

These templates are just starting points that you can customize further. In fact, you can select a screen template that works with a collection of entities, but not choose any data for the screen. For instance, in the Add New Screen dialog, you can select the Search Screen and then immediately click OK. This creates a blank “canvas” that allows you to start from scratch. Alternatively, when you select a template you can select the basic screen data you want to present and then add more data items to the screen as needed.

Data items can be basic properties like strings or integers; they can be methods you call from screen code or buttons; or they can be entities that originate from queries. To add a data item manually to a screen, click the Add Data Item button at the top of the screen designer. You can then specify the name and type of the data item. The home screen is a combination of all of these types of data items, as you can see in Figure 4.

Data Items and the Content Tree in Screen Designer
(click to zoom)

Figure 4 Data Items and the Content Tree in Screen Designer

You have a lot of flexibility with screens when laying out content in the tree. Once you add all of your data items, in order to make layout changes it’s usually easier to just run the application (press F5), open the screen and then click Design Screen in the upper-right corner of the application. This allows you to make layout changes and see the updates in real time. You can use grouping controls like the Table Layout and Rows and Columns Layouts to fine-tune exactly where and how controls should display. You can then tweak the sizing properties in the Properties window to specify the exact size. In addition to the screen command bar (which displays on the ribbon across the top of the application), you can also specify command bars for any control. This gives you the ability to place buttons or hyperlinks under any item in the tree. In Figure 4 you can see that the command bar for the static text property called Search Projects has its Control Type set to Link, which appears left-justified under the text when running (Figure 3).

The home screen displays a lot of static text and images. Adding images to buttons on screens is as easy as setting them in the Properties window. However, when you want to display an image or static text on the screen directly, you need to do a couple of things. You add static images and text to the screen as local properties via the Add Data Item dialog and then lay them out in the content tree. Because static properties do not originate from a data entity, you need to set the property value before the screen is displayed. You do this in the screen’s InitializeDataWorkspace method, which runs before any queries execute. For example, to set one image and one text static property, you’d write code similar to this:

Private Sub Home_InitializeDataWorkspace(saveChangesTo As List(Of IDataService))
  ' Initialize text properties
  Text_Title = "Contoso Construction Project Manager"
  ' Initialize image properties
  Image_Logo = MyImageHelper.GetImageByName("logo.png") 
End Sub

In order to load a static image, you switch to File View and place it in the Client project’s \Resources folder, then set the build action to “Embedded Resource.” Then you need to write some code to load the image. The Contoso Construction sample application uses static images in a variety of screens, so I created a helper class called MyImageHelper that can be used from anywhere in the client code. While in File View, right-click on the \UserCode folder in the Client project and select Add | Class. Name it MyImageHelper and create a static (Shared) method that loads the image, as shown in Figure 5.

Figure 5 The MyImageHelper Class

''' <summary>
''' This class makes it easy to load images from the client project.
''' </summary>
''' <remarks></remarks>
Public Class MyImageHelper
  Public Shared Function GetImageByName(fileName As String) As Byte()
    Dim assembly As Reflection.Assembly = 
    Dim stream As Stream = assembly.GetManifestResourceStream(fileName)
    Return GetStreamAsByteArray(stream)
  End Function

  Private Shared Function GetStreamAsByteArray(
                          ByVal stream As System.IO.Stream) As Byte()
    If stream IsNot Nothing Then
      Dim streamLength As Integer = Convert.ToInt32(stream.Length)
      Dim fileData(streamLength - 1) As Byte
      stream.Read(fileData, 0, streamLength)
      Return fileData
      Return Nothing
    End If
  End Function
End Class

You can add any custom code to the client this way. For instance, the Contoso Construction sample application also has helper classes for exporting construction project data to Word via COM. The bottom line is that you have a lot of flexibility to add your own custom code and classes to LightSwitch.

Working with the Save Pipeline

You can also add your own code to the server project in the same way. In the sample, there’s an appointment screen that allows users to set up appointments between customers and employees. If the customer and the employee have e-mail addresses, an e-mail appointment (iCal) is sent to both parties when the appointment entity is inserted into the data source. The save pipeline exposes many methods that you can use to write business rules, call other services or kick off workflows, including Inserted/Inserting, Updated/Updating and Deleted/Deleting methods for every entity.

The helper class to send the appointment via SMTP e-mail is located in the Server project’s \UserCode folder, and it’s called SMTPMailHelper. The application also sends updates and cancellations when appointments are updated or deleted in the system. In order to access these save pipeline methods, select the entity in the designer and then the Write Code button drop-down. When you hover over the methods, the tooltip will tell you whether the code runs on the client, the server or both. In the case of the Appointment entity, we need to inject code into the server-side methods shown in Figure 6 in order to track and send new, updated and canceled appointment e-mails.

Figure 6 Server-Side Methods to Track and Send Appointment E-mails

Private Sub Appointments_Inserting(ByVal entity As Appointment)
  'Used to track any iCalender appointment requests
  entity.MsgID = Guid.NewGuid.ToString()
  entity.MsgSequence = 0
End Sub

Private Sub Appointments_Updating(ByVal entity As Appointment)
  'Update the sequence anytime the appointment is updated
   entity.MsgSequence += 1
End Sub

Private Sub Appointments_Inserted(ByVal entity As Appointment)
  'Send an email notification when an appointment is inserted into the system
  Dim isCanceled = False
End Sub

  Private Sub Appointments_Updated(ByVal entity As Appointment)
    'Send an email update when an appointment is updated. 
    Dim isCanceled = False
End Sub

   Private Sub Appointments_Deleting(entity As Appointment)
     'Send an email cancellation when an appointment is deleted.
     Dim isCanceled = True

End Sub

You’ll also work with the save pipeline when you implement an audit trail. Audit trails are common in business applications and are used to track what changes were made and by whom to records in the system. In the sample application, a table called EmployeeChange tracks changes to fields on the Employee, as shown in Figure 7.

An Audit Trail Is a Common Business Application Requirement

Figure 7 An Audit Trail Is a Common Business Application Requirement

To capture the new and original values on an Employee that’s being updated, you can drill into the Details property of the entity. This allows you to get at the more advanced entity API. In the Employees_Updating method, you can dynamically loop through all the storage properties on the entity and record their new and original values, as shown in Figure 8.

Figure 8 Drilling into the Employee Entity Details Property to Create an Audit Trail

Private Sub Employees_Updating(entity As Employee)
  'Audit trail that tracks changes to employee records
  Dim change = entity.EmployeeChanges.AddNew()
  change.Employee = entity
  change.Updated = Now()
  change.ChangedBy = Me.Application.User.FullName
  Dim newvals = "New Values:"
  Dim oldvals = "Original Values:"

  For Each prop In entity.Details.Properties.All().
    OfType(Of Microsoft.LightSwitch.Details.IEntityStorageProperty)()

    If prop.Name <> "Id" Then
      If Not Object.Equals(prop.Value, prop.OriginalValue) Then
        oldvals += String.Format("{0}{1}: {2}", 
        newvals += String.Format("{0}{1}: {2}", 
      End If
    End If
  change.OriginalValues = oldvals
  change.NewValues = newvals
End Sub

For more information on the save pipeline, validation framework and entity API, see the Working with Code section of the LightSwitch Developer Center (

Advanced Queries

Because LightSwitch applications are all about data and screens, it’s not surprising that you can create queries. The query designer provides a quick, simple way to define filters, sorts and query parameters, as well as specify whether the query should return one or many rows. You can also base queries on other queries, which comes in handy when you always have a filter or sort you want applied to a set of data. You can also specify required and optional parameters. However, the query designer does have its limits. Luckily, you can click on the Write Code button at the top of the designer (or click “Edit Additional Query Code” in the properties window) and write code in the PreprocessQuery method.

In the Contoso Construction application, there’s a query called CurrentProjects, as shown in Figure 9. The CurrentProjects query only defines an optional parameter through the designer; the rest of the query is handled in code.

The CurrentProjects Query
(click to zoom)

Figure 9 The CurrentProjects Query

Notice that this query only defines an optional parameter and doesn’t specify a filter or sort. We need to check if the parameter is supplied and, if so, evaluate its value to determine if a filter should be applied. The PreprocessQuery method is passed any parameters that you define in the designer as well as the query itself. This means that you can define filter and sort clauses in the designer and then add to the query by writing LINQ code to filter or sort it further. Just keep in mind that you always need to return a collection of entity types that LightSwitch expects; you can’t 
return projections or other types.

So, in the PreprocessQuery method, you can write code as in Figure 10.

Figure 10 Intercepting Queries in the PreprocessQuery Method

Private Sub CurrentProjects_PreprocessQuery(
  ShowAllProjects As System.Nullable(Of Boolean),
  ByRef query As System.Linq.IQueryable(Of LightSwitchApplication.Project))

  'If ShowAllProjects is False (or Nothing) then just pull up the 
  ' projects that do not have an actual end date specified. 
  If Not (ShowAllProjects.HasValue) Then ShowAllProjects = False

  If Not (ShowAllProjects) Then
    query = From p In query
            Where p.ActualEndDate Is Nothing
            Select p

  End If
End Sub

Now when you create a screen based on the query, LightSwitch will see that there’s an optional parameter, then automatically create that screen data item for you and bind it to the query parameter. Because Show All Projects is a Boolean, it will create a checkbox, and when the user clicks the box the query will execute automatically.

I hope you’re starting to see all the code hooks that LightSwitch provides; queries are no different. Another interesting query in the sample application uses an aggregate to find projects that are over budget. This query doesn’t specify anything in the designer; it uses only code, because it needs to aggregate child data to calculate the materials cost on the project:

Private Sub ProjectsOverBudget_PreprocessQuery(
  ByRef query As System.Linq.IQueryable(Of LightSwitchApplication.Project))

  'Return projects where the cost is over the original estimate
  query = From p In query
          Let cost = p.Labor + 
            (Aggregate m In p.ProjectMaterials Into Sum(m.Quantity * m.Price))
          Where cost > p.OriginalEstimate
          Order By p.StartDate
          Select p
End Sub

In the sample application, these two queries are presented on Search Data Screens so that users can export the results to Excel, analyze the data and create reports. Because these reports are used often, it makes sense to have them hardcoded. However, it would be nice to allow users to define their own custom reports. You can do just that by installing the Filter Control extension that’s available in the Samples Gallery, which includes all the source code, at

Using Extensions

LightSwitch extensions are installed like any other Visual Studio extensions. Click on the VSIX file to install, then restart Visual Studio. Open your LightSwitch Project Properties and you’ll see an Extensions tab that allows you to select which extensions to use in the project, as shown in Figure 11.

Enabling an Extension on the Extensions Tab of the LightSwitch Project Properties

Figure 11 Enabling an Extension on the Extensions Tab of the LightSwitch Project Properties

To use the filter control extension, create a query and add a single string parameter called FilterTerm, then add the following code to the PreprocessQuery method:

query = LightSwitchFilter.Server.Filter(query, FilterTerm, Me.Application)

Next, add a screen based on the query and in the screen designer 
change the control type for the 
Filter Term control to “Advanced Filter Builder,” and change the label position to “None.” In the Contoso Construction sample application, the query is called CustomFilterProjects and the screen is called CustomReport.

When you run the sample application and open the Custom Report screen, the filter builder control will be displayed. Once you’ve defined the filter, the Go button will execute it against the server. The filter is a Silverlight control that will generate an XML representation of the designed filter. This is then passed to the query as a string. On the server, the query code will parse the XML and generate appropriate filter clauses.

Another handy extension is the Excel Importer extension that you can get at, along with all the source code.

LightSwitch already has built-in support for exporting data in grids to Excel. The Excel Importer lets you import data from spreadsheets by mapping Excel columns to properties of an entity. This extension is used on the Materials Catalog screen in the sample application. Once you install and enable the extension, create an Editable Grid Screen and add a button to the screen command bar. In the Execute method for the command you only need to write one line of code:

Private Sub ImportFromExcel_Execute()
End Sub

As you can see, it’s very easy to install and use extensions in LightSwitch to provide additional capabilities. When you package up your customizations as extensions, you can distribute them broadly to other LightSwitch developers.

Build Your Own Extensions

To build extensions, you’ll need Visual Studio Professional SP1 or higher with LightSwitch installed, the Visual Studio SDK and the LightSwitch Extensibility Toolkit, which you can download from the LightSwitch Developer Center ( This adds Visual Basic and C# extensibility project templates under the LightSwitch node in your New Project dialog.

Let’s create a simple theme for our Contoso Construction application. First create a new LightSwitch Extension Library project; I’ll call it ContosoThemes. This sets up all the necessary projects for the extension. You’ll notice a similarity to the File View of a LightSwitch application, but there are some additional projects included, namely the LSPKG and the VSIX projects.

Next, right-click on the ContosoThemes.LsPkg and select Add New Item. Here you’ll see the set of supported LightSwitch Extension templates. Select the LightSwitch Theme item and give it a name—I’ll call it PurpleTheme. The new theme’s pre-canned XAML file will be created and opened in the IDE. By default, it has all the brushes and styles that are in the standard shell theme. You can use any tool you like to set the colors and styles for every item that LightSwitch displays in its shell. For this example, I’ll just change a few colors using the XAML editor and the properties window to select colors, as shown in Figure 12.

Creating a LightSwitch Theme Extension
(click to zoom)

Figure 12 Creating a LightSwitch Theme Extension

Once you’re ready to test your extension, you can hit F5 to launch a debug IDE instance. To test the theme, create a new LightSwitch project in this instance. Open the LightSwitch Project Properties and on the Extensions tab enable the ContosoThemes extension you just built. Next, switch to the General tab and select the PurpleTheme. You’ll need to create entities and screens so you can see your theme in action; then you can press F5 in your test project to see what it looks like.

When you’re happy with your theme, build the extension in Release mode—then you can hand the VSIX package located in the \bin\Release folder of the VSIX project to a LightSwitch developer to use on any of her projects. You can also upload it to the Visual Studio Gallery for broad distribution. Figure 13 shows what the theme looks like in the Contoso Construction application.

Applying a Theme Extension to a LightSwitch Application
(click to zoom)

Figure 13 Applying a Theme Extension to a LightSwitch Application

For more information on building LightSwitch Extensions, see the Advanced Topics section of the LightSwitch Developer Center (

Wrapping Up

LightSwitch dramatically simplifies the development of data-centric business applications because it takes care of all the plumbing for you. It allows you to concentrate on the business logic and other custom features that your users need to get their jobs done efficiently. There are many levels of customization available to LightSwitch developers, as well as to professional developers looking to build LightSwitch extensions for the community. I hope this article has shown you how flexible and customizable LightSwitch can be. For information, training, samples, videos, forums, community and more, please visit the LightSwitch Developer Center at


Beth Massi is a senior program manager on the Microsoft Visual Studio BizApps team, which builds the Visual Studio tools for Azure, Office and SharePoint, as well as Visual Studio LightSwitch. Massi is a community champion for business application developers and is responsible for producing and managing online content and community interaction for the BizApps team. She has more than 15 years of industry experience building business applications and is a frequent speaker at software development events. You can find her on a variety of developer sites, including MSDN Developer Centers, Channel 9 and her blog, Follow her on Twitter at

Thanks to the following technical expert for reviewing this article: Robert Green