Guidelines for Creating WCF RIA Services for LightSwitch

This topic provides guidelines for creating and consuming Windows Communication Foundation (WCF) Rich Internet Application (RIA) services in a LightSwitch-based application. This topic provides information about the following tasks:

• Storing, retrieving, and consuming connection strings in the domain service class of a WCF RIA service

• Defining query methods for use in a LightSwitch-based application

• Applying attributes to the fields of an entity

For more general information about designing WCF RIA services, see WCF RIA Services.

Storing, Retrieving, and Consuming Connection Strings

To connect to data from within the domain service class of a WCF RIA service, your code must pass a connection string to the data source provider. Developers who consume the service can store the connection string in the web.config file of the LightSwitch application when they connect to the service. In the domain service class of your WCF RIA service, your code can retrieve and consume the connection string.

Storing the Connection String

Developers provide a data source connection string when they connect to your WCF RIA service in LightSwitch. The connection string is saved to the web.config file of the LightSwitch application. For more information, see How to: Connect to Data.

To help developers provide the correct connection string, you can provide helpful text that describes the expected format of the string. This text appears in the Connection String box of the Attach Data Source Wizard. To provide this text, add a DescriptionAttribute attribute to the top of the domain service class.

Retrieving the Connection String

In the domain service class of your WCF RIA service, your code can retrieve the connection string from the web.config file by referring to the fully qualified name of the domain service class (for example, CustomerNamespace.CustomerService). The following example retrieves a connection string by overriding the Initialize method of the domain service class. If no connection string is found, a hard-coded connection string is used.

Public Overrides Sub Initialize _
    (context As System.ServiceModel.DomainServices.Server.DomainServiceContext)
    
    If (WebConfigurationManager.ConnectionStrings.Item(Me.[GetType]().FullName) _
        Is Nothing) OrElse [String].IsNullOrWhiteSpace _
    (WebConfigurationManager.ConnectionStrings.Item _
     (Me.[GetType]().FullName).ConnectionString) Then
        
        _connectionString = "data source=NorthwindDB;initial catalog= " _
            & "Northwind;user id=myID;password=myPassword"
    Else
        _connectionString = WebConfigurationManager.ConnectionStrings.Item _
            (Me.[GetType]().FullName).ConnectionString
    End If

    MyBase.Initialize(context)
End Sub

        
string _connectionString;
public override void Initialize
    (System.ServiceModel.DomainServices.Server.DomainServiceContext context)
    {
        if ((WebConfigurationManager.ConnectionStrings
            [(this.GetType().FullName)] == null) || 
            String.IsNullOrWhiteSpace(WebConfigurationManager.ConnectionStrings
            [this.GetType().FullName].ConnectionString))
        {
            _connectionString = "data source=NorthwindDB;initial catalog= " + 
                "Northwind;user id=myID;password=myPassword";
        }
        else
        {
            _connectionString = WebConfigurationManager.ConnectionStrings
                [this.GetType().FullName].ConnectionString;
        }
        base.Initialize(context);
    }

Consuming the Connection String

In the domain service class, you can use the connection string to connect to data in any way that you want. However, some technologies in Visual Studio require that you use the connection string in specific ways. For example, if you generate the entities in your service by using an ADO.NET Entity Data Model, your code must return the connection string in the CreateObjectContext method. The following example is based on a scenario in which you have used an ADO.NET Entity Data Model to generate the entities provided by your service. This example overrides the CreateObjectContext method and returns the connection string to the Entity Framework provider.

Protected Overrides Function CreateObjectContext() As NorthwindEntities
    Dim Connection As New EntityConnectionStringBuilder()
    Connection.ProviderConnectionString = _connectionString
    Connection.Provider = "System.Data.SqlClient"
    Connection.Metadata = "res://*/NorthwindModel.csdl|" & _
                 "res://*/NorthwindModel.ssdl|" & _
                 "res://*/NorthwindModel.msl"

    Return New NorthwindEntities(Connection.ToString)
End Function

protected override NorthwindEntities2 CreateObjectContext()
{
    EntityConnectionStringBuilder Connection = new EntityConnectionStringBuilder();
    Connection.ProviderConnectionString = _connectionString;
    Connection.Provider = "System.Data.SqlClient";
    Connection.Metadata = "res://*/NorthwindModel.csdl|" +
                 "res://*/NorthwindModel.ssdl|" +
                 "res://*/NorthwindModel.msl";
    return new NorthwindEntities2(Connection.ToString());
}

Defining Query Methods That Are Consumed in LightSwitch

For each entity in your domain service class, you must identify a default method that LightSwitch can use to return a collection of entities. You can also define other methods that return data.

Identifying a Query Method That LightSwitch Uses by Default

All entities in LightSwitch have at least one method that returns a collection. This method appears in LightSwitch and enables developers to create screens that show lists of information such as customers or orders. You must identify which method you want LightSwitch to use as the default collection method for any given entity in your domain service class. To identify this method, apply the QueryAttribute attribute to the method. Set the IsDefault property of the QueryAttribute to True. This method must return either an IEnumerable<T> or an IQueryable<T> of the entity type. The collection returned by the method must contain all of the fields of the entity. The query must not accept any parameters. The following example applies the QueryAttribute attribute to the GetCustomers query method of the Customers entity.

<Query(IsDefault:=True)> _
Public Function GetCustomers() As IQueryable(Of Customer)
    Return Me.ObjectContext.Customers
End Function

[Query(IsDefault=true)]
public IQueryable<Customer> GetCustomers()
{
    return this.ObjectContext.Customers;
}

Creating Other Query Methods

You can create as many query methods as you want. Each query method can return one or more entities based on custom logic that you add to the method. In LightSwitch, you can run these methods in your business logic or use them to show data in a screen. Query methods must return an entity type, or an IEnumerable<T> or IQueryable<T> of an entity type. Method parameters must be nullable and simple types that are supported by LightSwitch. For more information about nullable types, see Nullable Value Types (Visual Basic) or Nullable Types (C# Programming Guide). For more information about simple types that are supported in LightSwitch, see How to: Define Data Fields.

Applying Attributes to Entity Fields

You can apply attributes to the fields of entities in your domain service class. The following table provides guidance on how to use attributes to achieve the effect that you want in LightSwitch.

The following attributes have no effect in LightSwitch:

• ConcurrencyCheck

• DataType

• DisplayColumn

• DisplayFormat

• FilterUIHint

• MetadataType

• RegularExpression

• ScaffoldTable

• UIHintAttribute