Beth Massi - Sharing the goodness that is VB

LightSwitch Screen Tips: Scrollbars and Splitters

2012-02-09T15:08:00Z

Often times in business applications we have a lot of information to present on a screen, and depending on the user’s screen resolution that information may scroll off the page. Visual Studio LightSwitch’s screen templates are set to automatically apply a vertical scrollbar to screens when this happens, however, sometimes we rather allow the user to resize sections of the screen how they see fit. It’s common in screen design to use splitter controls to do this. Splitters are a useful UI feature where the width or height of a control on the screen can be modified to show more or less information. In this post I’ll show you how you can enable splitter controls to appear in LightSwitch as well as control how scrollbars behave.

Create Your Screen

First create a screen with all the information you want to display. For this example I will use the ContactDetails screens we created in the Address Book Sample. In this example, Contacts have many Addresses, PhoneNumbers and EmailAddresses. By default, LightSwitch will place the Contact fields at the top of the screen with a Tab Control of three DataGrids representing the children.

Here is what the screen looks like:

And here is the content tree for the screen:

Scrollbars in LightSwitch

Imagine that over time our contacts get more and more email addresses, phone numbers, and/or addresses. If the user’s screen resolution is low (or the size of the application shell is not maximized) then LightSwitch will place a vertical scrollbar on the screen by default (I added the green box for clarity ;-))

This is controlled by selecting the topmost Rows Layout and under the Appearance properties you will see “Vertical Scroll Enabled” checked. Notice there is also a “Horizontal Scroll Enabled” property you can use to enable horizontal scrollbars when needed. All group controls in LightSwitch have these properties (i.e. Rows Layout, Columns Layout, Table Layout)

Leaving this checked however, means that the user cannot see all the email addresses and the First & Last name fields at the same time. There are a couple things we can do here. One is we can disable vertical scroll of the screen. Once we do that LightSwitch will automatically place the scrollbar into the grid itself instead.

But what if we aren’t using a DataGrid (or list control) below the list of fields? Or what if we want the user to choose how many rows they need to view at a time? In those cases, we can allow the user to resize the panels of information using a splitter.

Adding a Horizontal Splitter

In order to provide this functionality, we can place a splitter between the list of fields at the top and the tab control below. While the application is running in debug mode, click the “Design Screen” at the top-right of the shell to open Customization Mode. Select the nested Rows Layout control for Contact and under the sizing properties you will see a check box “Is Row Resizable”.

Check that and then click Save to save your changes. You will now see a splitter control that you can use to resize the top and bottom panels.

In this case you probably also want to set a minimum and maximum height of this Rows Layout panel so that the user doesn’t use the splitter to wipe the grid completely off the screen. Right now if you take and drag the splitter off the screen, the grid will completely disappear. In order to stop this, you can set the MinHeight and MaxHeight properties. You can enable a scroll bar to appear in the top panel when needed by checking “Vertical Scroll Enabled” as well.

Adding Vertical Splitters

You can also add vertical splitters in a similar way. Instead of displaying DataGrids in separate tabs, say we want to display them side-by-side. Open customization mode again and change the Tabs Layout to a Columns Layout.

Then select each DataGrid and in the Sizing properties, check “Is Column Resizable”.

Now you can resize all of the columns containing the DataGrids. The DataGrids will automatically put a horizontal scrollbar at the bottom so users can see all the fields as necessary.

Another Example

Splitters and scrollbars really start helping you out when you have sections of information and/or commands that you want to allow the user to resize. Here I modified the Contoso Construction example to allow resizing of the tab control of commands on the left and the information on the right.

Wrap Up

There are a lot of things you can do with the LightSwitch Screen designer in order to provide completely customized layouts. Controlling scrollbars and adding splitters is just another way you can achieve what you want. For more tips and tricks on customizing screens see:

Enjoy!

LightSwitch Community & Content Rollup–January 2012

2012-02-02T15:30:00Z

Last Fall I started posting a rollup of interesting community happenings, content, samples and extensions popping up around Visual Studio LightSwitch. If you missed those rollups you can check them out here:

Looks like folks took a few well-deserved days to ramp back into the groove after the holidays (including myself). But there were still a lot of awesome things around LightSwitch this month, especially the number of submissions The Code Project had in the LightSwitch Star Contest. A lot of really interesting applications and some great case studies for LightSwitch as well as some for Azure. Check them out…

“LightSwitch Star” Contest

In November The Code Project launched the “LightSwitch Star” contest. They’re looking for apps that show off the most productivity in a business as well as apps that use extensions in a unique, innovative way. Prizes are given away each month. Soon they will announce the January winners as well as the two grand prize winners of an ASUS U31SD-DH31 Laptop!

Check out all the submission we had in January and make sure to log onto Code Project and vote for your favorites. Here’s a breakdown of the 13 apps that were submitted in January (see all 34 apps that have been submitted here). There are some very creative “business apps” here – like a campaign manager for Dungeons & Dragons!

Profiling-Pro (video) – Project profiler that helps make sure your software projects are done on time
Luminous Commands For LightSwitch - Luminous Commands provides two pieces of functionality that was missing from LS RTM but wanted by many users
Access Control Manager - The Access Control Manager tracks user access to applications and other products (such as hardware, cellphones, etc.) by creating requests for access by the supervisor of the user
Light Enterprise Solution - An article about applications that is an enterprise system targeted for Small & Medium Enterprises in Malaysia and Singapore
LightSwitch Job Hunter Application - Job application tracker for those out of work built using Visual Studio LightSwitch 2011.
Job Hunter LightSwitch Application (video) - This is a demo video of a free application that is intended to help job applicants. The application and source code are free to download
Illuminous overview (video) - Illuminous is a comprehensive college management tool developed using Visual Studio LightSwitch.
Data Centre: A Product Information and Promotion Management System - A system for easily and effectively storing product information and managing promotions.
Visual Studio LightSwitch Application Database Script Generator - A tool to generate Sql server DB script from the LightSwitch internal database
MyBizz Portal - The "smallest" LightSwitch application you have ever seen. A portal to other LightSwitch applications.
Client Management System - A complete CRM solution that manages the entire customer lifecycle.
BPO Productivity Tool - This is is primarily built as a custom LightSwitch Shell Extension in which I embed PRISM to manage all LightSwitch and non-LightSwitch views.
Birthright Campaign Manager - Birthright Campaign Manager is an open source role playing computer aid for Birthright, a campaign setting for Dungeons & Dragons.

There are a lot of really interesting real-world LightSwitch production applications that were submitted. Some departmental apps, a few personal apps, some enterprise apps as well as a couple start-up companies. There are also some great case studies here for Azure, in particular:

Developer Center Updates

Learn Page Updates

In December I kicked off a series aimed at beginner developers just getting started with LightSwitch and was featured in the MSDN Flash Newsletter. In January we updated the Learn page of the Developer Center to feature this series and it’s been getting some great traffic!

I also released the completed source code for the sample we build in the series: Beginning LightSwitch - Address Book Sample

How Do I Videos – Learning Made Easier

We also updated all the How Do I video pages to show the sequential list of videos so that you can easily get to the previous and next videos in the series. This makes it a lot easier to navigate through the over 20 videos in the correct order. Just click into any video page like this one and you will see the video navigator at the bottom of the page.

Notable Content this Month

Here’s some more of the fun things the team and community released in January.

Extensions released in January (see all 73 of them here!):

The team also released a control extension sample that you can learn from. Check out the announcement on the team blog: Many-to-Many Control Released!

Build your own extensions by visiting the LightSwitch Extensibility page on the LightSwitch Developer Center.

Team Articles:

Community Articles:

Presentations:

Samples (see all of them here):

LightSwitch Team Community Sites

The Visual Studio LightSwitch Facebook Page has been increasing in activity thanks to you all. Become a fan! Have fun and interact with us on our wall. Check out the cool stories and resources.

Also here are some other places you can find the LightSwitch team:

