Building Data-Centric Applications with Microsoft Visual Studio LightSwitch

This chapter is from the book 

Testing the Application on the Development Machine

LightSwitch applications can be executed on the desktop or inside a web browser. This is a tremendous benefit because you can make your programs available as desktop or web applications just by changing one setting. In this chapter, you see how to run your program both as a desktop client and as a web application, starting from the default setting that is the desktop client.

Starting the Application as a Desktop Client

To run the application, press F5. After a few seconds, it displays what you see in Figure 3.10.

Before going into detail about how the application works, there are a few things to point out:

• The application implements a Ribbon Bar showing a built-in tab (Home) that includes two default buttons: Save and Refresh. This piece of the user interface is common to all screens and can be customized by adding new buttons or new tabs via the Screen Designer or in custom code.
• There is a Menu bar that is common to all screens and that includes collapsible panels nesting common shortcuts. By default, LightSwitch creates a Tasks panel that lists available screens and that you use for navigation between screens.
• Names of items in the user interface, including data fields and shortcuts, are autogenerated and are taken from tables and screen definitions.
• The remaining client area of the application is about screens. In Figure 3.10, you see the Create New Contact screen, which you use to add a new contact. Screen navigation is organized in tabs. If you click Search Contacts in the Tasks panel, another tab shows the Search Contacts screen (see Figure 3.11).

The user interface is intelligent enough to understand that the search screen is not used for data editing, so here the Save button is not available. It is also worth mentioning that what you are now seeing on screen has been created without writing one line of code, because LightSwitch takes care of all the plumbing for you. Let’s now see how the application works by adding/editing data and displaying lists of data.

Adding and Editing Data

To add new data, you can either click Create New Contact in the Tasks panel or on the Create New Contact tab. This screen opens first because it was the first to be created. If you want to change the startup screen, you can go to the Application Properties and select the Screen Navigation tab. This feature is discussed in detail in Chapter 4.

You just fill in fields according to the information you want to add. Notice that required fields are presented in bold (such as Last Name in the current example). To fill the Picture field (and ones like it), simply pass the mouse over such a field and click the green arrow to add the picture from disk or the click the black cross to remove an existing picture from the field. Figure 3.12 shows what the screen looks like when filled with custom data.

After you have finished adding information, click Save to permanently store the information to the database. When you save your data, the application shows an edit screen for the newly added item.

The star symbol also disappears, and the tab title is replaced with the content of the Last Name field. (This automatic choice is because it was the first property added to the entity.) Finally, the Id read-only field shows the record number of the element inside the database. Figure 3.13 shows what the screen looks like after saving data.

It is worth mentioning that data is still available for editing. So, you might change your data by replacing the content of fields and then save again. In this case, a star appears inside the tab’s title, indicating some pending changes.

Adding and Formatting Phone Numbers

While entering data, you might have noticed that fields of type Phone Number were automatically formatted. The Phone Number Editor control in LightSwitch applications can parse phone numbers and present them in one of the built-in formats if they are recognized as valid; otherwise, data remains as you entered it. The default formatting can be overridden by passing the mouse over the field and clicking the down arrow on the right side of the field. This shows a group of fields that you fill with your local phone number information, as shown in Figure 3.14.

In particular, you can specify the following information:

• Country Code: The phone number prefix for your country
• Area Code: The local prefix for your area
• Local Number: The actual phone number without any prefixes
• Extension: Additional information for the phone number

After you specify such information, the Phone Number field is updated to reflect changes. Sometimes the built-in phone number formats are not enough to satisfy your requirements, especially if you do not live in the United States. Fortunately, LightSwitch enables you to add custom phone number formats and edit built-in formats, as explained in the next subsection.

Customizing Phone Number Formats

The Phone Number Editor control provides automatic phone number formatting capabilities by comparing the phone number entered by the user with one of the built-in phone number formats available for the Phone Number data type. If the phone number entered by the user matches one of the available formats, the Phone Number Editor presents the number according to this format. You can customize phone number formats by both editing built-in formats and providing new ones. To accomplish this, you need to close the application and open the Table Designer for the desired entity (Contact in the current example). Once the entity is shown in the designer, select one of the properties of type Phone Number. Continuing the current example, select the HomePhone property, and then press F4 to enable the Properties window. Figure 3.15 shows what this window looks like with regard to the selected property.

