Export (0) Print
Expand All

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:

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

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.

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.

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.

        
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);
    }

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 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());
}

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.

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 IQueryable<Customer> GetCustomers()
{
    return this.ObjectContext.Customers;
}

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 in a LightSwitch Database.

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.

Attribute

Using this property in LightSwitch

AssociationAttribute

For one-to-many relationships, set the ThisKey property to the primary key of the entity that exists on the one side of the relationship.

For zero or one-to-many relationships, set the ThisKey property to the primary key of the entity that exists on the zero or one side of the relationship.

For one to zero-or-one relationships, set the ThisKey property to the primary key of the entity that exists on the one side of the relationship. Set the OtherKey property to the primary key of the entity that exists on the zero-to-one side of the relationship.

DisplayAttribute

In LightSwitch, use the ShortName or Name property to specify the name that you want to appear for this field. Use the Description property to specify the text that you want to appear as a tooltip when users point to a control that contains the field in a screen.

EditableAttribute

In LightSwitch, if you set the AllowEdit property to False, the ReadOnly property of the field is set to True.

EnumDataTypeAttribute

If you set the EnumType property to an enumeration, LightSwitch creates a choice list for the field by using the values of the enumeration.

KeyAttribute

In LightSwitch, use the KeyAttribute attribute if you want the field to be used as the primary key of the entity. You can specify multiple keys.

RangeAttribute

Use this attribute to set the maximum and minimum values of the field. This attribute has no effect on non-numeric data types.

RequiredAttribute

In LightSwitch, this property affects only fields that have a string type. If you set the AllowEmptyStrings property of this attribute to False, in LightSwitch, the Is Required property of the field is set to True.

ScaffoldColumnAttribute

In LightSwitch, if you set the Scaffold property to True , the Display By Default property is set to True.

StringLengthAttribute

In LightSwitch, use the MaximumLength property to set the Maximum Length property of the field.

StringLengthAttribute

In LightSwitch, if you apply this attribute, the Display by Default property of the field is set to False.

The following attributes have no effect in LightSwitch:

  • ConcurrencyCheck

  • DataType

  • DisplayColumn

  • DisplayFormat

  • FilterUIHint

  • MetadataType

  • RegularExpression

  • ScaffoldTable

  • UIHintAttribute

Show:
© 2014 Microsoft