LightSwitch MSDN Forums
LightSwitch Developer Center
LightSwitch Team Blog
LightSwitch on Twitter (@VSLightSwitch, #VisualStudio #LightSwitch)

Join Us!

The community has been using the hash tag #LightSwitch on twitter when posting stuff so it’s easier for me to catch it (although this is a common English word so you may end up with a few weird ones ;-)). Join the conversation! And if I missed anything please add a comment to the bottom of this post and let us know!

Enjoy!

Calling Web Services to Validate Data in Visual Studio LightSwitch

2012-01-30T14:15:00Z

Very often in business applications we need to validate data through another service. I’m not talking about validating the format of data entered – this is very simple to do in LightSwitch -- I’m talking about validating the meaning of the data. For instance, you may need to validate not just the format of an email address (which LightSwitch handles automatically for you) but you also want to verify that the email address is real. Another common example is physical Address validation in order to make sure that a postal address is real before you send packages to it.

In this post I’m going to show you how you can call web services when validating LightSwitch data. I’m going to use the Address Book sample and implement an Address validator that calls a service to verify the data.

Where Do We Call the Service?

In Visual Studio LightSwitch there are a few places where you can place code to validate entities. There are Property_Validate methods and there are Entity_Validate methods. Property_Validate methods run first on the client and then on the server and are good for checking the format of data entered, doing any comparisons to other properties, or manipulating the data based on conditions stored in the entity itself or its related entities. Usually you want to put your validation code here so that users get immediate feedback of any errors before the data is submitted to the server. These methods are contained on the entity classes themselves. (For more detailed information on the LightSwitch Validation Framework see: Overview of Data Validation in LightSwitch Applications)

The Entity_Validate methods only run on the server and are contained in the ApplicationDataService class. This is the perfect place to call an external validation service because it avoids having clients calling external services directly -- instead the LightSwitch middle-tier makes the call. This gives you finer control over your network traffic. Client applications may only be allowed to connect to your intranet internally but you can allow external traffic to the server managing the external connection in one place.

Calling Web Services

There are a lot of services out there for validating all sorts of data and each service has a different set of requirements. Typically I prefer REST-ful services so that you can make a simple http request (GET) and get some data back. However, you can also add service references like ASMX and WCF services as well. It’s all going to depend on the service you use so you’ll need to refer to their specific documentation.

To add a service reference to a LightSwitch application, first flip to File View in the Solution Explorer, right-click on the Server project and then select Add Service Reference…

Enter the service URL and the service proxy classes will be generated for you. You can then call these from server code you write on the ApplicationDataService just like you would in any other application that has a service reference. In the case of calling REST-ful services that return XML feeds, you can simply construct the URL to call and examine the results. Let’s see how to do that.

Address Book Example

In this sample we have an Address table where we want to validate the physical address when the data is saved. There are a few address validator services out there to choose from that I could find, but for this example I chose to sign up for a free trial of an address validation service from ServiceObjects. They’ve got some nice, simple APIs and support REST web requests. Once you sign up they give you a License Key that you need to pass into the service.

A sample request looks like this:

http://trial.serviceobjects.com/av/AddressValidate.asmx/ValidateAddress?Address=One+Microsoft+Way&Address2=&City=Redmond&State=WA&PostalCode=98052&LicenseKey=12345

Which gives you back the result:

<?xml version="1.0" encoding="UTF-8"?>
<Address xmlns="http://www.serviceobjects.com/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Address>1 Microsoft Way</Address>
    <City>Redmond</City>
    <State>WA</State>
    <Zip>98052-8300</Zip>
    <Address2/>
    <BarcodeDigits>980528300997</BarcodeDigits>
    <CarrierRoute>C012</CarrierRoute>
    <CongressCode>08</CongressCode>
    <CountyCode>033</CountyCode>
    <CountyName>King</CountyName>
    <Fragment/>
  </Address>

If you enter a bogus address or forget to specify the City+State or PostalCode then you will get an error result:

<?xml version="1.0" encoding="UTF-8"?>
<Address xmlns="http://www.serviceobjects.com/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Error>
    <Desc>Please input either zip code or both city and state.</Desc>
    <Number>2</Number>
    <Location/>
  </Error>
</Address>

So in order to interact with this service we’ll first need to add some assembly references to the Server project. Right-click on the Server project (like shown above) and select “Add Reference” and import System.Web and System.Xml.Linq.

Next, flip back to Logical View and open the Address entity in the Data Designer. Drop down the Write Code button to access the Addresses_Validate method. (You could also just open the Server\UserCode\ApplicationDataService code file if you are in File View).

First we need to import some namespaces as well as the default XML namespace that is returned in the response. (For more information on XML in Visual Basic please see: Overview of LINQ to XML in Visual Basic and articles here on my blog.) Then we can construct the URL based on the entity’s Address properties and query the result XML for either errors or the corrected address. If we find an error, we tell LightSwitch to display the validation result to the user on the screen.

Imports System.Xml.Linq
Imports System.Web.HttpUtility
Imports <xmlns="http://www.serviceobjects.com/">

Namespace LightSwitchApplication
  Public Class ApplicationDataService

    Private Sub Addresses_Validate(entity As Address, results As EntitySetValidationResultsBuilder)
      Dim isValid = False
      Dim errorDesc = ""

      'Construct the URL to call the web service
      Dim url = String.Format("http://trial.serviceobjects.com/av/AddressValidate.asmx/ValidateAddress?" &
                              "Address={0}&Address2={1}&City={2}&State={3}&PostalCode={4}&LicenseKey={5}",
                              UrlEncode(entity.Address1),
                              UrlEncode(entity.Address2),
                              UrlEncode(entity.City),
                              UrlEncode(entity.State),
                              UrlEncode(entity.ZIP),
                              "12345")

      Try
          'Call the service and load the XML result 
          Dim addressData = XElement.Load(url)

          'Check for errors first
          Dim err = addressData...<Error>
          If err.Any Then
              errorDesc = err.<Desc>.Value
          Else
              'Fill in corrected address values returned from service
              entity.Address1 = addressData.<Address>.Value
              entity.Address2 = addressData.<Address2>.Value
              entity.City = addressData.<City>.Value
              entity.State = addressData.<State>.Value
              entity.ZIP = addressData.<Zip>.Value
              isValid = True
          End If

      Catch ex As Exception
          Trace.TraceError(ex)
      End Try

      If Not (isValid) Then
          results.AddEntityError("This is not a valid US address. " & errorDesc)
      End If
    End Sub
  End Class
End Namespace

Run it!

Now that I’ve got this code implemented let’s enter some addresses on our contact screen. Here I’ve entered three addresses, the first two are legal and the last one is not. Also notice that I’ve only specified partial addresses.

If I try to save this screen, an error will be returned from the service on the last row. LightSwitch won’t let us save until the address is fixed.

If I delete the bogus address and save again, you will see that the other addresses were verified and all the fields are updated with complete address information.

Wrap Up

I hope this gives you a good idea on how to implement web service calls into the LightSwitch validation pipeline. Even though each service you use will have different requirements on how to call them and what they return, the LightSwitch validation pipeline gives you the necessary hooks to implement complex entity validation easily.

Enjoy!

Beginning LightSwitch–Address Book Sample

2012-01-26T20:48:13Z

Some folks have been asking for this so I just released the completed Address Book sample that you build step-by-step in the Beginning LightSwitch Article Series.

Download the Address Book Sample

Read the Series

Are you completely new to LightSwitch and software development? Read this entry-level article series to get started with the most important concepts you need to build any LightSwitch application.

More Information

Visit the LightSwitch Developer Center to download LightSwitch and get started learning.

Download Visual Studio LightSwitch

Watch the instructional LightSwitch "How Do I?" videos

Get essential training

Ask questions in the LightSwitch forums

Enjoy!

Using Different Edit Screens Based on Record Types (Table Inheritance)

2012-01-20T14:59:00Z

I had a reader ask a question this week on how to use Visual Studio LightSwitch to open different Edit Detail screens based on the “type” of record. This is a very common thing to do especially for data models that use table inheritance (or sub-tables). For instance say we are building an application for a pet store to manage their inventory of animals. We need to collect shared properties of all the animals in an Animal table but we also want to set up table inheritance to Fish, Cat and Dog tables which collect specific properties of those types of animals. When a user selects an animal on a search screen, we need to display a screen that lets them work with the correct data from the specific table. LightSwitch provides a “Show as Link” on labels which automatically opens up the default details screen for that entity, but in our case we could have multiple screens. There are also a few techniques you need to know when dealing with these types of relationships in LightSwitch, particularly around the insert pipeline. In this post I will show you how you can achieve this functionality.

Create The Data Model

First let’s start by creating a simple inheritance data model for the pet store. We will build an Animal table that collects general properties of any animal in the store. Then we will build Cat, Dog and Fish tables to collect specific properties of those types of animals. The relationship between the Animal table and the others will be a ‘one to zero or one’ relationship.

For this example, the Animal table has two required properties, Name and Type. Type is a Choice List with the static values “Cat”, “Dog”, “Fish” to correspond to the type of record the animal is. We will use this to drive what records are inserted into which specific table as well as use it to determine which screens to display.

Next, create the Cat, Dog and Fish tables to collect properties specific to these types of animals.

Finally, set up the relationships from Animal to these tables as a “one to zero or one” relationship with a delete behavior of “Cascade Delete”.

Our data model now looks like this.

Create the Screens

Next we’ll need to enter new animals into the system. Create a New Data Screen and select Animal as the screen data. When you do this, LightSwitch will include all the one-to-one related tables as fields on the screen. However, we only want to require the user to enter the general Animal properties on this screen. Once they save, we will direct them to the correct Cat, Dog or Fish detail screen. So first delete all the items in the content tree of the Screen Designer except for Name and Type.

Next, create an Edit Details Screen and select the Animal screen data again. Name the screen CatDetail and uncheck “Use as Default Details Screen”.

Again you will see that LightSwitch reads these special relationships and adds all the fields from all four tables to the screen. We will need to make some changes. First, change the “Type” from an Auto Complete box to a Label. Once the user has entered the type of animal on the New Data screen, it cannot be changed. Next, delete all the fields related to Dog and Fish from the screen.

Repeat the same process to create the DogDetail and FishDetail screens, removing the fields from the screen that do not belong.

Finally, add a Search Data Screen and select the Animal as the screen data again. Select the “Name” content item and in the properties window uncheck “Show as Link”.

Instead of using the built-in “Show as Link” functionality, we need to create our own command. We can put commands anywhere on the screen and we can show them as buttons or links. (For more information see: “I Command You!” - LightSwitch Screen Commands Tips & Tricks) For instance we could put an edit button on the screen command bar, the grid command bar, or even in the row itself. Let’s add a command into the row itself.

Right-click on the Data Grid Row Command Bar in the content tree and select “Add Button…”. Create a new method called “Edit”.

We want to show the command as a link instead of a button so select the button in the content tree and change it to a link.

Write the Code

Now we need to write some code to pull this all together. Right-click on the button we just created and select “Edit Execute Code” to open the code editor. Here we will check what type of animal we have to open the corresponding screen.

Private Sub Edit_Execute()
    If Me.Animals.SelectedItem IsNot Nothing Then
        Select Case Me.Animals.SelectedItem.Type
            Case "Cat"
                Me.Application.ShowCatDetail(Me.Animals.SelectedItem.Id)
            Case "Dog"
                Me.Application.ShowDogDetail(Me.Animals.SelectedItem.Id)
            Case "Fish"
                Me.Application.ShowFishDetail(Me.Animals.SelectedItem.Id)
        End Select
    End If
End Sub

Next we need to write similar code on the New Data screen so that it opens the correct detail screen after the user saves a new animal record. Open the CreateNewAnimal screen and in the upper right drop down the “Write Code” button and select the CreateNewAnimal_Saved method. First comment out the call to ShowDefaultScreen and then write code to determine which screen we need to show instead:

Private Sub CreateNewAnimal_Saved()
    Me.Close(False)
    'Application.Current.ShowDefaultScreen(Me.AnimalProperty)

    Select Case Me.AnimalProperty.Type
        Case "Cat"
            Me.Application.ShowCatDetail(Me.AnimalProperty.Id)
        Case "Dog"
            Me.Application.ShowDogDetail(Me.AnimalProperty.Id)
        Case "Fish"
            Me.Application.ShowFishDetail(Me.AnimalProperty.Id)
    End Select
End Sub

Finally, we need to implement a business rule on Animal in the save pipeline. This rule is important so that a new record is added to the correct table based on the animal’s type. That way after the user saves the CreateNewAnimal screen, a record will be written to the correct table and the detail screen will open and allow the user to edit the specific fields in the Cat, Dog or Fish table. Double-click on Animals in the Solution Explorer under the Data Sources/ApplicationData node to open the Data Designer. Drop down the Write Code button and select the Animals_Inserting method and write this code:

Private Sub Animals_Inserting(entity As Animal)
    Select Case entity.Type
        Case "Cat"
            If entity.Cat Is Nothing Then
                entity.Cat = New Cat()
            End If
        Case "Dog"
            If entity.Dog Is Nothing Then
                entity.Dog = New Dog()
            End If
        Case "Fish"
            If entity.Fish Is Nothing Then
                entity.Fish = New Fish()
            End If
    End Select
End Sub

Run it!

Enter new animals on the Create New Animal screen and when you click Save, the correct detail screen will open allowing you to enter more specific details based on the type of animal.

On our search screen, we can click the Edit link on any of the rows and it will open to the correct details screen as well.

Wrap Up

I hope this post answered the reader’s question on how to open different detail screens depending on the record’s type. All it takes is implementing your own command. I also touched on one to one relationships and how to set up basic table inheritance. I encourage you to experiment more with this type of relationship. They come in particularly handy when you need to extend external data sources with additional properties or when you need to set up inheritance hierarchies. The trick is to get a record inserted into the right table when you insert the master / parent record. I’ll expand on a couple other techniques in a future post.

Enjoy!

Creating Cascading Drop Down Lists in Visual Studio LightSwitch

2012-01-12T18:15:49Z

A common technique on data entry screens is using one “drop down list” (called an auto-complete box in LightSwitch) as a filter into the next. This limits the amount of choices that need to be brought down and guides the user into easily locating values. This technique is also useful if you have cascading filtered lists where the first selection filters data in the second, which filters data in the next, and so forth. LightSwitch makes this easy to do using parameterized queries and parameter binding. In this post let’s take a look a couple common scenarios.

Cascading Lists based on Multiple Tables

Let’s take an example where we have a table of States and a child table of Cities. Cities are then selected on Customers when entering them into the system. So we have one-to-many relationships between State and Cities and City and Customers. Our data model looks like this:

When the user is entering new customers we don’t want to display thousands of cities in the dropdown to choose from. Although the users can use the auto-complete box feature to locate a city, bringing down all these records affects performance. It’s better to either use a Modal Window Picker search dialog (like I showed in this article) or present the list of States first and then filter the list of Cities down based on that selection.

First we need to create a couple queries. The first will simply sort the list of States so that they show up in alphabetical order in the list. Right-click on the States table in the Solution Explorer and Add Query to open the Query Designer. Create a query called “SortedStates” that sorts on the state’s Name Ascending:

Next create a query called “CitiesByState” by right-clicking on the Cities table in the Solution Explorer and selecting Add Query again. This time we will create a parameterized query: Where the State.Id property is equal to a new parameter called Id. The Query Designer should now look like this:

Now create the Customer Detail Screen like normal. Right-click on the Screens node and select “Add Screen…”, select the Edit Details Screen template then choose Customers for the screen data. The Screen Designer opens and all the fields in the Customer entity will be in the content tree. The City field is displayed as an auto-complete box.

Next we’ll need to add a data item to our screen for tracking the selected State. We will use this value to determine the filter on the City list so that users only see cities in the selected state. Click “Add Data Item” and add a Local Property of type State called SelectedState.

Next, drag the SelectedState over onto the content tree above the City. LightSwitch will automatically create an auto-complete box control for you.

Since we want to display the states sorted, next add the SortedStates query to the screen. Click “Add Data Item” again, this time select Query and choose SortedStates.

Then select the SelectedState auto-complete box in the content tree and on the Properties window, set the Choices property to SortedStates.

Next, add the CitiesByState query to the screen and set that as the Choices property of the Cities auto-complete box. Again, click “Add Data Item” and choose the CitiesByState query.

Then select the Cities auto-complete box and set the Choices property to this query.

Lastly we need to hook up the parameter binding. Select the Id parameter of the CitiesByState query and in the properties window set the Parameter Binding to SelectedState.Id. Once you do this a grey arrow on the left side will indicate the binding.

Once you set the value of a query parameter, LightSwitch will automatically execute the query for you so you don’t need to write any code for this. Hit F5 and see what you get. Notice that the Cities drop down list is empty until you select a State at which point it feeds the CitiesByState query and executes it. Also notice that if you make a city selection and then change the state, the selection is still displayed correctly, it doesn’t disappear. Just keep in mind that anytime a user changes the state, the city query is re-executed against the server.

One additional thing that you might want to do is to initially display the state to which the city belongs. As it is, the Selected State comes up blank when the screen is opened. This is because it is bound to a screen property which is not backed by data. However we can easily set the initial value of the SelectedState in code. Back in the Screen Designer drop down the “Write Code” button at the top right and select the InitializeDataWorkspace method and write the following:

Private Sub CustomerDetail_InitializeDataWorkspace(saveChangesTo As List(Of Microsoft.LightSwitch.IDataService))
    ' Write your code here.
    If Me.Customer.City IsNot Nothing Then
        Me.SelectedState = Me.Customer.City.State
    End If
End Sub

Now when you run the screen again, the Selected State will be displayed.

Cascading Lists Based on a Single Table

Another option is to create cascading lists based on a single table. For instance say we do not want to have a State table at all. Instead it may make more sense to store the State on the City. So our data model could be simplified by having just a City table related to many Customers.

This time when we create a parameterized query called CitesByState, we’ll set it up Where the State is equal to a new parameter called State.

On the screen, select “Add Data Item” to add the CitiesByState to the screen and set it as the Choices property of the City auto-complete box just like before.

This time, however, the State is the query parameter we need to bind. Add a string screen property to the screen to hold the selected state. Click “Add Data Item” again, add a required Local Property of type String and name it SelectedState.

Drag the SelectedState onto the content tree above the City. This time LightSwitch will create a textbox for us since this is just a local string property.

Finally, we need to set up the query parameter binding. Select the State query parameter and in the properties window set the Parameter Binding to SelectedState.

In order to set the SelectedState when the screen opens, the same code as before will work. Now when we run this, you will see a textbox that will filter the list of cities.

However, this may not be exactly what we want. If the user has a free-form text field then they could mistype a state code and the query would return no results. It would be better to present the states in a auto-complete box like before. Close the application and open the Screen Designer again. Select the SelectedState screen property. Notice in the properties window you can display this as a static list of values by creating a Choice List.

Enter the states that the user should select from and then run the application again. Now we get an auto-complete box like before. However, this approach leaves us having to define the choice list of states on every screen we want this functionality. The first approach using a State table solves this issue but there is also one other approach we could take to avoid having to create a separate table.

Using a Choice List on the Entity

We could improve this situation by defining the choice list of states on the Customer entity. Then we would only have to define the lists of states in one place. Create a State property on the Customer using the Data Designer and on the properties window select Choice List and specify the list of states there.

Now add a new detail screen for Customer and you will see the State and City properties are set up as auto-complete boxes. Next add the CitiesByState query to the screen by clicking “Add Data Item” like before. We can use the same CitiesByState query as the previous example. Select the City auto-complete box and in the properties window set the Choices property to CitiesByState like before.

The difference is the query parameter binding. Select the State query parameter on the left and in the properties window set the Parameter Binding to Customer.State.

With this technique, you also do not need to write any code to set the initial selected State because we are now storing that value on the Customer record. Run the application again and the screen should behave the same. The only difference now is that we are storing the State on the Customer instead of a separate table.

This technique is the simplest to set up, so if you have a lot of Customer screens, then this may be the best choice for you if you have a static list of values like States. However if you have dynamic list of values then it’s better to store these in a separate table like the first technique showed.

For more information on filtering data and configuring lists see:

Enjoy!

LightSwitch Community & Content Rollup– December 2011

2012-01-05T14:55:00Z

Happy New Year everyone! I hope you all had a wonderful holiday and enjoyed some well-deserved time off. I sure did! Now that I’m back in the office I’m a few days overdue for this post so here ya go! A few months ago I started posting a rollup of interesting community happenings, content, samples and extensions popping up around Visual Studio LightSwitch. If you missed those rollups you can check them out here:

Usually December is a pretty slow month all around, but there were still a lot of awesome things around LightSwitch, especially the number of community articles this month! Check them out…

“LightSwitch Star” Contest

Do you have what it takes to be a LightSwitch Star? Show us your coolest, most productive, LightSwitch business application and you could win a Laptop and other great prizes!

In November The Code Project launched the “LightSwitch Star” contest. You just answer some questions and email them a screenshot or two. They’re looking for apps that show off the most productivity in a business as well as apps that use extensions in a unique, innovative way. Prizes are given away each month (see here for more details on prizes). In early December they announced the November winners and today they announced the December winners in each category:

Most Efficient Business Application	Most Ground-breaking Business Application
November	November
1st prize: Security Central 2nd prize: PTA LightSwitch	1st prize: Church+ 2nd prize: Engineering App
December	December
1st prize: Patient Tracker 2nd prize: Instant Assets	1st prize: Health and Safety Management System 2nd prize: Orion

Congrats to all! Can’t wait to see what people submit in January. There were some really cool applications submitted in December. Here’s a breakdown of what was submitted last month (see all 23 apps that have been submitted so far here). Make sure to vote for your favorite ones, grand prize is a laptop!

7 More Production Apps…

Instant Assets - The one stop shop for all your asset, equipment and facilities management needs
Patient Tracker - used to interface to a SharePoint list (used as the dataset) to provide timestamp and delay code inputs to the SharePoint list.
PeopleTrac – People Management for Not-For-Profit Organizations - Demonstrates several LightSwitch capabilities including WCF-RIA services, Native SQL, Name and Addres merge purge
The Health and Safety Management System - The Health and Safety Management System is an application that is used to help organizations better manage and mitigate health and safety statistics and KPIs.
Orion - A mini-CRM that helps with POS records, service request, field technicians workload, inventory, inventory tracking, fuel management and reports.
Search SSRS Subscriptions – Manages subscriptions to SQL Server Reporting Services
WindowsDevNews.com: A Visual Studio LightSwitch Application – WindowsDevNews.com site uses Visual Studio LightSwitch for it's back-end

3 More Tutorials/Samples/Videos…

ComponentOne Scheduler for LightSwitch Released

ComponentOne released another LightSwitch extension last month in addition to the OLAP Control. This ready-to-use LightSwitch screen gives you a complete Outlook-style scheduling application! Check it out:

Notable Content this Month

Here’s some more of the fun things the team and community released in December.

Extensions released in December (see all 71 of them here!):

Build your own extensions by visiting the LightSwitch Extensibility page on the LightSwitch Developer Center.

Team Articles:

In December I kicked off a series aimed at beginner developers just getting started with LightSwitch and was featured in the MSDN Flash Newsletter. This brought A LOT of traffic to my blog – in fact, it is at an all-time high since the month of December! WOW! This series is popular!

Matt Thalman also wrote the following article that address a top request in the LightSwitch Forums:
Creating a Custom Login Page for a LightSwitch Application

Community Articles:

Samples (see all of them here):

LightSwitch Team Community Sites

The Visual Studio LightSwitch Facebook Page has been increasing in activity thanks to you all. Become a fan! Have fun and interact with us on our wall. Check out the cool stories and resources.

Also here are some other places you can find the LightSwitch team:

LightSwitch MSDN Forums
LightSwitch Developer Center
LightSwitch Team Blog
LightSwitch on Twitter (@VSLightSwitch, #VisualStudio #LightSwitch)

Join Us!

Enjoy!

Beginning LightSwitch Part 6: I Feel Pretty! Customizing the "Look and Feel" with Themes

2011-12-21T22:23:42Z

Welcome to Part 6 of the Beginning LightSwitch series! In parts 1 thru 5 we built an Address Book application and learned all about the major building blocks of a Visual Studio LightSwitch application -- entities, relationships, screens, queries and user permissions. If you missed them:

In this post I want to talk about themes. Themes allow you to change the colors, fonts and styles of all the visual elements in the user interface. Now that our Address Book application is complete, we’re almost ready to get this in front of real users. But before we do, it would be really nice to apply a different look-and-feel to our application in order to make it stand out above the rest. Visual Studio LightSwitch comes with only one theme out of the box, but you can download more. In fact, there are all kinds of extensions you can download to enhance what LightSwitch can do out of the box, not just themes.

Visual Studio LightSwitch Extensibility

LightSwitch provides an entire extensibility framework so that professional developers can write extensions to enhance the LightSwitch development experience. Many third-party component vendors as well as the general community have released all sorts of extensions for LightSwitch. These include custom controls, business types, productivity libraries and designers, and of course themes. Check out some of the featured extensions from our partners. If you are a code-savvy, professional .NET developer with Visual Studio Professional or higher, then you can create your own extensions. For more information on creating extensions see the Extensibility section of the LightSwitch Developer Center.

Downloading and Enabling Extensions

Luckily, you don’t need to be a hardcore programmer to use extensions. They are easy to find and install. Just open the Extension Manager from the Tools menu.

The Extension Manager will come up and display all your installed extensions. Select the “Online Gallery” tab to choose from all the LightSwitch extensions from the Visual Studio Gallery. (Note: if you have Visual Studio Professional or higher and not just the LightSwitch edition installed, then you will need to filter the Extension Manager on “LightSwitch” to see those extensions.)

You can also download these extensions directly from the Visual Studio Gallery. Select the extension you want and click the download button to install.

For our Address Book application I’m going to apply the LightSwitch Metro Theme which is one of the most popular extensions (at the time of this writing) so it’s right at the top. Once you install the extension, you’ll need to restart Visual Studio LightSwitch. After extensions are installed, you need to enable them on a per-project basis. Open the project properties by right-clicking on the project in the Solution Explorer and select “Properties”. Then select the “Extensions” tab to enable the extension.

For our Address Book application, enable the Metro Theme extension. Also notice that there is the “Microsoft LightSwitch Extensions” also in this list which is always enabled and used in new projects. This is an extension that is included with the LightSwitch install and contains the business types Email Address, Phone Number, Money and Image that you can use when defining your data entities like we did in Part 1. You should never have to disable these.

Applying a Theme

Now that the theme extension is installed and enabled, you can apply the theme by selecting the “General Properties” tab and then choosing the LightSwitch Metro Theme.

Then just build and run (F5) the application to see how it looks!

For more information on the Metro Theme extension (and source code) see the LightSwitch Metro Theme Extension Sample.

Some More Cool LightSwitch Themes

Besides the Metro Theme, there are a lot of other nice looking themes available, some for free and some for a small fee. If you open the Extension Manager to the Online Gallery tab and enter the search term “theme” you will see a long list of them. Here are the top 5 most popular on the gallery (at the time of this writing):

Also check out Paul Patterson’s “Uber Theme Resource” which provides more screenshots and reviews of all the themes on the gallery!

Wrap Up

As you can see it’s easy to download and enable themes in Visual Studio LightSwitch in order to change the look-and-feel of your business applications. LightSwitch provides an entire extensibility model that not only allows the community to create themes, but all kinds of extensions that enhance the LightSwitch development experience that you can take advantage of. If you’re a code-savvy developer that wants to create your own themes, head to the Extensibility section of the LightSwitch Developer Center to get set up and then read this walkthrough Creating a Theme Extension.

Well that wraps up what I planned for the Beginning LightSwitch Series! I hope you enjoyed it and I hope it has helped you get started building your own applications with Visual Studio LightSwitch. For more LightSwitch training please see the Learn section of the LightSwitch Developer Center. In particular, I recommend going through my “How Do I” videos next.

Now I’m going to go enjoy some well-earned Christmas vacation. I’ll be back in a couple weeks. Happy Holidays LightSwitch-ers! Enjoy!

Beginning LightSwitch Part 5: May I? Controlling Access with User Permissions

2011-12-20T21:11:00Z

Welcome to Part 5 of the Beginning LightSwitch series! In parts 1 thru 4 we learned about entities, relationships, screens and queries in Visual Studio LightSwitch. If you missed them:

In this post I want to talk about user permissions, also known as Access Control. In most business applications we need to limit what resources users can access in the system, usually because of different job function or role. For instance, only system administrators can add new users to the system. Certain data and screens in the application may be sensitive and should be restricted unless that user has rights to that part of the system. LightSwitch makes it easy to define user permissions and provides hooks on entities, screens and queries that allow you to check these permissions.

For a video demonstration on how to set up user permissions see: How Do I: Set Up Security to Control User Access to Parts of a Visual Studio LightSwitch Application?

Authentication & Authorization

There are two pieces of information LightSwitch applications need in order to determine which users have rights to what parts of the system. First, the system needs to verify the user accessing the application. This is called Authentication. In other words: “Prove you are who you say you are.” There are two supported types of authentication in LightSwitch; Windows and Forms.

Windows authentication means that the application trusts the user based on their Windows credentials. So once a user successfully logs into their Windows desktop, those credentials are automatically passed to the LightSwitch application. Forms authentication means that the application requests a username & password of its own, completely independent of any other credentials. So when you choose to use Forms authentication a login screen is presented to the user and they must type their username and password every time they want to access the application.

Once a user is authenticated, the application can determine access to parts of the system by reading their user permissions. This is called Authorization. In other words: “Now that I know who you are, here’s what you can do in the system.”

Setting Up User Permissions

It all starts on the Access Control tab of the Project Properties. To open it, right-click on the name of your project in the Solution Explorer and select “Properties” from the menu.

Then select the Access Control tab to specify the type of authentication you want to employ as well as what user permissions you want to define.

By default, the application doesn’t have authentication enabled so here is where you select the type of authentication you want to use.

Using Forms authentication means you will be storing usernames and encrypted passwords inside the LightSwitch database. This type of authentication is appropriate for internet-based applications where users are not on the same network and you need to support other operating systems besides Windows.

Using Windows authentication is appropriate if all your users are on the same network/domain or workgroup, like in the case of an internal line-of-business application. This means that no passwords are stored by your LightSwitch application. Instead the Windows logon credentials are used and passed automatically to the application. This is a more secure and convenient option if you can use it. In this case you can also choose whether you want to set up specific users and roles or whether any authenticated user has access to the application.

The best way to think of the two options for Windows authentication are:

Give special permissions and roles to the Windows users that I administer within the application. (This is always on if you have selected Windows authentication)
ALSO, let any Windows user access the unprotected parts of my application

Next you define user permissions that you check in code in order to access resources (we’ll work through an example next). There is always a SecurityAdministration permission defined for you that is used by LightSwitch once you deploy the application. When you deploy, LightSwitch will create a single user with this permission which gives them access to the screens necessary to define the rest of the users and roles in the system. However, while debugging your application, LightSwitch doesn’t make you log in because this would be tedious to do every time you built and ran (F5) the application. So instead you can use the “Granted for debug” checkbox to indicate which sets of permissions should be turned on/off in the debug session.

Let’s walk through a concrete example by implementing some security in our Address Book (Contact Manager) application we’ve been building in this series.

Checking User Permissions in the Address Book Application

Let’s start by selecting an authentication scheme. Since this application will be used by a small business to manage all their contacts, I’ll choose Windows authentication. I’ll also select “Allow any authenticated Windows user” into the system so that everyone in the company can search for and edit contacts by default. However, in order to add or delete contacts, users will need special permissions to do that.

So we need to create two new permissions. You can name the permissions whatever you want. You only see the name in code. When the system administrator sets up users and roles later, they will see the Display Name on the screen so be descriptive there. So add two permissions; CanAddContacts and CanDeleteContacts.

Next, leave the “Granted for debug” unchecked for both of those permissions so that we can test that they are working. When you leave this unchecked, the permission will not be granted. This allows us to easily test combinations of permissions while debugging. In order to see the Users and Roles screens while debugging you can enable it for SecurityAdministration. Now that we have these permissions set up here, we need to check them in code. As I mentioned, LightSwitch provides method hooks for you so you can write code when you need for all sorts of custom validation and business rules, including access control.

For more information on writing code in LightSwitch see the Working with Code topic on the LightSwitch Developer Center.

For more information on writing custom business rules see: Common Validation Rules in LightSwitch Business Applications

So in order to implement the security, we need to write a couple lines of code to check these permissions. LightSwitch provides access control methods on entities, screens and queries. To access these methods, drop down the “Write code” button on the top right of any designer and you will see an “Access Control Methods” section in the list. When you want to restrict viewing (reading), inserting (adding), editing or deleting entities, open the entity in the Data Designer and drop down the “Write code” button and select the appropriate access control method.

For this application, select the Contacts_CanDelete method and this will open the code editor to that method stub. All you need to do is write one line of code (in bold below) to check the CanDeleteContacts permission you set up:

Namespace LightSwitchApplication

    Public Class ApplicationDataService

        Private Sub Contacts_CanDelete(ByRef result As Boolean)
            'Add this one line of code to verify the user has permission to delete contacts:
            result = Me.Application.User.HasPermission(Permissions.CanDeleteContacts)

        End Sub
    End Class

End Namespace

Note: This code is Visual Basic. If you chose C# as your programming language when you created the ContactManager project in Part 1, you will need to write the code like this: result = this.Application.User.HasPermission(Permissions.CanDeleteContacts);

Now go back to the “Write Code” button on the designer and select Contacts_CanInsert and then similarly write the following line of code (in bold) to check the CanAddContacts permission:

Namespace LightSwitchApplication

    Public Class ApplicationDataService

        Private Sub Contacts_CanDelete(ByRef result As Boolean)
            'Add this one line of code to verify the user has permission to delete contacts:
            result = Me.Application.User.HasPermission(Permissions.CanDeleteContacts)

        End Sub

        Private Sub Contacts_CanInsert(ByRef result As Boolean)
            'Add this one line of code to verify the user has permission to add contacts:
            result = Me.Application.User.HasPermission(Permissions.CanAddContacts)
        End Sub
    End Class

End Namespace

You may be wondering why we are checking these permissions in the entity instead of the screens. Checking permissions in the entity guarantees that no matter what screen the user is working with, the data actions are protected. It’s best practice remember to secure your entities first if you need to implement user permissions in your application. However, our application also has a “Create New Contact” screen and we don’t want to show this to the user on the menu if they do not have permission to add contacts to the system. If we forget to hide this screen from the menu, then the user would be able to open it and fill it out with data. However, when they click Save the Contacts_CanInsert method above will run and prevent the actual data from saving.

So in order to hide this screen from the navigation menu, we need to add one more check. Double-click the CreateNewContact screen in the Solution Explorer to open the Screen Designer. Drop down the “Write Code” button on the top right and you will see the one Access Control method available to you for screens:

Select the CreateNewContact_CanRun method and then write the following line of code (in bold):

Namespace LightSwitchApplication

    Public Class Application

        Private Sub CreateNewContact_CanRun(ByRef result As Boolean)
            'Add this one line of code to verify the user has permission to run the screen:
            result = Me.User.HasPermission(Permissions.CanAddContacts)

        End Sub
    End Class

End Namespace

Run it!

Now we are ready to test the application so build and run by hitting F5. Because we didn’t grant the CanAddContacts and CanDeleteContacts permissions for debug you will notice first that the CreateNewContact screen is not showing up on the menu. The first screen that displays is the custom search screen we created in Part 4. If you click on a contact then the details screen will open which allows the user to edit that contact’s information. In order to see if we are restricted from deleting or adding new contacts let’s make a small change to the search screen. While the search screen is open click the “Design Screen” button at the top right to open the screen customization mode.

In the content tree on the left, expand the command bar under the Data Grid and add two commands; DeleteSelected and AddAndEditNew.

Click Save (ctrl+shift+S) to save and exit customization mode and notice that the commands are disabled. Since we do not have permission to add or delete contacts this behavior is correct. Also since we are checking these permissions at the entity level all screen commands behave appropriately with no additional code necessary.

If you go back to your project properties Access Control tab you can check off combinations of permissions you want to test and you will see all commands enable/disable appropriately.

Users & Roles Screens

Before we wrap up I want to quickly walk through the Users and Roles screens. When you enable the SecurityAdministration permission for debugging, these screens are available on the menu. However, keep in mind that the data you put into these screens isn’t used at debug time. It isn’t later until you deploy the application when these screens are used. So putting data into these screens is for demonstration purposes only. When your application is deployed the first time, LightSwitch will ask you for an administrator username & password that it deploys into the users table and grants the SecurityAdministration permission. That administrator can then enter the rest of the users into the system.

First you define roles and add the permissions you defined to that role using the Roles Screen.

Then you can add new users using the Users Screen and assign them the appropriate Roles.

Wrap Up

As you can see defining and checking user permissions in Visual Studio LightSwitch is a simple but important task. Access control is a very common requirement in professional business applications and LightSwitch provides an easy to use framework for locking down all parts of the application through method hooks on entities, screens and queries. Once you deploy your application, the system administrator can start setting up users and roles to control access to the secure parts of your application.

For more information on user permissions and deploying applications see Working with User Permissions and Deploying LightSwitch Applications topics on the LightSwitch Developer Center.

In the next post we’ll look at themes and how to change the look and feel of your application by installing LightSwitch extensions. We’ll look at what’s available for free as well as some inexpensive ones that really look great. Until next time!

Enjoy!

Go to next article –> I Feel Pretty! Customizing the "Look and Feel" with Themes

Beginning LightSwitch Part 4: Too much information! Sorting and Filtering Data with Queries

2011-12-15T20:42:00Z

Welcome to Part 4 of the Beginning LightSwitch series! In part 1, 2 and 3 we learned about entities, relationships and screens in Visual Studio LightSwitch. If you missed them:

In this post I want to talk about queries. In real life a query is just a question. But when we talk about queries in the context of databases, we are referring to a query language used to request particular subsets of data from our database. You use queries to help users find the information they are looking for and focus them on the data needed for the task at hand. As your data grows, queries become extremely necessary to keep your application productive for users. Instead of searching an entire table one page at a time for the information you want, you use queries to narrow down the results to a manageable list. For example, if you want to know how many contacts live in California, you create a query that looks at the list of Contacts and checks the State in their Address.

If you’ve been following this article series, you actually already know how to execute queries in LightSwitch. In part 3 we built a Search Data Screen. This screen has a built-in search feature that allows users to type in search terms and return rows where any string field matches that term. In this post I want to show you how you can define your own queries using the Query Designer and how you can use them on screens.

The LightSwitch Query Designer

The Query Designer helps you construct queries sent to the backend data source in order to retrieve the entities you want. You use the designer to create filter conditions and specify sorting options. A query in LightSwitch is based on an entity in your data model (for example, a Contact entity). A query can also be based on other queries so they can be built-up easily. For instance, if you define a query called SortedContacts that sorts Contacts by their LastName property, you can then use this query as the source of other queries that return Contacts. This avoids having to repeat filter and/or sort conditions that you may want to apply on every query.

For a tour of the Query Designer, see Queries: Retrieving Information from a Data Source

For a video demonstration on how to use the Query Designer, see: How Do I: Sort and Filter Data on a Screen in a LightSwitch Application?

Creating a “SortedContacts” Query

Let’s walk through some concrete examples of creating queries in LightSwitch using the Contact Manager Address Book application we’ve been building. In part 3 we built a Search Data Screen for our Contacts, but if you notice the Contacts are not sorted when the screen is initially displayed. The user must click on the desired grid column to apply a sort manually. Once the user changes the sort order LightSwitch will remember that on a per-user basis, but we should really be sorting the Contacts for them when the Search screen is displayed the first time.

To create a query, in the Solution Explorer right-click on the entity you want to base it on (in our case Contacts) and choose “Add Query”.

The Query Designer will open and the first thing you do is name your query. We’ll name ours “SortedContacts”. Once you do this, you will see the query listed under the entity in the Solution Explorer.

Next we need to define the sort order so click “+Add Sort” in the Sort section of the designer then select the LastName property from the drop down. Click “+Add Sort” again and this time select the FirstName property. Leave the order Ascending for both.

Before we jump into Filter conditions and Parameters, let’s see how we can use this simple query on our Search Screen. It’s actually easier in this case to re-create the Search Screen we created in Part 3 because we didn’t make any modifications to the layout. So in the Solution Explorer select the SearchContacts screen and delete it. Then right-click on the Screens node and select “Add Screen…” to open the Add New Screen dialog.

Select the Search Data Screen template then for the Screen Data you will see the SortedCOntacts query. Choose that then click OK.

Hit F5 to build and run the application and notice this time the contacts are sorted in alphabetical order immediately.

Defining Filter Conditions and Parameters

Our Search Screen is in better shape now but what if we wanted to allow the user to find contacts who’s birth date falls within a specific range? Out of the box, LightSwitch will automatically search across all String properties on an entity but not Dates. Therefore, in order to allow the user the ability to search within a birth date range, we need to define our own query.

So let’s create a query that filters by date range but this time we will specify the Source of the query be the SortedContacts query. Right-click on the Contacts entity and choose “Add Query” to open the Query Designer again. Name the query “ContactsByBirthDate” and then select “SortedContacts” in the Source drop down on the top right of the designer.

Now the query is sorted but we need to add a filter condition. Defining filter conditions can take some practice (like designing a good data model) but LightSwitch tries to make it as easy as possible while still remaining powerful. You can specify fairly complex conditions and groupings in your filter, however the one we need to define isn’t too complex. When you need to find records within a range of values you will need 2 conditions. Once that checks records fall “above” the minimum value and one that checks records fall “below” the maximum value.

So in the Query Designer, click “+ Add Filter” and specify the condition like so:

Where

the BirthDate property

is greater than or equal to

a parameter.

Then select “Add New” to add a new parameter.

The parameter’s name will default to “BirthDate” so change it to MinimumBirthDate down in the Parameters section.

Similarly, add the filter condition for “Where the BirthDate property is less than or equal to a new parameter called MaximumBirthDate”. The Query Designer should now look like this:

One last thing we want to think about with respect to parameters is whether they should be required or not. Meaning must the user fill out the filter criteria parameters in order to execute the query? In this case, I don’t want to force the user to enter either one so we want to make them optional. You do that by selecting the parameter and checking “Is Optional” in the properties window.

Okay now let’s use this query for our Search Screen. In the Solution Explorer select the SearchSortedContacts screen and delete it. Then right-click on the Screens node and select “Add Screen…” to open the Add New Screen dialog again. Select the Search Data Screen template and for the Screen Data select the ContactsByBirthDate query and click OK.

Hit F5 to build and run the application. Notice the contacts are still sorted in alphabetical order on our search screen but you see additional fields at the top of the screen that let us specify the birth date range. LightSwitch sees that our query specified parameters so when we used it as the basis of the screen, the correct controls were automatically generated for us! And since both of these parameters are optional, users can enter none, one, or both dates and the query will automatically execute correctly based on that criteria.

As you can see using queries with parameters like this allows you to perform much more specialized searches than what is provided by default. When using queries as the basis of Screen Data, LightSwitch will automatically look at the query’s parameters and create the corresponding screen parameters and controls which saves you time.

For more information on creating custom search screens, see: Creating a Custom Search Screen in Visual Studio LightSwitch and How to Create a Screen with Multiple Search Parameters in LightSwitch

For a video demonstration, see: How Do I: Create Custom Search Screens in LightSwitch?

Querying Related Entities

Before we wrap this up I want to touch on one more type of query. What if we wanted to allow the user to search Contacts by phone number? If you recall our data is modeled so that Contacts can have many Phone Numbers so they are stored in a separate related table. In order to query these, we need to base the query on the PhoneNumber entity, not Contact.

So right-click on the PhoneNumbers entity in the Solution Explorer and select “Add Query”. I’ll name it ContactsByPhone. Besides searching on the PhoneNumber I also want to allow users to search on the Contact’s LastName and FirstName. This is easy to do because the Query Designer will allow you to create conditions that filter on related parent tables, in this case the Contact. When you select the property, you can expand the Contact node and get at all the properties.

So in the Query Designer, click “+ Add Filter” and specify the condition like so:

Where the Contact’s LastName property

contains

a parameter

Then select “Add New” to add a new parameter.

The parameter’s name will default to “LastName” so change it to SearchTerm down in the Parameters section and make it optional by checking “Is Optional” in the properties window.

We’re going to use the same parameter for the rest of our conditions. This will allow the user to type their search criteria in one textbox and the query will search across all three fields for a match. So the next filter condition will be:

Or the Contact’s FirstName property contains the parameter of SearchTerm

And finally add the last filter condition:

Or the Phone property contains the parameter of SearchTerm. I’ll also add a Sort on the PhoneNumber Ascending. The Query Designer should now look like this:

Now it’s time to create a Search Screen for this query. Instead of deleting the other Search screen that filters by birth date range, I’m going to create another new search screen for this query. Another option would be to add the previous date range condition to this query, which would create a more complex query but would allow us to have one search screen that does it all. For this example let’s keep it simple, but here’s a hint on how you would construct the query by using a group:

For more information on writing complex queries see: Queries: Retrieving Information from a Data Source and How to Create Composed and Scalar Queries

So to add the new Search Screen right-click on the Screens node again and select “Add Screen…” to open the Add New Screen dialog. Select the Search Data Screen template and for the Screen Data select the ContactsByPhone query this time and click OK.

Now before we run this I want to make a small change to the screen. The default behavior of a search screen is to make the first column a link that opens the Details screen for that record. Since we had to base our query on the PhoneNumber entity, LightSwitch will make the Phone property a link and not the Contact. So in the Screen Designer we need to make a small change. Select the Phone in the content tree and in the properties window uncheck “Show as Link”. Then select the Contact and check “Show as Link”.

Also change Display Name in the properties window for the PhoneNumberSearchTerm textbox to “Phone Number or Name” to make it more clear to the user what they are filtering on. And while we’re at it, we should disable the default search box by selecting the ContactsByPhone query on the left-hand side and unchecking “Supports search” in the properties window. This isn’t necessary since we are providing more search functionality with our own query.

Okay hit F5 and let’s see what we get. Open the “Search Contact By Phone” Search screen from the navigation menu and now users can search for contacts by name or by phone number. When you click on the Contact link, the Details screen we created in part 3 will open automatically.

Wrap Up

As you can see queries help narrow down the amount of data to just the information users need to get the task done. LightSwitch provides a simple, easy-to-use Query Designer that lets you base queries on entities as well as other queries. And the LightSwitch Screen Designer does all the heavy lifting for you when you base a screen on a query that uses parameters.

Writing good queries takes practice so I encourage you to work through the resources provided in the Working with Queries topic on the LightSwitch Developer Center.

In the next post we’ll look at user permissions and you will see how to write your first lines of LightSwitch code! Until next time!

Enjoy!

Go to next article –> Part 5: May I? Controlling Access with User Permissions

Beginning LightSwitch Part 3: Screen Templates, Which One Do I Choose?

2011-12-14T15:12:00Z

Welcome to Part 3 of the Beginning LightSwitch series! In part 1 and part 2 we learned about entities and relationships in LightSwitch and how to use the Data Designer to define them. If you missed them:

In this post I want to talk about screens. Screens are a common term in everyday life usually denoting a television or computer screen – the shiny thing we look at to interact with the device. In LightSwitch screens present data to the user and form the majority of the application’s user interface (UI). The default LightSwitch application shell presents screens in the center of the application window in a tabbed display. At the top is a ribbon of commands Save and Refresh, and on the left is the navigation menu.

Screens also allow users to search for, edit, insert and delete data in the backend data sources. LightSwitch makes the creation of screens really simple by providing templates you can choose from. You can then use them as is, or customize them further for your needs. Once you have some entities defined (like you learned in the previous posts) then you are ready to create screens.

Choosing a Screen Template

You can add a screen to your project by clicking the “+ Screens…” button at the top of the Data Designer or by right-clicking on the Screens folder in the Solution Explorer and selecting “Add Screen…”

When you do this the “Add New Screen” dialog appears which asks you to select a screen template as well as the data you want to display on the screen. There are five screen templates in Visual Studio LightSwitch; the Details Screen, Editable Grid Screen, List and Details Screen, New Data Screen, and Search Data Screen. Depending on the screen template you choose, your options in the “Screen Data” section on the right changes.

When you select the Screen Data drop down, you select the entity you want to use on the screen. On any screen template you choose, the controls are created in a similar way by looking at the entity definition. For instance, the labels for required properties appear as bold text. Also by default, screens use controls that match the underlying data types. So for instance, an editable String property is represented by a TextBox control, a Boolean becomes a CheckBox control, a Phone Number type gets the Phone Number control, etc. This is why it’s important to model your data correctly before creating screens. Although you can customize most of these things on a screen-by-screen basis, LightSwitch reads the settings in your data model to create smart defaults, speeding up the time it takes to create the application.

Let’s walk through this list of screen templates and some guidelines on why you would choose them.

List and Details Screen

You use the List and Details Screen when you want to see a list of all the records in a table and edit their details on one screen. By default, the screen contains two areas. On the left you will see a list that displays the summary of each record. On the right, it displays the details about the record that is selected. You can also choose to add any related entities to the screen and they will display below the detail controls in a grid. Users can use the search & sort functionality on the list to find records and then edit them all on one screen.

Use this template if you want to allow users to modify all the records in your table on one screen with no additional workflow. This can be particularly well suited for tables that have a smaller number of rows (records), like administration screens, and where only a few users would be modifying the data at the same time. Like all screens that work with multiple data rows, the query will return 45 rows of data at a time by default (you can change this on the screen properties). So it’s usually better to choose entities that don’t have too many or large fields so the application stays responsive as the database grows.

Editable Grid Screen

Similar to the List and Details Screen, you can also use the Editable Grid Screen when you want to modify all the records at the same time on one screen. In this case though, users are presented with a grid of data to edit in a tabular format. Users can press Tab to move from field to field to make changes and edit everything inline. You’ll want to choose this template if your users need to enter a lot of data quickly into a single table like maintenance and lookup tables or where you would only be editing a subset of fields so the user doesn’t need to scroll too much horizontally.

Details Screen

The Details Screen allows you to edit a single row of data from a table and optionally, any related data. When you click on a link or button to open a single record, the Details screen for that entity is displayed. LightSwitch generates a default details screen for you automatically at runtime if you do not create one yourself. Typically you will want to show all the editable properties for an entity on this screen as well as any related grids of data. This screen template has an additional option in the Add New Screen dialog. Once you select the Screen Data, you will see a checkbox “Use as Default Details Screen” which means to open this screen anytime the user opens a single record from this table anywhere in the system. This is also specified in the Data Designer for the “Default Screen” property for the entity.

New Data Screen

The New Data Screen allows you to insert new rows into a table one at a time. By default, the screen contains entries for every field of data. Although you can add related entities to this screen as grids, you may want to choose a small subset of just the required or common fields and then flow to another screen to enter the rest. LightSwitch will automatically open the default Details screen after the user saves so this type of “Add New, Save, then Edit” workflow is automatically set up for you.

Search Data Screen

You use the Search Data Screen when you want a user to be able to locate a single row of data in a table and then open another screen to edit just that row. By default, the screen displays a read-only grid of all the rows in a single table (again only 45 are returned at a time by default). To search for a record, you use the search box at the top right of the screen. The search returns all the rows where any string field matches the search term. Clicking on the summary link for the record opens the Details Screen. It is a very common workflow to have users search for records first before allowing edits to them so the search screen provides this behavior automatically. Typically this should be the first screen a user interacts with for large sets of data because it puts them into an efficient workflow that keeps the system responsive even as the database grows.

Adding Screens to the Address Book Application

Now that you understand what each screen template gives you, let’s create some screens for the Address Book application we’ve been building in this series. At the end of the previous posts we used the List and Details screen so that we could quickly test our data model. If the number of contacts you expect in your address book is relatively small (say less than 100), that screen may be enough to use for the entire application. Users can use the search functionality on the list to find contacts and then edit them all on one screen.

However, if we wanted to manage thousands of contacts for a business and allow multiple users accessing that data, it’s probably better to put users into a workflow where they first search for a contact and then can either edit one at a time or add a new one if they don’t find the contact they were looking for. It’s always good to create a simple flowchart of how the application should work:

First the user searches for a contact and if found then open the Contact Details screen and let them edit all the related contact data. Once the user saves the screen the data is simply redisplayed on the same screen until they close it. If the user does not find the contact they were looking for, they open the New Contact screen which allows them to enter just the contact entity data. When they Save, the Contact Details screen opens and they can finish entering any related data if they need.

So we just need three screens for our Address Book application; Search Data Screen, New Data Screen, and Details Screen. The order you create your screens is the default order in which they are displayed on the navigation menu. Note that Detail screens will not show up on the navigation menu because a specific record must be selected first. The first screen you create is the first one that is opened by default when the application starts so we’ll want to create the Search Screen first. You can change the screen navigation and how screens appear in the menu by right-clicking on the Solution Explorer and choosing “Edit Screen Navigation”. For a video demonstration on how to edit the screen navigation see: How Do I: Modify the Navigation of Screens in a LightSwitch Application?

So first create the Search Contact Screen by right-clicking on the Solution Explorer and selecting “Add Screen..” to open the Add New Screen dialog. Select the Search Data Screen template and then select the Contacts Screen Data and click OK.

Next create the New Data Screen in the same manner. This time, select the New Data Screen template. Then select the Contact entity for the Screen Data but do not select any related data. Then click OK

Finally we will add the Details Screen the same way but this time select all the related entities; EmailAddresses, PhoneNumbers, and Addresses. Also leave the “Use as Default Details Screen” checked.

Run it!

Now that we have all our screens defined hit F5 to build and run the application and let’s see what we get. You will notice that the Search screen opens right away and on the navigation menu we have both Search Contacts and Create New Contact screens available. I only have a couple rows of test data in here but if I had hundreds of contacts, LightSwitch would display only 45 rows at a time and we would use the paging control at the bottom of the grid to retrieve the next set of rows.

If you click on the last name of a contact it will open the details screen which allows us to edit all the contact information. Notice that LightSwitch also creates links in the first column of the related grids so that you can click on them and open additional detail screens for those records as well.

If the user does not see the contact in the list, they can click on the Create New Contact screen to enter new data.

Then once they save this screen, the Contact Details Screen opens for further editing of all the contact information.

If the Search screen is still open, the user can see newly added records by clicking the Refresh button on the ribbon.

Notice we have a LOT of functionality and a totally working Address Book application by just creating a data model and picking some screen templates.

Customizing Screen Layouts

As I mentioned earlier, all the screen templates are totally customizable so you can use them as-is or modify the layouts completely for your needs. In fact, you as the developer can change the layouts of screens while the application is running. When you are developing your application within Visual Studio LightSwitch you will see a “Design Screen” button at the top right of the running application window. Open a screen and then click that button to open the Screen Customization Mode. Here you can manipulate the content tree exactly how you like and see your changes in real time.

This comes in extremely handy for quickly modifying the order of fields as well as what, where, and how things are displayed on the screen. However, in order to customize your screen with code or additional data you will need use the Screen Designer back in Visual Studio. For more information on using the Screen Designer to customize screens see: Tips and Tricks for Using the Screen Designer.

For more information on building and customizing screens see the Working with Screens learn topic on the LightSwitch Developer Center and LightSwitch Tips & Tricks on dnrTV.

Wrap Up

As you can see the built-in screen templates provide a ton of functionality for you. We now have a fully functional Address Book application and there was no need to write any code to do it! Next post we’ll look at queries and how to design them in order to filter and sort data on our screens exactly how we want. Until next time!

Enjoy!

Go to next article –> Part 4: Too much information! Sorting and Filtering Data with Queries

Beginning LightSwitch Part 2: Feel the Love - Defining Data Relationships

2011-12-08T15:25:00Z

Welcome to Part 2 of the Beginning LightSwitch series! In the last post we learned about tables, or entities, in LightSwitch and how to use the Data Designer to define them. If you missed it: Beginning LightSwitch Part 1: What’s in a Table? Describing Your Data

In this article I want to focus on data relationships as we build upon the data model we started in part 1. Relationships define how information in one table corresponds to information in another table in a database. Or more generically, relationships define how an entity corresponds to another entity in (or across) a data source. You can think of relationships between entities like relationships between things in everyday life. For instance, the relationship between a school and its students is one that exists in the real world. Similarly, a real-world relationship exists between students and the classes that those students attend. In a data model, you may have one entity that contains students and another that contains classes they are attending. When you tie the two entities together, you create a relationship.

Building a Better Address Book

In the example we started in part 1, we’re building an address book application that manages contacts. In our current data model, we’re only storing one phone number, one email address and one address for our contact.

However, in real life contacts typically have more than one email, phone number, and address information. In order to model this in the database we are building through LightSwitch, we need to define additional tables and relate them to the contact table in a one-to-many relationship. A one-to-many relationship is probably the most common type of relationship you can define. In our case, this means that one contact can have many email addresses. One contact can have many phone numbers. One contact can also have many physical addresses.

Let’s start with email address. If we want to collect multiple email addresses for a contact we have a couple options. One option is to add a fixed number of email properties to our contact in the form of Email1, Email2, Email3. This means that we would never be able to collect more than 3 email addresses for any given contact. Depending on the type of application you are building this may be just fine. But if you start adding too many properties with the same meaning (in this case email) to your table, then it’s time to think of a different strategy. Instead we should create an EmailAddress table and define a one-to-many relationship.

From the Data Designer, click the “New Table” button and define an entity called EmailAddress with two required properties: Email (of type Email Address) and EmailType (of type String).

For EmailType we’ll create an Choice List, which you learned about in Part 1 of the series. This property will capture the type of email, whether that’s Personal or Work. I’ve also chosen to make the maximum length only 25 characters – we won’t ever need all 255.

Why don’t we make the maximum length 8 characters, which is the length of the longest value in the choice list? Because if we need to add a value to the choice list later that is a little longer than 8 characters, then we won’t have to change the data model. Disk space is cheap these days so it’s better to err on the side of longer max lengths so that all your data can fit into the underlying table. This avoids having to change the data model too often.

Defining Relationships in LightSwitch

Now that we have our EmailAddress entity it’s time to define the relationship. Click on the “Relationship…” button at the top of the Data Designer and this will open up the “Add New Relationship” dialog window. In the “To” column select Contact to set up the one-to-many relationship. The multiplicity is set to Many to One by default so we don’t need to change it. Multiplicity defines the type of relationship you want to create. In LightSwitch, you can also specify the multiplicity as One to Zero or One which means that only a maximum of one related entity would be allowed.

For more information on defining different types of relationships see: How to: Define Data Relationships

For information on how to model a many-to-many relationship in LightSwitch see: How to Create a Many-to-Many Relationship

You can also specify what happens to the email addresses when a contact is deleted. By default, this is set to “Restricted”. This means that a user would not be allowed to delete a Contact if they had any Email Addresses. Leaving the setting makes sense if we were working with Customers who had many Orders, for instance, but not in this case. We want LightSwitch to automatically delete any Email Addresses when we delete the Contact, so set the “On Delete Behavior” equal to “Cascade delete”.

The description at the bottom of the dialog is there to help you understand what you are doing when setting up the relationship. Once you click OK you will see the relationship in the Data Designer which will show all direct relationships to the entity you are working with. Notice that a Contact property is now added to the EmailAddress entity. This is called a navigation property and represents the Contact to which the EmailAddress belongs.

Double-click on the Contact entity to open it and you will notice a navigation property to all the EmailAddresses for that Contact. Navigation properties are used by LightSwitch on screens to navigate through your data, so it’s important to model them correctly.

Now that we’ve got the EmailAddress table defined and a relationship set up, we need to delete the Email property we had previously defined on the Contact itself. Select the Email property and hit the Delete key. Alternatively you can right-click and choose Delete on the menu. Do the same to delete the Address1, Address2, City, State, ZIP and Phone properties as well.

Next, let’s add a PhoneNumber table in the same way we added EmailAddress. You might wonder why we need to create a new table separate from the EmailAddress. This is because an EmailAddress and a PhoneNumber are different aspects of a Contact and have no relation to each other except through the Contact itself. Therefore, we need to create a new table.

Click the “Add Table” button and define the PhoneNumber entity with two required properties: Phone (of type Phone Number) and PhoneType (of type String). PhoneType will have a Choice List of “Cell”, “Fax”, “Home”, and Work”.

Next add the relationship to Contact exactly the same way as before. While the PhoneNumber entity is displayed, click the “Relationship…” button at the top of the Data Designer and specify the relationship to the Contact table.

Last but not least, we need to create an Address table to store multiple physical addresses for a Contact. Click the Add Table button and define the Address entity with the following properties AddressType, Address1, Address2, City, State, ZIP. Set the AddressType and Address1 properties as required. We will also specify a Choice List for the the AddressType property with values “Home”, “Work”, and “Other”.

Now set up the relationship for Address exactly as before. While the Address entity is displayed, click the “Relationship…” button and specify the relationship to the Contact table. Again we’ll choose “Cascade delete” so that any Addresses are deleted automatically if a Contact is deleted. This makes sense in the case of Contact because if the user deletes the contact from the system all their information should be automatically deleted. Keep in mind, however, that you may not want this behavior in other applications. For instance if you are building an order entry application you would want to restrict deletion of Customers if they had any Orders in the system in order to keep the Order history intact.

Now when we open the Contact entity in the Data Designer you can see all the direct relationships.

Testing the Address Book

Now that we have the data model designed, let’s quickly test it out by creating a screen. At the top of the Data Designer click the “Screen…” button to open the Add New Screen dialog. We’ll talk more about screens in a future post but for now just select the List and Details screen. Then drop down the Screen Data and select Contacts. Once you do this, you will see checkboxes for the additional related entities we created. Select all of them and click OK.

To build and launch the application hit F5. Now you can enter information using this screen. Click the “+” button on the top of the list box on the left to add new contacts.

Notice that LightSwitch read all the one-to-many relationships we set up in our data model and created a tabbed section of grids below the Contact details for Email Addresses, Phone Numbers and Addresses just like we would expect. The grids are editable by default so you can just type the related data directly into the rows.

Because we defined the relationships properly in our data model, LightSwitch was able to create a very usable screen for entering our data into all the tables in our database without much work at all. In the next post we’ll dive deeper into the Screen Templates and how to customize the layout of screens. Until next time!

Enjoy!

Go to next article –> Part 3: Screen Templates, Which One Do I Choose?

Beginning LightSwitch Part 1: What’s in a Table? Describing Your Data

2011-12-06T15:18:00Z

Welcome to Part 1 of the Beginning LightSwitch series! To get things started, we’re going to begin with one of the most important building blocks of a LightSwitch application, the table. Simply put, a table is a way of organizing data in columns and rows. If you’ve ever used Excel or another spreadsheet application you organize your data in rows where each column represents a field of a specific type of data you are collecting. For instance, here’s a table of customer data:

Customer table.

LastName	FirstName	BirthDate
Doe	Jane	10/20/1972
Smith	John	11/12/1956

When you work with databases, the data is stored in a series of tables this way. You then create relationships between tables to navigate through your data properly. We’ll talk about relationships in the next post. For this post let’s concentrate on how to create and work with tables in LightSwitch.

Tables (Entities) in LightSwitch

Applications you build with LightSwitch are forms-over-data applications that provide user interfaces for viewing, adding, and modifying data. LightSwitch simplifies the development of these applications by using screens and tables. Because LightSwitch can work with other external data sources that do not necessarily have to come from a database, we sometimes call tables “Data entities” or just “entities” in LightSwitch. So whether you have a table in a database or a list in SharePoint, both the table and the list are entities in LightSwitch. Similarly, a field in a table or a column in a list is referred to as a “property” of the entity.

Entities are how LightSwitch represents data and are necessary to assemble an application. You create these data entities by using the built-in application database, or by importing data from an external database, a SharePoint list, or other data source. When you create a new project in LightSwitch, you need to choose whether you want to attach to an existing data source or create a new table. If you choose to create a new table, LightSwitch will create it in the built-in database, also referred to as the intrinsic database. You then design the table using the Data Designer.

When you create tables and relate them together you are designing a data model, or schema. Describing your data this way takes some practice if you’ve never done it before, however, you will see that it’s pretty intuitive using LightSwitch. The better you are at describing your data model, the more LightSwitch can do for you when you create screens later.

The LightSwitch Data Designer

The Data Designer is where all your data modeling happens in LightSwitch whether you’re attaching to an existing data source or creating a new database. By using the Data Designer, you can define properties on your entities and create relationships between them. LightSwitch handles many typical data management tasks such as field validation, transaction processing, and concurrency conflict resolution for you but you can also customize these tasks by modifying properties in the Properties window, and/or by writing code to override or extend them.

For a tour of the Data Designer, see Data: The Information Behind Your Application

For a video demonstration on how to use the Data Designer, see: How Do I: Define My Data in a LightSwitch Application?

Creating a “Contact” Entity

Let’s walk through a concrete example of creating an entity. Suppose we want to create an application that manages contacts, like an address book. We need to create an entity that stores the contact data. First open Visual Studio LightSwitch and create a new project called ContactManager.

After you click OK on the New Project dialog, the LightSwitch home page will ask you if you want to create a new table or attach to an external data source.

Click “Create new table” and this will open the Data Designer. Now you can start describing the contact entity. Your cursor will be sitting in the title bar of the entity window when it opens. Name it “Contact” and hit the Enter key.

Once you do this you will see “Contacts” in the Solution Explorer under the ApplicationData node in the Data Sources folder. ApplicationData represents the intrinsic database that LightSwitch creates for you. Contacts refers to the table in the database that stores all the contact rows (or records). You can also think of this as a collection of entities, that’s why LightSwitch makes it plural for you.

Now we need to start defining properties on our entity, which correlates to the columns (or fields) on the table. You should notice at this point that the Contact entity has a property called “Id” that you cannot modify. This is an internal field that represents a unique key to the particular row of data. When you model tables in a database, each row in the table has to have a unique key so that a particular row can be located in the table. This Id is called a primary key as indicated by the picture of the key on the left of the property name. It is always required, unique, and is stored as an integer. LightSwitch handles managing primary keys automatically for you.

So we now need to think about what properties we want to capture for a contact. We also will need to determine how the data should be stored by specifying the type and whether a value is required or not. I’ve chosen to store the following pieces of data: LastName, FirstName, BirthDate, Gender, Phone, Email, Address1, Address2, City, State and ZIP. Additionally, only the LastName is required so that the user is not forced to enter the other values.

Also notice that I selected types that most closely match the type of data I want to store. For Phone and Email I selected the “Phone Number” and “Email Address” types. These business types give you built-in validation and editors on the screens. The data is still stored in the underlying table as strings, but is formatted and validated on the screen automatically for you. Validation of user input is important for keeping your data consistent. From the Properties window you can configure rules like required values, maximum lengths of string properties, number ranges for numeric properties, date ranges for date properties, as well as other settings. You can also write your own custom validation code if you need.

For more information on validation rules see: Common Validation Rules in LightSwitch Business Applications

If you don’t see the Properties window hit F4 to open it. Select a property on the entity and you will see the related settings you can configure for it. Depending on the type of data you chose for the property, you will see different settings. All properties have an “Appearance” section in the property window that allow you specify the Display Name that will appear in field labels on screens in the application. By default, if you use upper camel case (a.k.a Pascal case) for your entity property names then LightSwitch will put a space between the phrases. For instance, the Display Name for the “LastName” property will become “Last Name” automatically. So it’s best practice to use this casing for your entity properties.

You can also enter a “Description” for properties when their names aren’t intuitive enough for the user, or you just want to display a standard help message. The Description is displayed on screens as a Tooltip when the user hovers their mouse over the data entry control on any screen displaying that field.

Settings you make here in the Data Designer affect all the screens in the application. Although you can make additional customizations on particular screens if needed, you will spend the bulk of your time configuring your data model here in the Data Designer. That way, you don’t have to configure settings every time you create a new screen. The better you can model your entities, the more LightSwitch can do for you automatically when creating the user interface.

For the Contact entity let’s set a few additional settings. First, select the Id field and in the Appearance section, uncheck “Display by default”. This makes it so that the property doesn’t show up anywhere in the user interface. As mentioned earlier, the primary key is an internal field used to locate a row in the table and isn’t modifiable so the user does not need to see it on any screens in the application.

For BirthDate, set the minimum value to 1/1/1900 so that users can’t enter dates before that.

For Gender, we want to display a fixed set of static values to the user: “Female”,“Male”. In order to do this in LightSwitch we can use a Choice List. Click on “Choice List…” on the Properties window and this will open a window that will let you define the values that are stored in the table and the display name you want the user to see. For our purposes, we just want to store an “F” or “M'” in the underlying database table. Therefore, also set the Maximum Length to 1.

By default, maximum lengths of strings are set to 255 characters and should handle most cases, but you can change this for your needs.

Using the Properties window you can also configure settings on the entity itself. Select the title bar of the Contact entity and notice that there is a setting called Summary Property. Summary properties are used to “describe” your entity and are used by LightSwitch to determine what to display when a row of data is represented on a screen. By default, LightSwitch selects the first string property you defined on your entity but you can change that here.

You can also create computed properties to use as the summary property when you want to format values or display values from multiple fields.

For more information on Summary Properties see: Getting the Most out of LightSwitch Summary Properties

Testing the Contact Entity

Now that we have the Contact entity designed, let’s quickly test it out by creating a screen. At the top of the Data Designer click the “Screen…” button to open the Add New Screen dialog. We’ll talk more about screens in a future post but for now just select the List and Details screen. Then drop down the Screen Data and select Contacts and then click OK.

To build and launch the application hit F5. Now you can enter information into the contact table using this screen. Click the “+” button on the top of the list box to add new contacts.

Notice that the labels are displayed properly with spaces and the Last Name is bolded to indicate it’s a required field. Also if you enter invalid data as specified by the settings we made, a validation error will be displayed. When you are done, click the Save button on the ribbon at the top left of the application shell. This will save the data back into your development database. This is just test data stored in your internal database while you develop the application. Real data doesn’t go into the system until you deploy the application to your users.

In the next post we’ll talk about relationships and build upon our data model. Until next time!

Enjoy!

Go to next article –> Part 2: Feel the Love - Defining Data Relationships

Beginning LightSwitch: Getting Started

2011-12-01T15:08:00Z

For the month of December I’m going to write a series of posts aimed at the beginner developer getting up to speed with Visual Studio LightSwitch. At least I’m going to try ;-). It’s been a while since I was a beginner myself and started cobbling lines of code together – in fact, I started when I was 8 years old on an Atari 400. However, folks have told me I have a knack for this writing thing ;-) so I’m going to attempt to put myself in a beginner’s shoes and try to explain things as clear as I can.