Among the available properties, you can find a shortcut named Phone Number Formats. If you click it, the Phone Number Formats dialog appears, showing all the available built-in phone number formats, as shown in Figure 3.16.

To edit an existing format, just click the box related to the format and replace it with custom information, remembering that

• The letter C represents the country code. You can enter up to three C letters for country codes requiring three numbers.
• The letter A represents area code numbers. There is basically no limit to the number of A letters.
• You can enclose letters between parentheses to provide this kind of formatting.
• The letter N represents the local number. You must specify the exact number of N letters to match a fixed phone number length. For instance, you add six N letters if you want to match a phone number exactly six characters long, but not numbers that are seven or five characters long.

You can test whether a phone number matches one of the listed formats by typing it inside the Test a Phone Number text box. This is useful to understand how formats work. You follow exactly the same rules if you want to specify a new custom format. Just click inside the Add Format field at the bottom of the list and begin writing your format by following the explanations provided in the previous bulleted list. Notice that Visual Studio LightSwitch validates your format while you write it. If it does not comply with built-in rules, LightSwitch shows validation error messages, as shown in Figure 3.17 with regard to C letters.

After you finish adding your custom phone number format, click OK. If the user enters a phone number that matches your format, it is formatted according to your rules.

Automatic Check for Pending Changes

The LightSwitch infrastructure automatically provides to applications the so-called dirty checking feature, which is the ability to check whether the user is attempting to close a screen or the application without saving pending changes (and ask for confirmation that the user really wants to do this). For example, if you are adding or editing a contact and then try to close the CreateNewContact screen before saving your changes, the application asks whether you want to save or discard changes before closing, as shown in Figure 3.18.

Similarly, users are asked for confirmation when attempting to close the application but there are some unsaved changes. It is important to underline that such a feature is implemented automatically, meaning that you do not need to enable it manually or write a single line of code.

Displaying and Searching Data

So far, you have seen how to add items to and edit items in the application’s database via the user interface of the ContactsManager application example. Now it is time to see how the application can list and search existing data via the search screen implemented earlier. Let’s suppose you have added a number of contacts to the application. Now, in the Tasks panel, click the SearchContacts element. You will get the full list of data in a tabular form, similar to what you would get in Microsoft Excel. Figure 3.19 shows an example taken from my machine, showing a list of friends of mine.

As you can see, the tabular representation shows all the available information organized in columns, one per property exposed by the Contact entity. By default, the search screen is read-only, so you cannot directly edit items inside the grid (although there are two ways to accomplish editing that are discussed later). Data is shown via a DataGrid control; and phone numbers, email addresses, and images are displayed respectively via Phone Number Viewer, Email Address Viewer, and Image Viewer controls. The search screen also offers lots of interesting built-in functionalities that the LightSwitch infrastructure offers without the need to write a single line of code, as described in the following sections.

Paging

Suppose that you have added thousands of records to your application’s database. If a search screen had to show them all, it would have to load all items in memory and then render the list to the user interface, and this would heavily affect performances. In addition, scrolling the list of records on the screen would also be slow because the user interface would refresh each time you scrolled the list. Because of this, LightSwitch applications offer a built-in paging mechanism. Thanks to paging, the application divides data into virtual pages and loads and displays 45 items at a time. For example, when you run an application that stores 100 elements, it divides the data into 3 virtual pages (45 + 45 + 10) and then it loads and displays the first 45 items. Then you can go to page 2 or 3 (and then go back) by using the DataPager control shown in Figure 3.20.

The first button on the left side of the control brings you back to the first page, and the last button on the right side of the control moves to the last page. Intermediate controls browse data by one page. Only when you click one of these buttons does the LightSwitch application load and display the corresponding number of items. This paging mechanism is a convenient way to maintain optimal performances and is something that is provided by default, without writing a single line of code. The page size is not fixed; you can replace the default value of 45 with a custom one. To do so, open the Screen Designer and select the collection in the upper-left corner (which is Contacts in the current example). Then, in the Properties window, edit the value of the No. of Items to Display per Page property.

