Walkthrough: Creating a Value Control Extension

Article
12/08/2014

This walkthrough demonstrates how to create a value control extension for LightSwitch. You can use a value control to display a single field of an entity on a LightSwitch screen. A value control is typically designed for use with a set of data types. For example, you can use the text box control in LightSwitch to display strings and numeric types but not binary data.

To create a value control extension, you must perform the following tasks:

Create a control extension project.
Update the control icon.
Specify supported data types.
Bind to LightSwitch data.
Allow user code to access the control.
Add read-only support.
Test the value control.

Prerequisites

Visual Studio 2013 Professional
Visual Studio 2013 SDK
LightSwitch Extensibility Toolkit for Visual Studio 2013

Create a Control Extension Project

The first step is to create a project and add a Control template.

To create an extension project

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

To choose an extension type

In Solution Explorer, open the shortcut menu for the ValueControlExtension.Lspkg project and choose Open With.
In the Open With dialog box, choose XML (Text) Editor, and then choose the OK button.
On the menu bar, choose Project, Add New Item.
In the Add New Item dialog box, choose Control.
In the Name field, enter ValueControl as the name for your extension. This name will appear in the LightSwitch screen designer.
Choose the OK button. Files will be added to several projects in your solution.

Update the Control Icon

Two image files named ValueControl.png were added to your solution: one in the ControlImages folder of the ValueControlExtension.Client.Design project and the other in the ControlImages folder of the ValueControlExtension.Design project. The image in the file is used as an icon. You can replace the default image with one that uniquely identifies your control.

To modify the icon image

In Solution Explorer, in the ControlImages folder of the ValueControlExtension.Client.Design project, open the shortcut menu for the ValueControl.png file and choose Open With.
In the Open With dialog box, select Paint and then choose the OK button.
In Paint, change the image, for example, change the color or add a shape, and then save the file and return to Visual Studio.
Choose the ValueControl.png file, and then on the menu bar, choose Edit, Copy.
Choose the ControlImages folder of the ValueControlExtension.Design project, and then on the menu bar, choose Edit, Paste. In the message that asks whether you want to replace the file, choose the Yes button.

Specify Supported Data Types

Each control has a SupportedDataTypes collection that determines which data types the control can display. You must specify this information by using the module name and the name of the data type. For business types in the same extension, you must specify only the name of the business type. You can use “:” as a shortcut for Microsoft.LightSwitch:. For a list of supported data types, see Supported Data Types for LightSwitch Extensions.

You specify only non-nullable types for SupportedDataTypes, but your control must also support the nullable versions of all data types that you do specify.

To specify the supported data types

In Solution Explorer, open the ValueControl.lsml file in the Metadata, Controls folder of the ValueControlExtension.Common project.

Locate the <Control.SupportedDataTypes> element and add the following code after the <SupportedDataType DataType=":String"/> element:

<SupportedDataType DataType=":Boolean"/>
      <SupportedDataType DataType=":Byte"/>
      <SupportedDataType DataType=":DateTime"/>
      <SupportedDataType DataType=":Decimal"/>
      <SupportedDataType DataType=":Double"/>
      <SupportedDataType DataType=":Guid"/>
      <SupportedDataType DataType=":Int16"/>
      <SupportedDataType DataType=":Int32"/>
      <SupportedDataType DataType=":Int64"/>
      <SupportedDataType DataType=":SByte"/>
      <SupportedDataType DataType=":Single"/>

For every entity field defined as any one of these data types, the ValueControl will be displayed as a choice in the screen designer.

Bind to LightSwitch Data

The underlying Silverlight control must specify how it binds to and displays data from the LightSwitch application. LightSwitch provides IContentItem as the data context for each control. This content item includes both the data to display and metadata such as properties, DisplayName, and whether data has been loaded. IContentItem also has Value and StringValue properties that contain the actual current data for the control.

Your Silverlight control must contain a reference to the LightSwitch.Presentation.Framework namespace, which provides some common building-block controls. For example, LightSwitch provides a StatesControl that you can use to display loading information and validation errors.

To bind to data

In Solution Explorer, open the ValueControl.xaml file in the Presentation, Controls folder of the ValueControlExtension.Client project.

Add the following namespace declaration after the xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"element.

xmlns:framework ="clr-namespace:Microsoft.LightSwitch.Presentation.Framework;assembly=Microsoft.LightSwitch.Client"

Replace the <TextBox Text="{Binding StringValue, Mode=TwoWay}"/>element with the following XAML.

<!-- 
    Bind two-way to StringValue, which will enable automatic conversion and validation from or to any of the supported data types,
    and will also automatically support Choice lists.
    You also bind several alignment properties, so the control will honor what the application developer sets in the property sheet.
    The tooltip is bound to the description provided by the application developer.

    We also put the TextBox inside StatesControl, so we can show loading states or errors correctly.
    -->
    <framework:StatesControl HorizontalAlignment="Stretch">
        <TextBox x:Name="TextBox" Text="{Binding StringValue, Mode=TwoWay}"
             TextAlignment="{Binding Properties[Microsoft.LightSwitch:RootControl/TextAlignment]}"
             HorizontalAlignment="Stretch"
             ToolTipService.ToolTip="{Binding Description}"/>
    </framework:StatesControl>