There’s a ton of information out there on building LightSwitch applications, especially on the LightSwitch Developer Center but here I want to pull together a cohesive set of entry-level articles that focus on the most important concepts you need to learn in order to build any LightSwitch application. By the way, if you aren’t familiar with what LightSwitch is and what it can do I encourage you to check out the product overview here.

Here’s what I’m thinking for the series:

Before we get started with the series, the first thing to do is make sure you’re all set up with LightSwitch by visiting the LightSwitch Developer Center. There on the home page you will see clear steps to get started.

Download Visual Studio LightSwitch

Watch the instructional LightSwitch "How Do I?" videos

Get essential training

Ask questions in the LightSwitch forums

If you click on “Get essential training” then you will be taken to the Learn page which is broken down into the sections, Getting Started, Essential Topics and Advanced Topics. If you’re a beginner, the getting started section is what you want to start with:

Getting Started

Are you completely new to Visual Studio LightSwitch? This information will help you get started using LightSwitch to develop business applications for the desktop or the cloud. Be sure to check out the step-by-step “How Do I”videos.

Create Your First LightSwitch Application

Watch the LightSwitch How Do I Videos

Download the Visual Studio LightSwitch Training Kit

Get Started with the LightSwitch Starter Kits

The first link is to a step-by-step walkthrough that shows you how to quickly build a simple contact manager. It should take you 5 to 10 minutes to complete the application so it’s a great place to start. Then you can move onto the “How Do I” videos for more step-by-step video lessons to build a simple order entry application. If you want a super-quick way to get an application started, check out the starter kits. There’s currently six available for you to choose from and are full working applications you can use.