Searching and Filtering

As its name implies, a search screen not only displays the list of items from a table, but it also provides search tools. By default, search screens in LightSwitch applications implement a search text box where you can type your search key. Then you click the button with a lens inside or you simply press Enter. For example, you might want to retrieve a specific record from the list. Figure 3.21 shows how to retrieve a contact by its last name.

You can simply return to the full list by clicking the button with a blue X near the search box. It is important to mention that the search tool filters all the items that contain the specified text in every string column. For example, if you use the “cat” search key in the sample application, the search screen returns all the items that contain the specified key, and in this case, this is true in the Last Name column, as shown in Figure 3.22.

Similarly, if you type the “de” key search, the search screen filters all the items that contain the search key in every string column that in the current example is contained in the Job Role column, as shown in Figure 3.23.

Refreshing the Search Results

Search screens provide a Refresh button on the Ribbon Bar.

You use this button to reload the full list of data, and it is useful when you add a new or edit an existing item. In fact, when you are editing items, the search results do not automatically reflect changes, so you need to refresh the list with the Refresh button. To understand how this works, follow these steps:

1. In the Tasks panel, click Create New Contact.
2. Add a new contact by specifying real or sample information, and then save your changes.
3. Return to the search screen.

At this point, you might notice that the new contact is not automatically displayed in the search results. The reason is that the screen displays a snapshot of items stored in the database at the time you executed the search, which is similar to requesting a web page in your browser.

So, click the Refresh button on the Ribbon Bar to get the list updated with the new data.

Editing Data from the Search Screen

By default, you cannot edit data directly inside cells. By the way, LightSwitch presents cells in the first column (for each row) with a hyperlink that you can click to edit the current item. This refers to the summary property of your table, which by default is the first property you added to your entity and that is used as the default column. You can change this in the Table Designer.

Continuing the previous example, the Contact column refers to the LastName property in the Contact entity, and you can click the last name of each contact to easily edit the item. Figure 3.24 shows what happens when you click the last name of a contact.

As you can see, a new tab appears containing a screen that allows editing the item you selected. Here you just make your changes and then click Save when you are done. It is worth mentioning that LightSwitch created this editing screen for you, saving you a lot of time. You can return to the search results by closing the current tab or by clicking the Search Screen tab.

Understanding Summary Properties and the Show as Link Feature

Earlier you saw how LightSwitch presents the first property added to the entity with a hyperlink in search screens. By clicking this hyperlink, you can immediately access detail properties for the selected item (see Figures 3.19, 3.22, and 3.23). In the current example, the LastName property value is presented with a hyperlink because that was the first property added to the entity. Of course, you can change the default setting, and this is an easy task. For instance, with regard of the current ContactsManager application, you might want to make the Email property the hyperlink. If you just want to change the property that is displayed as a hyperlink, in the Screen Designer you simply select the control mapped to the property, and in the Properties window you check the Show as Link check box, as shown in Figure 3.25.

Notice that selecting a new property does not automatically deselect the previous one (in this case, LastName). Therefore, LightSwitch allows you to present multiple properties as hyperlinks, but you have to manually uncheck the Show as Link check box for undesired properties. If you now run the application, you can open contact details by clicking the Email hyperlink. Using Show as Link is the simplest way possible to change the default behavior, but in some situations, this is not enough. In fact, some screens use the Summary control to display a list of items but present them via only one property. For a better understanding, consider Figure 3.26, which is taken from the sample application that will be built in Chapter 4. Notice how the Customer property shows a list of customers but only the company name is displayed. That is an example of Summary control, and the property that is displayed is referred to as a summary property.

By default, the summary property is the first property added to the entity. To change the summary property, double-click the desired table in Solution Explorer, and then in the Table Designer, click the table name. In the Properties window, you can see at this point the Summary Property field, where you can select a different entity property to identify a list of items within a Summary control. With regard to customers, you could select the email address or the name of the contact. Figure 3.27 demonstrates how to change the current summary property.

Using Controls That Support Editing