Binding to StringValue is recommended for controls, such as TextBox, that are meant to display multiple data types because it automatically converts data types with the best validation support. It also handles any automatic formatting, such as displaying display names in a choice list instead of values. Non-string controls, such as CheckBox, can bind to Value. The tooltip is bound to the description that the application developer specifies. TextAlignment is bound to the TextAlignment property’s value. Finally, the TextBox is put inside StatesControl so that LightSwitch will show loading and error states correctly.

Allow User Code to Access the Control

LightSwitch provides a FindControl() method that developers can use to directly access the Silverlight control from their screen code and enlist in events from the control or directly set properties on it. For this method to work, the control must specify with which internal Silverlight control the developer should interact. In general, a LightSwitch control should return a familiar Silverlight control to this method. In the StatesControl example, the developer interacts with the internal TextBox control.

To enable access to user code

In Solution Explorer, in the Presentation, Controls folder of the ValueControlExtension.Client project, open the ValueControl.xaml.vb or ValueControl.xaml.cs code-behind file.

Add the following code to implement the IContentVisual interface.

Public Partial Class ValueControl
    Inherits UserControl
    Implements IContentVisual

public partial class ValueControl : UserControl, IContentVisual

Add the implementation for the interface.
```
Public ReadOnly Property Control As Object Implements Microsoft.LightSwitch.Presentation.IContentVisual.Control
            Get
                Return Me.TextBox
            End Get
        End Property

        Public Sub Show() Implements Microsoft.LightSwitch.Presentation.IContentVisual.Show
         End Sub
```
```
object IContentVisual.Control
        {
            get { return this.TextBox; }
        }

        void IContentVisual.Show()
        {
        }
```
The implementation for the interface is usually very simple. Most controls must implement only the Control property. If a control, such as an expander, is designed to hide part of the user interface (UI), you can use the Show method to display that part.

Some controls have a more complex lifetime for their internal Silverlight controls than the control itself. For instance, a modal window control may not create the actual Silverlight window until its button is clicked. For this kind of case, you should implement INotifyControlChanged to tell LightSwitch when the internal control is available or unavailable.

Add Read-Only Support

LightSwitch developers must be able to use controls to display data that users cannot edit. In some cases, data for a control should become read-only based on which user is logged on or some other business logic on the screen. You specify the read-only state of a control by setting the value of the IsReadOnly property on the IContentItem object, which is the data context for the control.

To add read-only support

In Solution Explorer, in the Presentation, Controls folder of the ValueControlExtension.Client project, open the ValueControl.xaml file.
Add the following binding element just after the TextBox x:Name="TextBox" Text="{Binding StringValue, Mode=TwoWay}" element.
```
IsReadOnly="{Binding IsReadOnly}"
```
Depending on the control, you might require different behavior for IsReadOnly. You might have to disable some or all of the control. In the simple example of the text box, the IsReadOnly property on the IContentItem is bound to the IsReadOnly property on the text box.

At this point the value control is finished, and you can test it in LightSwitch.

Test the Value Control

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

To enable an experimental instance

In Solution Explorer, choose the BusinessTypeExtension.Vsix project.
On the menu bar, choose Project, BusinessTypeExtension.Vsix Properties.
On the Debug tab, under Start Action, choose Start external program.
Enter the path of the Visual Studio executable, devenv.exe.

By default on a 32-bit system, the path is C:\Program Files\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe; on a 64-bit system, it is C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe.
In the Command line arguments field, enter /rootsuffix Exp.

Note

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

To test the detail control

On the menu bar, choose Debug, Start Debugging. An experimental instance of Visual Studio opens.
In the New Project dialog box, expand the Visual Basic or Visual C# node, choose the LightSwitch node, and then choose the LightSwitch Desktop Application template.
In the Name field, enter ValueControlTest, and then choose the OK button to create a test project.
On the menu bar, choose Project, ValueControlTest Properties.
In the project designer, on the Extensions tab, select the ValueControlExtension check box.
Create a basic LightSwitch application that has a table that contains several fields of varying data types, including String and DateTime.
Add a List and Details screen, and then in the screen designer, change a TextBox control for one of the String fields to ValueControl.
On the menu bar, choose Debug, Start Debugging. Observe the behavior of the ValueControl control in the application and verify that the text is displayed properly.
Open the run-time screen designer and change a DateTimePicker control for one of the DateTime fields to ValueControl. Verify that the ValueControl works for the supported data types that you specified earlier.

Next Steps

This completes the value control walkthrough; you should now have a fully functioning control extension that you can reuse in any LightSwitch project. This was just one example of a value control; you might want to create a control that is significantly different in appearance or behavior. The same basic steps and principles apply to any value control, but there are other concepts that apply in other situations. For example, you might want to handle validation errors or support editing inside a DataGrid control. For more information, see Additional LightSwitch Control Concepts.

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