So do your homework kids, and in the next post we’ll start to dive into the series starting with my favorite topic – Data!

Enjoy!

LightSwitch Community & Content Rollup–November 2011

2011-11-30T15:01:00Z

A couple months ago I started posting a rollup of interesting community happenings, content, and sites popping up. If you missed those rollups you can check them out here, lot of great content and exciting events happened:

Here’s a rollup of LightSwitch goodies for November:

“LightSwitch Star” Contest

Do you have what it takes to be a LightSwitch Star? Show us your coolest, most productive, LightSwitch business application and you could win a Laptop and other great prizes!

Last month The Code Project launched the “LightSwitch Star” contest. You just answer some questions and email them a screenshot or two. They’re looking for apps that show off the most productivity in a business as well as apps that use extensions in a unique, innovative way. Check out the contest page on The Code Project for details.

There were some really cool applications submitted in November! Some were real production apps and some were samples/tutorials. Here’s a breakdown of what was submitted. Vote for your favorites! Prizes are given away each month.

6 Production Apps

Church+ - Church+ is a comprehensive, extensive and integrated church management application
Engineering App - A business application for a structural and architectural engineering company
Favourite Food App - The app was created to help remember favourite food
LightSwitch Timetable Management Application - A LightSwitch application used to manage the resources needed to build university timetables
PTA LightSwitch - A LightSwitch application manages student, parent, and staff information
Security Central - Security Central is a role based application designed for Corporate Legal and Physical Security Departments