The default behavior for search screens is that they are read-only and that you cannot directly edit data within cells, but you can access the edit screen by clicking the hyperlink provided for each row. If you do not like to invoke an external screen for editing data, you can override the default behavior by changing the Use Read-Only Controls property for the screen.

To accomplish this, follow these steps:

1. Close the application if it is running.
2. In Solution Explorer, double-click the SearchContacts screen and then press F4 to enable the Properties window.
3. Uncheck the Use Read-Only Controls check box, as shown in Figure 3.28.

If you now rerun the application and open the search screen, you can click inside the cells you want to edit and type your information without opening an external screen. Figure 3.29 shows an example, where the Address property for the first contact in the list is being edited.

You can also edit email addresses, phone numbers, and images. This is because the viewer controls (for example, Image Viewer) are replaced with the editor counterparts (for example, Image Editor). Of course, you can still edit data by clicking the hyperlink in each row, which points to the edit screen for the current item. Editing data inside cells is a plus.

Exporting Data to Microsoft Excel

In most business applications, interaction with the Microsoft Office suite is a common scenario. For example, you might want to export a report to a Microsoft Excel spreadsheet, or you might want to produce letters in Microsoft Word starting from a list of customers. One goal of Visual Studio LightSwitch is to make Office integration easier. Because exporting data to Microsoft Excel is a common scenario, the LightSwitch infrastructure provides automation for this particular task from within search screens. Under the search box is an Export to Excel button, identified with the typical Excel icon. If you click this button, after a few seconds your search results are exported into a new Excel workbook, as shown in Figure 3.30.

The generated Excel workbook shows a list of columns representing exactly the columns in the Data Grid, including column headers. Below, there is the actual list of data that you can treat as you would in any other Excel spreadsheet. For example, you might want to format column headers in bold, but you can also add formulas, edit cells, and so on. Just notice that with regard to pictures, there is no Excel counterpart for the Image data type in LightSwitch, so the Picture column just reports the string representation of the .NET data type that handles images, which is [Image]. (System.Byte() is the .NET representation of the type.) Excel integration is, without a doubt, a requirement in most cases, and LightSwitch makes this easy.

Basic Screen Customizations

So far, you have generated a fully functional LightSwitch application without making any changes to the user interface. You can customize screens in a number of ways, both basic and advanced. In this chapter, you learn about basic customizations. In Chapter 4, you learn about advanced customizations.

Customizing Display Names and Descriptions

When generating screens, LightSwitch automatically provides descriptive text for controls by picking up the name of the related entity’s property. For example, you have a LastName property in the entity. When you create screens, LightSwitch generates a text box into which you can type the last name and names that text box Last Name (refer to Figure 3.10 for an example).

Properties in entities expose two particular subproperties, Name and Display Name. The first identifies the control within the application; it cannot contain blank spaces and can be changed, although it is preferable to leave the autogenerated name unchanged. The application infrastructure refers to the control via the Name property (for example, when binding the data to the control). The Display Name property refers to the text you see on the screen, so you can replace this with more meaningful content. Let’s see how to provide the CreateNewContact screen with a more meaningful user interface. Close the application, if it is running, and open the Screen Designer for the CreateNewContact screen by double-clicking it in Solution Explorer. When ready, select the top-level element named Rows Layout, Create New Contact and press F4 to enable the Properties window. Locate the Display Name property and replace its content with Add a New Contact. Figure 3.31 shows this edit.

After you change display name values, such changes are reflected in the Screen Designer, which shows the new display name for each element. At this point, you can update the user interface for any other screen in the application by following the steps described here. Another step that you can take is to add a description for each property. For example, you might want to indicate to the user how to fill in a particular field, why it is required, or any other useful information. With LightSwitch, you can provide descriptive text inside the Description property in the Properties window. (Refer to Figure 3.31 to understand how to locate it.) Text that you type inside the Description property is shown via a yellow tooltip when you click inside the related field. For example, with regard to the LastName entity’s property, add the following text inside the Description property: Required. Specifies the contact’s last name.