7 Tutorials/Samples

LightSwitch Developer Center: Free Video Training from Pluralsight

We added over an hour and a half of video training to the Developer Center “How Do I” video page graciously donated by Pluralsight! Check out the modules we added:

We also updated the essential learning topics with new content and organized the learning sections better so have a look at all the new training available on the LightSwitch Developer Center!

Notable Content this Month

Here’s some more of the fun things the team and community released in November.

Extensions released in November (see all 64 of them here!):

Build your own extensions by visiting the LightSwitch Extensibility page on the LightSwitch Developer Center.

Team Articles:

Community Content:

Samples (see all of them here):

LightSwitch Team Community Sites

The Visual Studio LightSwitch Facebook Page has been increasing in activity lately. Become a fan! Have fun and interact with us on our wall. Check out the cool stories and resources.

Also here are some other places you can find the LightSwitch team:

LightSwitch MSDN Forums
LightSwitch Developer Center
LightSwitch Team Blog
LightSwitch on Twitter (@VSLightSwitch, #VisualStudio #LightSwitch)

Join Us!

The community has been using the hash tag #LightSwitch on twitter when posting stuff so it’s easier for me to catch it. Join the conversation! And if I missed anything please add a comment to the bottom of this post and let us know!

Enjoy!

I’m Speaking at Sac.NET User Group Tomorrow, Nov 29th!

2011-11-28T23:20:07Z

Tomorrow evening I’ll be presenting Visual Studio LightSwitch to Sac.NET in the Sacramento area. Please come join us! I always try and make it a fun and lively presentation and I’ll have tons of demos. Here are the details:

When: Tuesday, November 29th at 6:00 PM
Where: Rancho Cordova Library, 9845 Folsom Blvd, Rancho Cordova, CA 95827

Building Business Applications in Light Speed using Visual Studio LightSwitch
Visual Studio LightSwitch is the simplest way to build business applications for the desktop and cloud for developers of all skill levels. LightSwitch simplifies the development process by letting you concentrate on the business logic, while LightSwitch handles the common tasks for you. In this demo-heavy session, you will see, end-to-end, how to build and deploy a data-centric business application using LightSwitch. You will also see how professional developers can enhance the LightSwitch experience by tapping into its rich extensibility model.

See the event details and register here.

Hope to see you there!

Using the Save and Query Pipeline to “Archive” Deleted Records

2011-11-18T15:35:00Z

Before Microsoft, I used to work in the health care industry building software for hospitals and health insurance companies. In all of those systems we had detailed audit trails (change logging), authorization systems, and complex business rules to keep patient data safe. One particular requirement that came up often is that we never delete patient information out of the system, it was merely archived or “marked” as deleted. This way we could easily maintain historical data but limit the data sets people worked with to only current patients.

Fortunately LightSwitch makes this extremely simple because it allows us to tap into the save pipeline to perform data processing before data is saved. We can also tap into the query pipeline to filter data before it’s returned. In this post I’ll show you how you can mark records for deletion without actually deleting them from the database as well as how to filter those records out so the users don’t see them.

Tapping into the Save Pipeline

The save pipeline runs in the middle tier (a.k.a. logic tier) anytime an entity is being updated, inserted or deleted. This is where you can write business logic that runs as changes are processed on the middle tier and saved to data storage. (For more details on the save pipeline please see Getting the Most Out of the Save Pipeline in Visual Studio LightSwitch.)

Let’s say we have an application that works with customers. However we don’t ever want to physically delete our customers from the database. There’s a couple ways we can do this. One way is to “move” the record to another table. This is similar to the audit trail example I showed here. Another way you can do this is to “mark” the record as deleted by using another field. For instance, let’s take a simple data model of Customer and their Orders. Notice that I’ve created a required field called “IsDeleted” on Customer that is the type Boolean. I’ve unchecked “Display by Default” in the properties window so that the field isn’t visible on any screens.

In order to mark the IsDeleted field programmatically when a user attempts to delete a customer, just select the Customer entity in the data designer and drop down the “Write Code” button and select Customers_Deleting method.

Here are the 2 lines of code we need to write:

Private Sub Customers_Deleting(entity As Customer)
    'First discard the changes, in this case this reverts the deletion
    entity.Details.DiscardChanges()
    'Next, change the IsDeleted flag to "True"
    entity.IsDeleted = True
End Sub

Notice that first we must call DiscardChanges in order to revert the entity back to it’s unchanged state. Then we simply set the IsDeleted field to True. That’s it! Keep in mind when we change the state of an entity like this, the appropriate save pipeline methods will still run. For instance in this case, the Customers_Updating will fire now because we changed the state of the entity from Deleted to Unchanged to Modified. You can check the state of an entity by using the entity.Details.EntityState property.

Tapping into the Query Pipeline

Now that we’re successfully marking deleted customers, the next thing to do is filter them out of our queries so that they don’t display to the user on any of the screens they work with. In order to apply a global filter or sort on any and all customer entities in the system, there’s a trick you can do. Instead of creating a custom global query and having to remember to use that query on all your screens, you can simply modify the built-in queries that LightSwitch generates for you. LightSwitch will generate xxx_All, xxx_Single and xxx_SingleOrDefault queries on all entities for you and you can modify them in code. You access them the same way you do the save pipeline methods.

Drop down the “Write Code” button on the data designer for Customer and scroll down to Query methods and select Customers_All_PreprocessQuery.

This query is the basis of all the queries you create for Customer. I usually use this method to sort records in meaningful ways so that every default query for the entity is sorted on every screen in the system. In this case we need to also filter out any Customers that have the IsDeleted flag set to True, meaning only return records where IsDeleted = False:

Private Sub Customers_All_PreprocessQuery(ByRef query As System.Linq.IQueryable(Of Customer))
    query = From c In query
            Where c.IsDeleted = False
            Order By c.LastName, c.FirstName
End Sub

Notice we also have a related table called Order. I can do a similar filter on the Order entity as well. Depending on how you have users navigate to orders, this may not be necessary. For instance if you only show Orders on Customer detail screens then you don’t have to worry about the extra filter here.

Private Sub Orders_All_PreprocessQuery(ByRef query As System.Linq.IQueryable(Of Order))
    query = From o In query
            Where o.Customer.IsDeleted = False
            Order By o.OrderDate Descending
End Sub

See it in Action!

Okay time to test this and see if it works. I’ve created a List and Details screen on Customer. When we run this I can perform inserts, updates and deletes like normal. There’s nothing on the screen that needs to be changed and it acts the same as it normally would.

You mark the records for deletion….

.. and then click save to execute our Customers_Deleting logic. Once I delete a record and save, it disappears from the list on my screen, but it’s still present in the database. We can see that if we look in the actual database Customer table.

Leveraging the save and query pipelines can provide you with a lot of power over your data. This is just one of many ways you can use them to manipulate data and write business rules.

Enjoy!

Common Validation Rules in LightSwitch Business Applications

2011-11-11T15:45:00Z

Checking the validity of data input is a common requirement for any application that interacts with humans (and other systems), particularly business applications. I’ve never seen or written a data-entry application without implementing common validation rules for inputting data. LightSwitch has many ways to implement validation declaratively through the data designer as well as supporting custom code you write. Field (or property) validation is just one aspect of writing business rules in LightSwitch, but it’s definitely an important one. It’s your “first line of defense” in keeping user entered data consistent.

Although LightSwitch has some built-in business types and declarative validation settings, many times we need to write small snippets of code to check the format of data entered on a screen. Common things in the USA are States, ZIP codes, Social Security Numbers, UPIN, ISBN, etc. But you may also want to prevent things like numeric and symbolic values in people’s or place’s names or a variety of other rules based on string manipulation.

In this post, I’ll show you how to define declarative rules as well as write custom validation code in LightSwitch. I’ll also show you some common patterns you can use to validate strings. Let’s get started!

Declarative Validation Rules

First let’s walk through the types of validation you can specify declaratively without having to write any code. Let’s take a customer entity that we’ve designed with the data designer. It has the following fields:

Required Fields & Business Types

The first step to validating these fields is to determine their types and which ones are required. LightSwitch will automatically handle required fields as well as validation that comes with business types so you can set these up declaratively using the data designer without having to write any code. The built-in business types are Email, Phone, Money and Image but this is an extensibility point so you can download more. On our customer entity notice I’m only requiring that LastName is filled out. Required fields prevent the user from saving data if the field is left blank and the labels show up bolded on the screen.

When any validation fails, a message is displayed when the user’s cursor is in the field or if they click the validation summary at the top of the screen.

Notice that I have also selected the “Phone Number” and “Email Address” business types for the Phone and Email fields on our customer entity. Business types come with built-in validation and have additional properties that you can set in the properties window to indicate how the validation should work. For Email Address, you can select whether you want to provide a default email domain and if the domain is required:

For Phone Number you can supply additional formats it should validate against and in what order:

Specifying Field Maximum Lengths

Another important declarative validation rule is specifying a maximum length. By default all string fields default to 255 characters. This works for most of our fields because they have variable lengths and 255 will be plenty of room for our data. However, the SSN, State, and ZIP fields are fixed lengths of 11, 2 and 10 characters respectively. Anything over that isn’t a valid piece of data. You specify maximum lengths in the properties window at the bottom in the Validation section:

Preventing Duplicates with a Unique Index

You can also prevent duplicates by including required fields in a unique index. For instance if I wanted to prevent duplicate Last Names in the system then I could include it in the unique index.

Note that this adds the field to a unique index for the table and is enforced by the database. So the validation message will appear after the data is saved and checked on the server side. In the case of my customer entity this is not a good idea to limit duplicates this way because it’s pretty common to have customers with the same last name. You might consider using SSN but then we’d have to make this a required field and only customers with an SSN would be allowed into the system. This is too restrictive in this case, but including fields in a unique index can work well for other types of data entities where you want to prevent duplicate records.

Custom Validation Rules

When you can’t express a validation rule declaratively then you need to write some code. To write custom validation code, select the property you want on the entity then drop down the “Write Code” button and select the property_Validate method:

This will open the code editor to a method stub that allows you to write the custom validation code. When a rule fails, you use the results object to add your error message.

Private Sub LastName_Validate(results As EntityValidationResultsBuilder)
    ' Check the rule, if it fails then display an error message on the field:
    results.AddPropertyError("<Error Message>")
End Sub

You can also specify warnings and informational messages as well. Only error messages prevent data from being saved. To specify a warning or informational message on a field use the AddPropertyResult method and pass it the level of severity:

You can also specify entity-level errors which aren’t specific to certain fields, instead they will only show up in the validation summary at the top of the screen. You use the AddEntityError and AddEntityResult methods for this. These property validation methods run on the client first and then again on the server, however you just write them once and LightSwitch will take care of calling them at the appropriate times. For a deeper understanding of the validation framework please read: Overview of Data Validation in LightSwitch Applications

Simple String Validation & Formatting

The first rule I want to enforce is that the State field should always be entered in uppercase. There are a lot of string methods you can use to manipulate and validate string data. For instance to format strings in a variety of ways you can use the String.Format() method. There are also methods to find characters at certain positions (IndexOf), to check if a string contains another string (Contains), to return parts of strings (Substring), to trim whitespace (Trim), and much much more. See the documentation for all the string methods available to you.

In order to format the State field we can simply use the ToUpper() method. Since State isn’t a required field, we first check to see if the State property has a value and if so we make it upper case.

Private Sub State_Validate(results As EntityValidationResultsBuilder)
    If Me.State <> "" Then
        Me.State = Me.State.ToUpper
    End If
End Sub

Notice that this doesn’t report a validation error to the user, it just formats the string they enter. You can also use the property_Validate methods to perform formatting as well because the _Validate method will fire when the user tabs out of the field when the method runs on the client. However we still need to validate whether they entered a valid State code – “AA” is currently allowed and this isn’t a valid U.S. State. In order to validate all the possible state code combinations we can use Regular Expressions.

Using Regular Expressions

Regular expressions are used by many text editors, utilities, and programming languages to search and manipulate text based on patterns. Regular expressions are used all over the web to validate user input. In fact, one of my favorite sites is www.RegExLib.com which has thousands of community submitted patterns you can use in your own validation rules. In order to use regular expressions in your _Validate methods you use the RegEx class located in the System.Text.RegularExpressions namespave. So in order to check that the State is a valid US State we can write the following in bold:

Imports System.Text.RegularExpressions

Namespace LightSwitchApplication
    Public Class Customer

        Private Sub State_Validate(results As EntityValidationResultsBuilder)
            If Me.State <> "" Then
                Me.State = Me.State.ToUpper

                Dim pattern = "^(?:(A[KLRZ]|C[AOT]|D[CE]|FL|GA|HI|I[ADLN]|K[SY]|" +
                              "LA|M[ADEINOST]|N[CDEHJMVY]|O[HKR]|P[AR]|RI|S[CD]|" +
                              "T[NX]|UT|V[AIT]|W[AIVY]))$"
                
                If Not Regex.IsMatch(Me.State, pattern) Then
                    results.AddPropertyError("Please enter a valid US State.")
                End If
            End If
        End Sub
    End Class
End Namespace

Similarly we can use regular expressions to check ZIP codes as well. However I want to allow both 5 digit and 9 digit ZIP codes. I also want to allow the user to not have to specify the dash so we’ll do a little formatting as well first.

Private Sub ZIP_Validate(results As EntityValidationResultsBuilder)
    If Me.ZIP <> "" Then
        'Add the dash if the user didn't enter it and the ZIP code is 9 characters
        If Not Me.ZIP.Contains("-") AndAlso Me.ZIP.Length = 9 Then
            Me.ZIP = Me.ZIP.Substring(0, 5) + "-" + Me.ZIP.Substring(5)
        End If
        'Now validate based on regular expression pattern
        If Not Regex.IsMatch(Me.ZIP, "^\d{5}$|^\d{5}-\d{4}$") Then
             results.AddPropertyError("Please enter a valid US ZIP code.")
        End If
    End If
End Sub

Another rule I want to enforce is the SSN format that has the pattern “3 digits (dash) 2 digits (dash) 4 digits”. I want to do the same type of thing we did above where we won’t require the user to enter the dashes. So we can write the following:

Private Sub SSN_Validate(results As EntityValidationResultsBuilder)
    If Me.SSN <> "" Then
        'Add the dashes if the user didn't enter it and the SSN is 9 characters
        If Not Me.SSN.Contains("-") AndAlso Me.SSN.Length = 9 Then
            Me.SSN = Me.SSN.Substring(0, 3) + "-" + Me.SSN.Substring(3, 2) + "-" + Me.SSN.Substring(5)
        End If

        'Now validate based on regular expression pattern
        If Not Regex.IsMatch(Me.SSN, "^\d{3}-\d{2}-\d{4}$") Then
            results.AddPropertyError("Please enter a valid SSN (i.e. 123-45-6789).")
        End If
    End If
End Sub

You can do a lot with regular expressions and string manipulation. The last rule I want to enforce is not allowing users to enter numbers or symbols in the LastName and FirstName fields. They should only contain alphabetical characters and spaces are allowed. We can do something like this to enforce that:

Private Sub LastName_Validate(results As EntityValidationResultsBuilder)
    If Me.LastName <> "" Then
        'This pattern only allows letters and spaces
        If Not Regex.IsMatch(Me.LastName, "^[a-zA-Z\s]+$") Then
            results.AddPropertyError("Last Name can only contain alphabetical characters.")
        End If
    End If
End Sub

Private Sub FirstName_Validate(results As EntityValidationResultsBuilder)
    If Me.FirstName <> "" Then
        'This pattern only allows letters and spaces
        If Not Regex.IsMatch(Me.LastName, "^[a-zA-Z\s]+$") Then
            results.AddPropertyError("First Name can only contain alphabetical characters.")
        End If
    End If
End Sub

Notice that in this last example I’m using the same pattern. You’ll most likely have fields across entities in your application where you’ll want to use the same validation checks. When you start copying and duplicating code you should stop and think about consolidating it into a single library or class that you can call. This way if you have a bug in your validation code you fix it in just one place. Remember, the less code you write the less bugs you’ll have. ;-)

Creating a Common Validation Module

Let’s create a validation module that we can call from our validation methods that encapsulates all the types of validation routines we’d want to support across all the entities in our application. In the Solution Explorer flip to “File View” and under the Common project expand the UserCode folder. Right-click and add a new Module. I’ll name it CommonValidation.

To make these validation rules easy to discover and call from our _Validate methods we’ll create them as Extension Methods. Basically extensions methods “extend” types, like a string or integer or any other object type with your own custom methods. What’s cool is they appear in IntelliSense with you type the dot “.” after the type. To place extension methods in our module we just need to import the System.Runtime.CompilerServices and then attribute our method with the <Extension()> attribute.

Let’s take a simple example before we move our complex validation code in here. For instance let’s create an extension method that extends a string type with a method called “MyMethod”. The first parameter to your extension method is the type you are extending. Here’s how we could write the module. (Notice I added the comment section by typing three single quotes (‘’’) above the <Extension>):

Imports System.Runtime.CompilerServices

Module CommonValidation
    ''' <summary>
    ''' This is my extension method that does nothing at the moment. ;-)
    ''' </summary>
    ''' <param name="value">extend the string type</param>
    ''' <remarks></remarks>
    <Extension()>
    Public Sub MyMethod(ByVal value As String)
        'Do something
    End Sub
End Module

If we flip back to one of the property_Validate methods then we will now see this extension method in IntelliSense on any string type. (You need to flip to the “All” tab).

Notice there are a lot of “built-in” extension methods in the .NET framework once you flip to the “All” tab in IntelliSense. So if you were wondering why the icons looked different now you know why :-). Extension methods are a great way to add additional functionality to a type without having to change the implementation of the actual class.

Now sometimes we’ll need to pass parameters and/or return a value from our extension method. Any parameters you specify after the first one in an extension method becomes a parameter the caller needs to pass. You can also return values from extension methods by declaring them as a Function instead.

Imports System.Runtime.CompilerServices

Module CommonValidation
    ''' <summary>
    ''' This is my extension method that still does nothing. :-)
    ''' </summary>
    ''' <param name="value">extend the string type</param>
    ''' <param name="param">demoing parameter</param>
    ''' <returns></returns>
    ''' <remarks></remarks>
    <Extension()>
    Public Function MyMethod(ByVal value As String, param As Boolean) As Boolean
        'Do something
        Return True
    End Function
End Module

If we use this extension method now, you’ll see that a boolean parameter is required.

Now let’s start moving our validation methods in here. Let’s start with the State validation method. Notice in this method that we first format the value by making it upper case. In order to change the value of the type we’re extending we just pass the parameter ByRef instead of ByVal. I also want to allow passing of a parameter that indicates whether the field can be empty. So now here is our CommonValidation module with an IsState extension method:

Imports System.Runtime.CompilerServices
Imports System.Text.RegularExpressions