Customizations described in this subsection are summarized in Figure 3.29. Before running the application to see how what the user interface now looks like, however, you should replace the application’s name with a more meaningful one.

Changing the Application’s Name

When you create a new application, LightSwitch assigns the application a name that is taken from the project name. This makes sense except for the user interface. In fact, considering the current example of the ContactsManager application, you can easily see from the previous figures how the application’s window title reports ContactsManager, but a professional user interface should say Contacts Manager (with a blank space). The application’s name is an application-level setting and can be changed within the Application Designer. So, double-click Properties in Solution Explorer, and on the General tab of the Application Designer, replace the content of the Application Name box with Contacts Manager, and then save your changes.

At this point, run the application again. You can now see a more professional layout, with the window’s title and descriptions updated with more meaningful information, as shown in Figure 3.32.

Adding and Removing Data

You will sometimes need additional data on the entity side and so must add the appropriate control on the screen side to map the new property. LightSwitch makes updating the user interface really easy; you just drag and drop. For example, suppose you want to add a WebSite property to the Contact entity. To accomplish this, open the Table Designer and add a new property called WebSite of type String, marking it as not required, and then save your changes. Double-click the CreateNewContact screen in Solution Explorer so that the Screen Designer displays. On the left side of the IDE, you can see that the new WebSite property has been added to the ContactProperty item. Now click the WebSite item and drag it under the Job Role text box, as shown in Figure 3.33.

When you release the mouse button, you can see how LightSwitch adds a new TextBox control, which is data-bound to the WebSite property. This is enough to update the user interface to reflect changes to the data structure.

Repeat the same steps to update the SearchContacts search screen, dragging the WebSite property under the Job Role text box (inside the Data Grid Row element). If you now run the application, you can see how screens have been updated with the new item, which correctly accepts (or shows, in case of the search screen) the specified information, as shown in Figure 3.34.

The important thing to remember here is that you updated the user interface with a simple mouse click, without writing a single line of code to associate the new property with the appropriate text box.

Running the Application as a 3-Tier Desktop Client

When you run the application as a 3-tier client from Visual Studio LightSwitch, the ASP.NET development server is used.

Internet Information Services (IIS) is actually required only on the web server that you use for deployment, as described further in Chapter 15. As a general rule, you change the application type and deployment topology for your application in the Application Designer. So, in Solution Explorer, double-click Properties. When the Application Designer is available, select the Application Type tab on the left. Figure 3.35 shows how things look at this point.

As you can see, LightSwitch shows the list of available application types. You just need to click the desired type and nothing else. Select the Desktop client type, and then select the Host Application Services on an Internet Information Services (IIS) Service application server option type. When you build the project, Visual Studio LightSwitch generates a 3-tier application in which the middle tier is hosted by IIS and that exposes services responsible for working with data and responsible for communications between the user interface and the data. If you try to run the application, you will see no difference in how the application looks. The reason why is that this application type is, again, a desktop client, even though behind the scenes there is a middle tier working in IIS. For now, this is enough. Later in Chapter 15, when discussing deployment and installations, a complete explanation of the IIS requirement is provided.

Running the Application in the Web Browser

LightSwitch applications can run inside a web browser such as Microsoft Internet Explorer, Mozilla FireFox, or any other browser that supports Silverlight 4. This is without a doubt a great benefit because you can easily create and deploy applications that end users can use via a web interface. In addition, a 3-tier browser client means that the application is available online only, without the need of a local installation as instead happens for n-tier desktop clients. This is discussed in detail in Chapter 15. For now, let’s see how to run the application in a web browser for testing purposes. Open the Application Designer and go to the Application Type tab shown in Figure 3.32. Now simply select the Web client application type. With this simple selection, you switch to a web interface. Press F5 to run the application again and see the magic happen. The application now runs inside your default web browser and provides the same functionalities that desktop clients offer, as shown in Figure 3.36.

The program is nothing but a complete Silverlight 4 application available online only, running inside a web browser like any other Silverlight application would do, unless you turn it into an out-of-browser application. Before going on, in the Application Designer revert to the default setting, which is a 2-tier desktop client. This is the application type that is used to demonstrate other important LightSwitch built-in features, such as data validation.