Module CommonValidation
    ''' <summary>
    ''' Checks if the string is formatted as a 2 character US state code
    ''' </summary>
    ''' <param name="state">string type extension</param>
    ''' <param name="isEmptyOK">True if empty values are allowed, otherwise false</param>
    ''' <returns>True if the string is a valid US state, otherwise false</returns>
    ''' <remarks></remarks>
    <Extension()>
    Public Function IsState(ByRef state As String, ByVal isEmptyOK As Boolean) As Boolean
        If state <> "" Then
            'States should always be upper case
            state = state.ToUpper

            'Now validate based on regular expression pattern
            Dim pattern = "^(?:(A[KLRZ]|C[AOT]|D[CE]|FL|GA|HI|I[ADLN]|K[SY]|" +
                          "LA|M[ADEINOST]|N[CDEHJMVY]|O[HKR]|P[AR]|RI|S[CD]|" +
                          "T[NX]|UT|V[AIT]|W[AIVY]))$"

            Return Regex.IsMatch(state, pattern)
        Else
            Return isEmptyOK
        End If
    End Function
End Module

Notice the nice IntelliSense we now get back in the _Validate methods when we call our extension method:

To finish off the State_Validate method all we need to do is check the return value to determine if we should add the property error or not:

Private Sub State_Validate(results As EntityValidationResultsBuilder)
    If Not Me.State.IsState(True) Then
        results.AddPropertyError("Please enter a valid US State.")
    End If
End Sub

OK cool! So here are all of the extension validation methods in the module:

Imports System.Runtime.CompilerServices
Imports System.Text.RegularExpressions

Module CommonValidation
    ''' <summary>
    ''' Checks if the string is formatted as a 2 character US state code
    ''' </summary>
    ''' <param name="state">string type extension</param>
    ''' <param name="isEmptyOK">True if empty values are allowed, otherwise false</param>
    ''' <returns>True if the string is a valid US state, otherwise false</returns>
    ''' <remarks></remarks>
    <Extension()>
    Public Function IsState(ByRef state As String, ByVal isEmptyOK As Boolean) As Boolean
        If state <> "" Then
            'States should always be upper case
            state = state.ToUpper

            'Now validate based on regular expression pattern
            Dim pattern = "^(?:(A[KLRZ]|C[AOT]|D[CE]|FL|GA|HI|I[ADLN]|K[SY]|" +
                          "LA|M[ADEINOST]|N[CDEHJMVY]|O[HKR]|P[AR]|RI|S[CD]|" +
                          "T[NX]|UT|V[AIT]|W[AIVY]))$"

            Return Regex.IsMatch(state, pattern)
        Else
            Return isEmptyOK
        End If
    End Function
    ''' <summary>
    ''' Checks if the string is formatted as a valid US ZIP code
    ''' </summary>
    ''' <param name="zip">string type extension</param>
    ''' <param name="isEmptyOK">True if empty values are allowed, otherwise false</param>
    ''' <returns>True if the string is a valid ZIP code, otherwise false</returns>
    ''' <remarks></remarks>
    <Extension()>
    Public Function IsZIP(ByRef zip As String, ByVal isEmptyOK As Boolean) As Boolean
        If zip <> "" Then
            'Add the dash if the user didn't enter it and the ZIP code is 9 characters
            If Not zip.Contains("-") AndAlso zip.Length = 9 Then
                zip = zip.Substring(0, 5) + "-" + zip.Substring(5)
            End If
            'Now validate based on regular expression pattern
            Return Regex.IsMatch(zip, "^\d{5}$|^\d{5}-\d{4}$")
        Else
            Return isEmptyOK
        End If
    End Function
    ''' <summary>
    ''' Checks if the string is formatted as a Social Security Number
    ''' </summary>
    ''' <param name="ssn">string type extension</param>
    ''' <param name="isEmptyOK">True if empty values are allowed, otherwise false</param>
    ''' <returns>True if the string is a valid SSN, otherwise false</returns>
    ''' <remarks></remarks>
    <Extension()>
    Public Function IsSSN(ByRef ssn As String, ByVal isEmptyOK As Boolean) As Boolean
        If ssn <> "" Then
            'Add the dashes if the user didn't enter it and the SSN is 9 characters
            If Not ssn.Contains("-") AndAlso ssn.Length = 9 Then
                ssn = ssn.Substring(0, 3) + "-" + ssn.Substring(3, 2) + "-" + ssn.Substring(5)
            End If

            'Now validate based on regular expression pattern
            Return Regex.IsMatch(ssn, "^\d{3}-\d{2}-\d{4}$")
        Else
            Return isEmptyOK
        End If
    End Function

    ''' <summary>
    ''' Checks if the string contains only upper and lower case letters
    ''' </summary>
    ''' <param name="value">string type extension</param>
    ''' <param name="isEmptyOK">True if empty values are allowed, otherwise false</param>
    ''' <param name="isWhitespaceOK">True if spaces are allowed, otherwise false</param>
    ''' <returns></returns>
    ''' <remarks></remarks>
    <Extension()>
    Public Function IsAlpha(ByVal value As String,
                            ByVal isEmptyOK As Boolean,
                            ByVal isWhitespaceOK As Boolean) As Boolean
        If value <> "" Then
            'Validation for strings that must be Alphabetical characters only. 
            Dim pattern As String
            If isWhitespaceOK Then
                'Allows spaces 
                pattern = "^[a-zA-Z\s]+$"
            Else
                'No spaces
                pattern = "^[a-zA-Z]+$"
            End If

            Return Regex.IsMatch(value, pattern)
        Else
            Return isEmptyOK
        End If
    End Function

    ''' <summary>
    ''' Checks if the string contains only upper and lower case letters and/or numbers
    ''' </summary>
    ''' <param name="value">string type extension</param>
    ''' <param name="isEmptyOK">True if empty values are allowed, otherwise false</param>
    ''' <param name="isWhitespaceOK">True if spaces are allowed, otherwise false</param>
    ''' <returns></returns>
    ''' <remarks></remarks>
    <Extension()>
    Public Function IsAlphaNumeric(ByVal value As String,
                                   ByVal isEmptyOK As Boolean,
                                   ByVal isWhitespaceOK As Boolean) As Boolean
        If value <> "" Then
            'Validation for strings that must be AlphaNumeric characters only. 
            Dim pattern As String
            If isWhitespaceOK Then
                'Allows spaces 
                pattern = "^[a-zA-Z0-9\s]+$"
            Else
                'No spaces
                pattern = "^[a-zA-Z0-9]+$"
            End If

            Return Regex.IsMatch(value, pattern)
        Else
            Return isEmptyOK
        End If
    End Function
End Module

And finally, our customer entity that calls these methods. Notice how much cleaner the code is now and we can reuse these across any entity in the application.

Namespace LightSwitchApplication
    Public Class Customer

        Private Sub State_Validate(results As EntityValidationResultsBuilder)
            If Not Me.State.IsState(True) Then
                results.AddPropertyError("Please enter a valid US State.")
            End If
        End Sub

        Private Sub SSN_Validate(results As EntityValidationResultsBuilder)
            If Not Me.SSN.IsSSN(True) Then
                results.AddPropertyError("Please enter a valid SSN (i.e. 123-45-6789).")
            End If
        End Sub

        Private Sub ZIP_Validate(results As EntityValidationResultsBuilder)
            If Not Me.ZIP.IsZIP(True) Then
                results.AddPropertyError("Please enter a valid US ZIP code.")
            End If
        End Sub

        Private Sub LastName_Validate(results As EntityValidationResultsBuilder)
            If Not Me.LastName.IsAlpha(False, True) Then
                results.AddPropertyError("Last Name can only contain alphabetical characters.")
            End If
        End Sub

        Private Sub FirstName_Validate(results As EntityValidationResultsBuilder)
            If Not Me.FirstName.IsAlpha(True, True) Then
                results.AddPropertyError("First Name can only contain alphabetical characters.")
            End If
        End Sub
    End Class
End Namespace

To pull this all together into a concrete example I’ve included the sample code here:
http://code.msdn.microsoft.com/Common-Validation-Rules-in-397bf46b

I hope this helps get you started writing your own more complex business rules and validation methods for your LightSwitch applications.

Enjoy!

LightSwitch Community & Content Rollup–October 2011

2011-10-31T19:59:54Z

Last month I started posting a rollup of interesting community happenings, content, and sites popping up. Particularly last month we had an explosion of extensions and a great list of community sites to check out:

LightSwitch Community & Content Rollup–September

Here’s a rollup of October tricks and treats!

“LightSwitch Star” Contest

Do you have what it takes to be a LightSwitch Star? Show us your coolest, most productive, LightSwitch business application and you could win a Laptop and other great prizes!

Today The Code Project launched the “LightSwitch Star” contest! Just answer the questions on the submission template and either create a YouTube video or write an article for Code Project explaining your application or extension. They’re looking for apps that show off the most productivity in a business as well as apps that use extensions in a unique, innovative way.

Check out the contest page on The Code Project for details. I can’t wait to see what you guys come up with. Good luck!

Sydney Lights it Up!

To kick off the LightSwitch launch in Australia, they lit up the Microsoft buildings on the waterfront with a cool light show that made the local news in Seattle! Watch the light show they did on YouTube: LightSwitch Launch on Sydney Waterfront

Notable Content this Month

Here’s some more of the fun things the team and community has released in October.

Extensions released in October (see all 62 of them here!):

Build your own extensions by visiting the LightSwitch Extensibility page on the LightSwitch Developer Center.

Books:

New E-book published: Developing Real-world Applications with LightSwitch by @gillcleeren
New Book: Microsoft Visual Studio LightSwitch Business Application Development (now on Kindle)

Team Articles:

Community Articles:

Videos & Podcasts:

Samples (see all of them here):

Events Coming Up

Here some conferences and events I know about coming up soon that have LightSwitch presence.

DevConnections Las Vegas - 10/31- 11/3
LightSwitch and Azure Around Australia – Perth 11/2, Sydney 11/10
South Bay.NET User Group – 11/3
LightSwitch Onramp – 11/10
Louisville .NET Meetup – 11/17
The Power of LightSwitch on Windows Azure – Wellington 11/16 , Auckland 11/17

LightSwitch Team Community Sites

And of course don’t forget the LightSwitch Developer Center!

This is your one-stop-shop to training content, samples, extensions, documentation, podcasts, a portal to the forums, community, and much more. All of the team content is aggregated onto this site, and we also aggregate all the community submitted extensions and samples. It’s the first place you should go if you’re just learning LightSwitch.

Also here are some other places you can find the LightSwitch team:

LightSwitch “How Do I” Videos
LightSwitch MSDN Forums
LightSwitch Team Blog
LightSwitch on Facebook
LightSwitch on Twitter (@VSLightSwitch, #VisualStudio #LightSwitch)

Join Us!

Enjoy!

Talking LightSwitch in the South Bay on Wednesday Nov. 2nd

2011-10-28T18:46:02Z

I’ll be speaking about LightSwitch next Wednesday in Mountain View so if you’re in the area come on out and I’ll show you what LightSwitch can do for you! See how to build business applications in light speed….

Building Business Applications in Light Speed with Visual Studio LightSwitch

When: Wednesday, 11/2/2011 at 6:00 PM
Where: Hacker Dojo, 140A S Whisman Rd Mountain View, CA

Visual Studio LightSwitch is the simplest way to build business applications for the desktop and cloud for developers of all skill levels. LightSwitch simplifies the development process by letting you concentrate on the business logic, while LightSwitch handles the common tasks for you. In this demo-heavy session, you will see, end-to-end, how to build and deploy a data-centric business application using LightSwitch. You will also see how professional developers can enhance the LightSwitch experience by tapping into its rich extensibility model.

Hope to see you there!

How to Connect to and Diagram your SQL Express Database in Visual Studio LightSwitch

2011-10-27T14:08:00Z

Visual Studio LightSwitch makes it easy to create and model database tables using the Data Designer. With this designer you have a simple interface into the Tables, Columns and Relationships that make up your data model. When you create tables this way, under the covers LightSwitch creates a SQL Express database file at design time. SQL Express is installed with Visual Studio LightSwitch and is required for it to work properly. When you are ready to deploy your application you can choose to deploy it to any version of SQL Server, including SQL Azure, however during development time the LightSwitch development environment manages your database through SQL Express. We call this the Intrinsic Database.

Many folks have asked me how I created the database diagram in the last article I wrote and I’ve seen the question in other Visual Studio forums as well. All versions of Visual Studio (not just LightSwitch) allow you to connect to SQL Server from the Server Explorer window. This allows you to browse the tables and data. However getting the diagramming support to work is somewhat of a mystery for folks so in this post I’ll show you how you can get it to work on your local development machines.

PLEASE NOTE: This technique requires you be an administrator of your machine and you installed Visual Studio (and thus SQL Express) under that administrator login. This technique should only be used for development environments.

Connecting to the Server Explorer

To connect to the intrinsic database open the Server Explorer (Ctrl+Alt+S).

Then right-click on the Data Connections and select “Add Connection…” to add a new connection.

We need to connect to a specific database file on disk, not an attached database. During development time LightSwitch creates what’s called a User Instance database that is dynamically attached to the SQL Express service when it is accessed. This makes it possible for you to copy LightSwitch development solutions and samples from machine to machine and not lose any of the critical data information.

So when the “Add Connection” dialog comes up click the “Change…” button.

Then change the data source to “Microsoft SQL Server Database File” and click OK.

Now you need to specify the file location of the database. The database file is always named ApplicationDatabase and it is located in the \bin\Data folder under your solution. Select the ApplicationDatabase.mdf file and click OK.

Use Windows Authentication and click the Test Connection button. If it succeeds click OK. (If it doesn’t, make sure you are logged into the machine as the same administrator you used to install Visual Studio).

Now you can see all the internal tables that LightSwitch has created for you based on your model in the Data Designer.

The Server Explorer lets you make any number of changes to not only the data stored in the tables but also the structure (schema). BE CAREFUL here. Any changes you make directly to the database structure WILL NOT automatically be reflected in your data model and you could break it. The Data Designer makes sure your changes to the model stay in sync with the database but if you modify the database outside the Data Designer all bets are off. You have been warned! :-)

Setting Up Diagramming Support

However there are other nifty things you can do in the Server Explorer like enter more records of data as well as create database diagrams. In order to create a database diagram expand the “Database Diagrams” node. You will be presented with the following dialog:

Click Yes and another dialog will be presented:

Click Yes again. If the message goes away you’re all set. However, a lot of times it’s not that easy. Usually an error message appears similar to the following:

In order to get diagramming support working, the owner of the database must be a local login and a valid db_owner, not a domain login like I am above. So in order to fix this we need to change the database owner to a local account. When Visual Studio installs SQL Express, the service logs on as NETWORK SERVICE. You can check this by going to Services (Windows Start, search “Services”) and looking at the SQLEXPRESS service entry.

So if we change the database owner to this login, the diagramming will work. Although you can do this in SQL Server Management Studio, it’s not installed out of the box with Visual Studio so I’m going to show you how to get this working without installing anything else. First go back to the bin\Data folder where your intrinsic database is located and make a copy (just in case :-)).

Then grant the NETWORK SERVICE permissions to the folder, allowing Full Control. (Right click on the \Data folder, select properties, security tab, click the Add button, enter NETWORK SERVICE, OK, then check off Full Control.)

Now we need to create a small SQL script to attach the database to the SQL Express service, change the owner and then detach it again. Open notepad and paste the following into a new text file, modifying the path to your database files.

USE master
GO
-- Change the path to your database files! 
-- Make sure the login that runs your SQLEXPRESS service (i.e. NETWORK SERVICE) has file access to this folder

CREATE DATABASE ApplicationData ON 
( FILENAME = N'C:\...\Projects\MyApplication\MyApplication\bin\Data\ApplicationDatabase.mdf' ),
( FILENAME = N'C:\...\Projects\MyApplication\MyApplication\bin\Data\ApplicationDatabase_log.ldf' )
FOR ATTACH
GO

ALTER AUTHORIZATION ON DATABASE::ApplicationData TO [NT AUTHORITY\SYSTEM]
GO

USE master
GO
EXEC master.dbo.sp_detach_db @dbname = N'ApplicationData'
GO

Save the file as C:\Temp\ChangeOwner.sql – with the SQL extension. Next open an administrator command prompt.

First close Visual Studio in order to close all connections to the database file. Then type the following to execute the script:

sqlcmd -S .\SQLEXPRESS –i "C:\Temp\ChangeOwner.sql"

Creating a Diagram

Now that’s all done open up Visual Studio again and you should see the ApplicationDatabase still sitting in the Server Explorer. To connect just expand the database node and then right click on the Database Diagrams folder and select “Add New Diagram”. Everything should be working now.

When you add a new diagram it will ask you what tables you want to include. In a LightSwitch database all the tables that start with “aspnet_” as well as the “RolePermissions” are internal and related to the authentication & authorization system. They cannot be modified so you can omit these from your diagram.

Click Add and the diagram will be generated based on the tables you chose.

In order to save the diagram just close the window by clicking on the “X” on the tab and you will be prompted to save the diagram back to the database.

REMEMBER

Using the Server Explorer against your intrinsic LightSwitch database can be useful for entering data or generating diagrams but anytime you want to make changes to the actual structure/schema of your tables you MUST do that in the Data Designer otherwise you risk getting your model out of sync.

I hope this helps not only LightSwitch users but also other Visual Studio users get diagramming support working on their databases.

Enjoy!

LightSwitch Tips & Tricks on dnrTV

2011-10-17T20:51:26Z

Check it out, I’m back with the always entertaining Carl Franklin on dnrTV showing some tips and tricks you can use in your screens and queries. See how you can add command bars to any control, create custom search screens, pass parameters into queries, and fine-tune the layout of your screens.

Watch: Beth Massi on Tips and Tricks in LightSwitch 2011

Here’s some links I’d like to share from the show:

Enjoy!

Customizing the LightSwitch Time Tracker Starter Kit

2011-10-13T14:07:00Z

Visual Studio LightSwitch released with a set of 7 Starter Kits that people can use as starting points for their own applications. You can download them or install them directly in Visual Studio LightSwitch using the Extension Manager. Take a look at Robert Green’s Visual Studio Toolbox episode for more info.

One of the Starter Kits is a Time Tracker application for tracking employee timesheets against projects they are working on. Here’s the data model:

Employees enter multiple time entries onto their time sheets and a project is selected on each of the time entries. This week a blog reader asked how he could get a tally of all hours worked on a given project for a given employee. In this post I’ll describe how to create a screen that filters on project and employee and tallies all the time entries.

Creating the Parameterized Query

In order to do this we’ll need to create a parameterized query that optionally filters on Employee and Project. Right-click on the TimeEntries table in the Solution Explorer and select “Add Query”. Name it TimeWorked. Next we need to add a filter on the Project.Id “equals” then choose “@ Parameter” and add a new parameter called ProjectID. Do the same thing for the employee by expanding TimeSheet.Submitter and select Id “equals” another “@ Parameter”. This time add a new parameter called SubmitterID.

Then select the SubmitterID parameter and in the property window check “Is Optional” to make that one an optional parameter. That way we can optionally see the total hours worked for a selected project across all our employees. Also add a sort by the SubmittedDate Descending. Your query should now look like this.

Create the Custom Search Screen

Next add a new search screen based on this query. Click the “Add Screen” button at the top of the query designer and choose the Search Data Screen template and select the TimeWorked query you just created for the Screen Data and click OK.

Notice that LightSwitch added screen fields for the filter criteria that needs to be fed into the query. However we don’t want users to have to type in IDs, instead we want a dropdown of choices for both Employee and Project. So delete the two fields on the view model on the left-hand side of the screen designer:

When you delete these fields the controls in the content tree will also be removed. Next click the “Add Data Item” button at the top and add a Local Property of Type “Project (entity)” and name it “SelectedProject”, then click OK.

Do the same thing for Employee. Click the “Add Data Item” button again and add a Local Property of Type “Employee (entity)” and name it “SelectedEmployee”, then click OK. Now you should see Employee and Project in your view model. Drag them to the top of the content tree to place them above the results Data Grid. LightSwitch will automatically create drop-down controls for you.

The next thing we need to do is hook up the selected items to the query parameters. First select the ProjectID query parameter in the view model, then in the properties window set the binding to SelectedProject.Id:

Once you do this a grey arrow will indicate the binding on the far left. Do the same thing for SubmitterID and set the binding to SelectedEmployee.Id.

Calculating Hours

The final piece of the screen we need is the tally of all the hours worked across the time entries that are returned based on our filter criteria. Click “Add New Data Item” once again and this time choose Local Property of Type Decimal, uncheck “Is Required” and call it TotalHours.

Now you will see the TotalHours field in the view model. Add it to the screen anywhere you want by dragging it to the content tree. In this example I’ll add it above the results grid. Make sure to change the control to a Label. You can also select how the label font appears by modifying that in the properties window.

Last thing we need to do is calculate the total hours based on this filter. Anytime the TimeWorked query is successfully loaded we need to calculate the TotalHours. Select TimeWorked in the view model and then at the top of the screen drop down the “Write Code” button and select the “TimeWorked_Loaded” method. Write this code to tally the hours:

Private Sub TimeWorked_Loaded(succeeded As Boolean)
    Me.TotalHours = 0 
    If succeeded Then
        For Each te In TimeWorked
            Me.TotalHours += te.HoursWorked
        Next
    End If
End Sub

Now run it! Once you select a project the query will execute and the total hours displayed for all employees that worked on the project. If you select an employee, the results will narrow down further to just that employee’s hours.

Starter kits are a GREAT way to get started with Visual Studio LightSwitch. I urge you to explore them and customize them for your exact needs.

Enjoy!

Resources from Silicon Valley Code Camp LightSwitch Sessions

2011-10-10T20:45:33Z

Thanks to Peter Kellner and all the folks that made for another extraordinary Silicon Valley Code Camp this year! There were over 2300 people that came to Foothill college in Los Altos this weekend. And what gorgeous weather we had!

Thanks to all those folks who came out to my LightSwitch talks Saturday afternoon, I had a blast! Here are all the resources from the sessions to check out. Of course, all of these resources are available from the LightSwitch Developer Center, including the free trial download.

Intro Session: Building Business Applications Quickly with Visual Studio LightSwitch

Vision Clinic Walkthrough & Sample
LightSwitch Training Kit – See Demo: Introducing Visual Studio LightSwitch

Advanced Session: LightSwitch Advanced Development and Customization Techniques

Contoso Construction Sample
Extending Visual Studio LightSwitch
LightSwitch Training Kit – See Lab: LightSwitch Control Extensions

And here are some more good resources that you’ll want to explore as you start building your LightSwitch business apps!

Start

Learn

Extend

Browse Popular LightSwitch Extensions Online

Community

Enjoy!

“I Command You!” - LightSwitch Screen Commands Tips & Tricks

2011-10-06T20:58:22Z

In this post I wanted to pull together some command tips that seem common when building features into the screens in your business applications. Some of them are floating around on the LightSwitch forums, community blogs, and samples but I thought having these in one place would be easier for folks. I use these techniques a lot when I’m building my own LightSwitch applications.

In this article I will show you:

How to Create a Command
How to Open a Open Another Screen (with or without Parameters)
How to Open a Modal Dialog or Window
How to Open the Browser & Navigate to a URL
How to Open the Calculator (or other Windows System Programs)
How to Open an “Open File” Dialog
How to Open the Default Program for a File (like Office Documents)

So let’s get started!

How to Create a Command

First off let me start by showing you what I mean by “screen commands”. Commands are buttons (or links) that users click to perform some sort of action. You can add commands to any control like grids & textboxes as well as the screen itself. Take a look at the documentation

How to: Add a Custom Command to a Screen. Commands show up in the model on the left-hand side of the screen designer and are indicated by the pink method icons. You always have three commands by default – Close, Refresh and Save. Refresh and Save also appear in the Screen Command Bar by default when running the application.

Creating commands has two main parts – creating the actual button (or link), then writing the code to execute the command in the command_Execute method. (You can also control whether the command buttons are enabled or disabled by writing code in command_CanExecute method.) Commands can be buttons or links and typically are located in the ribbon at the top of the screen (called the Screen Command Bar) as well as on Data Grids or topmost group controls (called Command Bar) and these are displayed by default when you create a screen. However, you can add commands to any control on a screen that you want so you have a lot of flexibility on the placement of your commands. Here is a screen with a variety of commands:

To add a command to the Screen Command Bar or Command Bar for a group just select it in the screen designer and click the +Add button. Depending on the control LightSwitch will present a set of pre-built commands. On group controls that display data from a single entity, you can add a prebuilt command “Delete” that will delete the current record. On data grids and lists that work with multiple entities you can select a from a variety of commands for adding, editing and deleting records. You can also overwrite the default behavior of these commands by right-clicking on them and selecting “Override Code”.

To create a new custom command, select “New button” and then give it a method name. At that point it will appear in the model on the left of the screen designer. Once you create the button, right click on it and select “Edit Execute Code” to write the code for the command.

If you don’t see a Command Bar on a control (like a label, textbox, date picker, autocomplete box, etc.) just right-click on the control and then on the menu you will see "Add Button…”. You can also click “Add Layout Item” at the top of the screen designer and select “Add Button…”. If you’re running the application in screen customization mode then select the control and click the “Add button” icon at the top of the content tree. This gives you the flexibility to put commands anywhere on the screen you want.

Now that you understand how to create commands anywhere you want, here are some tips & tricks on some common code that you can write for your custom commands. Note that you can write this code in any of the screen methods, they are not limited to commands. Although that’s probably the most common place you will see custom code like this.

How to Open Another Screen (with or without Parameters)

This one is very common and very simple in LightSwitch. In order to open a screen you use the Application object to access all your screens and call one of the “Show” methods.

Private Sub OpenMyScreen_Execute()
    ' Write your code here.
    Me.Application.ShowCreateNewCustomer()
End Sub

You can also define optional and required parameters on screens. For instance if we create a screen based on a query that requires a parameter then LightSwitch will generate a screen field for us in the model that is used to feed the query. You can select this field and in the properties window you can indicate that it is a screen parameter as well as whether it is required or not.

Keep in mind that screens that have required parameters will not show up in the main navigation bar because they must be called in code.

Private Sub OpenMyScreen_Execute()
    ' Write your code here.
    Me.Application.ShowSearchCustomersByPostalCode("98052")
End Sub

For a couple video demonstrations to see this in action please watch:

How to Open A Modal Dialog or Window

There are also a couple methods on screens that allow up to pop up modal message boxes and input boxes. To present a message to the user you write the following:

Me.ShowMessageBox("This is the message")

You can also specify a caption and what kind of buttons you want on the message box like OK, OK and Cancel, Yes and No, etc. ShowMessageBox will return a value that indicates what the user chose. In this example I am want to ask the user if they are sure they want to delete a record. Since Delete is a pre-built command, just right-click on it in the screen designer and select “Override Code”. Then you can write the following:

Private Sub gridDeleteSelected_Execute()
    If Me.ShowMessageBox("Are you sure you want to delete this record?",
                         "Delete",
                         MessageBoxOption.YesNo) = Windows.MessageBoxResult.Yes Then

        Me.Customers.SelectedItem.Delete()
    End If
End Sub

You can also get input from the user by using an input box. This is handy for presenting a message and requesting a single answer from the user.

Private Sub Search_Execute()
    If Me.CustomerPostalCode = "" Then
        Me.CustomerPostalCode = Me.ShowInputBox("Please enter a postal code to search for:", "Search")
    End If
    Me.CustomersByPostalCode.Load()
End Sub

You can also open other modal windows that you create on the screen in the content tree. For instance, you may have a lot of fields on a record and you want to display the entire set of fields in a modal window when the user clicks a row command in a search screen instead of requiring them to scroll. Simply add the Selected Item to the bottom of your screen and then change the control type to a Modal Window. You can then lay out the fields exactly how you like. By default LightSwitch will create a button command for you to launch the modal window automatically but you can turn this off in the properties window by unchecking “Show Button”.

In order to launch this modal window from your own command you can call OpenModalWindow and pass it the Name of the Modal Window control:

Private Sub ShowAllFields_Execute()
    Me.OpenModalWindow("Customers_SelectedItem")
End Sub

This video also shows a couple of these techniques:

How Do I: Open a Screen After Saving Another Screen in a LightSwitch Application?

How to Open the Browser & Navigate to a URL

This is a common one for sure. Maybe you want to open a browser to a specific site, or a report from SQL reporting services, or a SharePoint site. For instance say we have a textbox for our website address field. We can add a command to the control and then execute code to open the address. First you will need to add a reference to the System.Windows.Browser assembly. On the Solution Explorer flip to file view and then right-click on the Client project and select Add Reference.

Then on the .NET tab select System.Windows.Browser and then click OK.

Then you’ll need to add these imports at the very top of your code file:

Imports Microsoft.LightSwitch.Threading
Imports System.Runtime.InteropServices.Automation

Now you can write code to open a browser to a specific URL:

Private Sub OpenSite_Execute()
    Dispatchers.Main.BeginInvoke(
        Sub()
            'Dim uri As New Uri("http://www.bing.com") 'Go to a specific website
            Dim uri As New Uri(Me.Customer.WebSite) 'Go to website stored in the Customer.WebSite field

            If (AutomationFactory.IsAvailable) Then
                Dim shell = AutomationFactory.CreateObject("Shell.Application")
                shell.ShellExecute(uri.ToString)

            ElseIf (Not System.Windows.Application.Current.IsRunningOutOfBrowser) Then
                System.Windows.Browser.HtmlPage.Window.Navigate(uri, "_blank")
            End If
        End Sub)
End Sub

Notice that we need to make sure we always call this code from the Main UI thread. If you don’t you will get an error if you are running LightSwitch as a browser application. When running in desktop mode the AutomationFactory.IsAvailable is true so that means we need to open the default browser. If we are already in the browser, then we can simply navigate to a new page.

You can also do a lot of other things in desktop mode like access the Windows file-system, open default programs, and use COM automation. Here’s some more tips for your desktop applications.

How to Open the Calculator (or other Windows System Programs)

This is based on a tip I saw from Paul Patterson that I thought was pretty clever: Open the System Calculator with Interop. This is a nice productivity feature for users working with numerical values on your screen. Just like the previous example that opens the browser, you can open any Windows system programs with ShellExecute in desktop mode (this will not work in browser mode). First add this import to the top of your code file:

Imports System.Runtime.InteropServices.Automation

Then you can simply pass to ShellExecute the name of the Windows program you want to open:

Private Sub OpenProgram_Execute()
    Try
        If (AutomationFactory.IsAvailable) Then
            Dim shell = AutomationFactory.CreateObject("Shell.Application")

            shell.ShellExecute("calc.exe") 'Open the calculator
            shell.ShellExecute("notepad.exe") 'Open notepad
            shell.ShellExecute("mspaint.exe") 'Open Paint
        End If

    Catch ex As Exception
        Me.ShowMessageBox(ex.ToString)

    End Try
End Sub

How to Open an “Open File” Dialog

You may want to request a file from a user and you need to present the Open File Dialog. Here’s how you can do that. First add these imports to the top of your code file:

Imports Microsoft.LightSwitch.Threading
Imports System.Runtime.InteropServices.Automation
Imports System.Windows

Then write this code to open the Open File Dialog which prompts the user for a file:

Private Function GetFile(fileFilter As String) As IO.FileInfo
    Dim file As IO.FileInfo = Nothing

    'This only works in desktop mode in LightSwitch.
    If AutomationFactory.IsAvailable Then

        'You need to open the file dialog on the main thread.
        Dispatchers.Main.Invoke(
            Sub()
                Dim dlg As New Controls.OpenFileDialog
                dlg.Filter = fileFilter

                If dlg.ShowDialog = True Then
                    file = dlg.File
                End If
            End Sub)
    End If
    Return file
End Function

Then you could use this to guide the user into opening certain types of files by specifying a filter. Keep in mind that you can read from any file on the local machine but you are limited to writing or accessing the full path or details of the file to only those that come from trusted locations like the user’s My Document folder.

Private Sub FindFile_Execute()
    Try
        'Request a text file:
        Dim myFile = GetFile("Text Files (*.txt)|*.txt")

        'You can read from files anywhere on disk that the user has access to.
        ' However you can only write to files in trusted locations like My Documents.
        Using fs = myFile.OpenText()
            Me.ShowMessageBox(fs.ReadToEnd())
            fs.Close()
        End Using

        'Try to get the full path to the file. This will throw a SecurityException if
        ' the file is not from a trusted location like My Documents.
        Me.ShowMessageBox(myFile.FullName)

    Catch ex As System.Security.SecurityException
        Me.ShowMessageBox("Please select a file in your Documents, Music or Pictures folder.")

    Catch ex As Exception
        Me.ShowMessageBox(ex.ToString)
    End Try
End Sub

Also note that in LightSwitch opening the OpenFileDialog will only work in Desktop applications which have elevated permissions. If you try to directly launch the OpenFileDialog in a browser-based application you will get a “Dialogs must be user-initiated” error message. This is because Silverlight dialogs (like OpenFileDialog) can only be opened from “user actions”, like a button clicked event handler. The reason why this won’t work with LightSwitch is because we invoke the button logic asynchronously, so the code is not considered to be “user-initiated”. For a work-around see the “Add a Simple Silverlight dialog” section of Matt Sampson’s post: How Do I Import Data While Running a LightSwitch Web Application.

How to Open the Default Program for a File (like Office Documents)

If you want to open a file in it’s default program (specified by Windows) you can just use ShellExecute again. In this case you probably need to request the file from the user first so you can use the GetFile method in the previous tip above for that. Add these imports to the top of your code file:

Imports Microsoft.LightSwitch.Threading
Imports System.Runtime.InteropServices.Automation
Imports System.Windows

Then you can write code like this to request the file and then open it with the default program. Here’s a couple examples:

Private Sub OpenFile_Execute()
    Try
        If (AutomationFactory.IsAvailable) Then
            Dim shell = AutomationFactory.CreateObject("Shell.Application")

            'Open a text file 
            Dim textFile = GetFile("Text Files (*.txt)|*.txt")
            shell.ShellExecute(textFile.FullName)

            'Open an Excel file
            Dim excelFile = GetFile("Excel Files (*.xlsx)|*.xlsx")
            shell.ShellExecute(excelFile.FullName)

            'Open a Word Document
            Dim wordFile = GetFile("Word Files (*.docx)|*.docx")
            shell.ShellExecute(wordFile.FullName)
        End If

    Catch ex As System.Security.SecurityException
        Me.ShowMessageBox("Please select a file in your Documents, Music or Pictures folder.")

    Catch ex As Exception
        Me.ShowMessageBox(ex.ToString)
    End Try
End Sub

Wrap Up

I hope this post showed you some cool tips and tricks you can use on your screens and commands. Remember that you can put commands anywhere on your LightSwitch screens and there are a good set of prebuilt commands you can use for working with data. However if you need to provide users additional productivity features you can easily create custom commands and do almost anything you want.

Enjoy!