The Silverlight Business Application template has good support for customization and localization of the strings presented to the user. If you crack open the AssetsResourcesApplicationStrings.resx file, you'll see that you can change key prompts, window titles, and more without altering the XAML.

Although not strictly required, when adding your own pages or prompts, a best practice is to place the text in one of the three resource files (ApplicationStrings, ErrorResources, or SecurityQuestions) rather than directly into XAML or code. Of course, you can create your own resource files if the text doesn't logically fit in one of these three.

To test the application resources approach, change the ApplicationName property to something different. I chose "Chapter 17 Example". Run it, and you'll see the changed name. It doesn't change in the designer right away; but after a build (or build and run), you'll see the title update in the designer as well. In this way, the resource files don't block your design-time experience.

How and why does this work? Open MainPage.xaml, and find the TextBlock named ApplicationNameTextBlock. Its definition looks like this:

The displayed Text value is bound to a property of the generated resource file class ApplicationStrings. The ResourceWrapper class provides a single location from which you can access all the resource classes. The resource property name is the same as that defined in the resource file. I've used traditional resource files before, and it was never this easy to get values into the UI. The power of binding in Silverlight makes using traditional resource files a no-brainer.

The client project file has a number of other differences compared to the straight navigation template. As you explore the project structure, you'll see a number of additional controls (such as the BusyIndicator), helper classes, additional views, and more. You'll run across many of them as you create your RIA Services application in the upcoming sections.

WCF RIA Services, especially through the use of the application template, makes it easy to structure a full business application, following best practices. The tooling in Visual Studio helps automatically synchronize the client and server, avoiding a cumbersome manual step.

The architecture of WCF RIA Services, although geared toward Silverlight applications, is usable by other application types as well through the server-side services. We'll leave the client project alone for a moment while we concentrate on the server (web) project in order to learn how to expose data to the application.

RIA Services can expose a read-only OData endpoint for use by any application that can speak the OData/AtomPub protocol. When creating the domain service, you were offered the option to expose an OData endpoint. For this example, you did that. That did two things:

Because the name added is OData, the service name has /OData appended to it. In this case, the service name is

http://localhost:<port>/Chapter17-Web-Services-EmployeeService.svc/OData

If you want to see metadata about the service (the OData rough equivalent of SOAP WSDL), you can append /$metadata to the endpoint name. For this service, it's as follows:

http://.../Chapter17-Web-Services-EmployeeService.svc/OData/$metadata

To access the root entities sets exposed by the domain service, you append Set to the name of the entity so Employee becomes EmployeeSet. Then, append that to the OData endpoint URL, as shown here:

http://.../Chapter17-Web-Services-EmployeeService.svc/OData/ContactSet
http://.../Chapter17-Web-Services-EmployeeService.svc/OData/EmployeeSet

Currently, accessing a single entity by ID isn't supported in the OData endpoint. With a full OData endpoint, you'd be able to do something like this:

http://.../Chapter17-Web-Services-EmployeeService.svc/OData/EmployeeSet(1)
(NOTE: this is not supported)

Figure 17.6. Data from the WCF RIA Services OData endpoint, loaded into PowerPivot for Excel 2010. PowerPivot is a C# .NET Office add-in application, by the way.

You can easily test the OData endpoint in Microsoft PowerPivot^[2] for Excel 2010 by selecting the From Data Feeds option while the application is running, and providing the full EmployeeSet or ContactSet URL. When executed, the EmployeeSet query returns the results directly into PowerPivot, as seen in figure 17.6.

OData endpoints are good for querying data on the web or using tools such as PowerPivot. Although OData could be used for Ajax applications, you'll be better served using the native JSON endpoint.

Both the JSON and SOAP endpoints require the use of assemblies in the RIA Services Toolkit, which can be installed, like all other Silverlight tools, using the Microsoft Web Platform Installer.^[3] If you performed a default Silverlight 4 tools installation with RIA Services, you have the toolkit installed. If you don't have a toolkit folder under the Program FilesMicrosoft SDKsRIA Services 1.0 folder, you can manually install the toolkit from http://silverlight.net/getstarted/riaservices/.

From the web project, you'll need to add an assembly reference to the Microsoft.ServiceModel.DomainServices.Hosting assembly in the RIA Services toolkit. Figure 17.7 shows the Add Reference dialog with the correct assembly selected.

Figure 17.7. The Add Reference dialog with the correct assembly selected to allow exposing JSON and SOAP endpoints

When the project reference is set, you'll need to modify the web.config file to add the new JSON endpoint. In the domainServicesendpoints section, where the OData endpoint also lives, add the following XML:

That configuration entry sets up a WCF endpoint using the factory included in the RIA Services toolkit DLL. When it's configured, the root URL will be, as it was in the OData case, the service name with /<endpoint>:

http://localhost:<port>/Chapter17-Web-Services-EmployeeService.svc/JSON

You can call the endpoint anything you want, as long as you use the same endpoint name in the configuration file and in the URL. By convention, you use the return type—JSON. To perform a query, use Get<EntityName>s as the format. For example:

http://.../Chapter17-Web-Services-EmployeeService.svc/Json/GetEmployees

Note that if you call that URL using Internet Explorer 8, you'll get a download error. If you use Google Chrome, or another browser or JSON tool, you'll be able to see the text of the JSON content. If you have nothing handy, create this simple HTML file (see listing 17.1) in the web the project and select View in Browser. I called mine Test-JsonEndpoint.html and used a little jQuery to handle the Ajax call.

Example 17.1. Testing the JSON endpoint from JavaScript using jQuery

This example HTML page shows how to test the retrieve method of the JSON endpoint for your RIA Services domain service class. Using the EmployeeID and Title, it creates a single list item for each employee returned in the query and then displays an alert when the query returns. Note the path used to get to the root of the results: it's the name of the query with Result appended, plus the name .RootResults. This is consistent for any RIA Services JSON get call.

jQuery^[4] makes the service call and processing simple. If you haven't yet been exposed to jQuery, definitely check it out. jQuery has been the one thing that makes JavaScript and DOM manipulation tolerable for me. It's a great library for handling on-page work, and it interacts nicely with Silverlight.

The JSON endpoint also supports updating data. For space and relevance reasons, I won't create a full update UI here, but the code is similar to any other JSON Ajax call using a POST.

JSON is great for Ajax applications, but the format itself can be limiting. Although not as rich as the WCF native formats, another widely understood format is SOAP.

Like JSON endpoints, SOAP endpoints are updatable services exposed using a service endpoint definition in the web.config. The entry to add for SOAP is

This requires the same assembly reference the JSON example required. Note that the public key token and other assembly information are identical as well.

Unlike the JSON approach, the SOAP endpoint ends up working right at the root service level. For example, to get the Web Services Description Language (WSDL) for the SOAP service in your solution, hit this URL with the browser:

http://.../Services/Chapter17-Web-Services-EmployeeService.svc?wsdl

You don't need to add /Soap to the URL.

To fully utilize the SOAP client, you'll need to add a service reference from another project and generate the client. As was the case in the JSON version, the service is read/write but doesn't expose the entity metadata to the client. To take advantage of WCF RIA Services, you'll want a full Silverlight application, aware of WCF RIA Services and aware of the metadata it uses.

Query methods are methods that return a single entity or a set of entities. The default query method generated by the template returns all instances of the entity in the data store. This allows you to further compose the query on the client with additional criteria to limit the result set.

Query methods may be indicated by convention or attribute, as shown previously. When using the attribute, you have a few options to set. These are shown in table 17.2.

Creating a query method on the service is pretty simple if you follow the naming and method signature conventions. Here's an example of one that returns only salaried employees:

public IEnumerable<Employee> GetSalariedEmployees()
{
    return from Employee emp in ObjectContext.Employees
            where emp.SalariedFlag == true
            select emp;
}

When the solution is compiled, the method is turned into a client-side method named GetSalariedEmployeesQuery on the generated EmployeeContext domain context object.

Query methods fall into three primary buckets:

The first two are easily understood, falling squarely into patterns you've used since functions were first conceptualized in computer science. The third option is a little different and provides real flexibility.

A function with an IQueryable return type returns an expression tree. This is a LINQ concept for a generic query that's to be executed by a query provider. The IQueryable interface inherits from IEnumerable, so it also represents the results of that expression tree. Even when you build the LINQ query on the client, the query itself is executed server-side, typically all the way back at the database for a provider such as the Entity Framework.

In effect, this means you can have this query method on the server

public IQueryable<Employee> GetEmployeesSorted()
{
    return from Employee emp in ObjectContext.Employees
            orderby emp.Title, emp.HireDate
            select emp;
}

and use it like this on the client:

EmployeeContext context = new EmployeeContext();

EntityQuery<Employee> query =
    from emp in context.GetEmployeesSortedQuery()
    where emp.SalariedFlag == true
    select emp;

Note that the query is composed—the server-side query and the client-side query are combined to return a set of results. That's a powerful way to provide prefiltered or presorted data to the client. For example, the query could've taken a parameter to use in the filter or used security to decide which records could be returned to the client. The query execution itself is deferred; it's not executed until the client code first accesses the result data.

We'll cover more about using the domain service query methods from the client later in this chapter. Another class of methods the service provides is for data manipulation: insert, update, and delete operations.

The generated code for the insert, update, and delete methods takes in a single entity and uses the backing data store to perform the appropriate operation. For example, the update code looks like this:

public void UpdateEmployee(Employee currentEmployee)
{
  this.ObjectContext.Employees.AttachAsModified(currentEmployee,
                    this.ChangeSet.GetOriginal(currentEmployee));
}

That tells the server-side object context to add this employee and mark it in the modified state, using the passed-in employee object as the current state and the original object as the last-known state from the data store. The Attach and AttachAsModified functions are all provided by the Entity Framework. The specific function used for your data provider may vary.

For a given entity, it's unusual to create alternate general insert, update, and delete methods. Doing so would confuse RIA services, not to mention your fellow programmers. There's one exception—the named update method.

Normally, the update methods are handled automatically based on the state of the data. But you may have situations where you need to provide a custom update method that you'll call directly rather than let Silverlight infer the update operation for a particular entity during the SubmitChanges call on the domain context.

To mark an update operation as a named update operation, it needs to have the usual update operation signature and the Update attribute with UsingCustomMethod = true. Here's an example:

[Update(UsingCustomMethod = true)]
public void SpecialCascadedUpdate(Employee emp)
{
   ...
}

This approach exists to allow you to handle special cases related to business logic or database complexities. It's still called as part of the batched SubmitChanges call. If you want to immediately execute a function, another approach is available.

CRUD methods are called as part of a batch—the entities have the CRUD operations performed on them but aren't sent to the server for the actual action until the call to SubmitChanges is made on the client.

Invoke methods are normal methods you can use to perform some sort of calculation or return a piece of data. They're operations that need to be executed without change tracking or deferred execution. Invoke methods shouldn't be used to load data; that's what query methods are intended for. Returning an entity from an Invoke method bypasses the pattern and won't cause the appropriate change tracking and entity generation to occur on the client.

Although the Invoke attribute is optional, to be considered an invoke method, a method shouldn't take entities as a parameter or return an entity, IEnumerable, or IQueryable of entities as a result.

A typical invoke method, if there could be such a thing, might look like this (example shamelessly stolen from chapter 16 on MVVM):

[Invoke()]
public int CalculateVacationBonus(DateTime hireDate)
{
  int vacationBonus;
  DateTime today = DateTime.Today;

  int yearsInService = today.Year - hireDate.Year;

  if (hireDate.AddYears(yearsInService) > today)
    yearsInService--;

  if (yearsInService < 5)
    vacationBonus = 10;
  else
    vacationBonus = 20;

  return vacationBonus;
}

It's a regular business method. Given that it's on the server, you probably have a reason— it may call another web service, or it may hit a database to do a lookup. In this case, it's on the server to illustrate the invoke type.

As mentioned, the Invoke attribute is optional. When in doubt, add the attribute to make your intentions clear. For normal CRUD methods where the name is sufficiently patterned using the naming conventions, this is usually unnecessary. But I find that Invoke methods can be ambiguous at first glance. Speaking of naming conventions, what happens when you want to avoid having them kick in?

Some of these operations require the use of attributes, but many are autogenerated via the naming conventions. If you don't want RIA Services to generate a domain method for your service method, apply the Ignore attribute to that method, as shown here:

[Ignore()]
public void UpdateEmployeeButNotReally(Employee emp)
{
...
}

With that attribute in place, despite the fact that the method uses the Update naming convention and method signature, it won't be generated as an update call on the client.

The domain service provides a number of standard method types, many of which are autogenerated from the tooling but may be modified or replaced. Domain services provide CRUD operations in the form of insert, update, delete, and query methods. In addition, arbitrary functionality may be included in invoke methods.

When discussing the IQueryable type, I sneaked an EmployeeContext object into the example. What's that, and what does it provide? That's the subject of the next section.

One way to use the domain service is to reference the client context object from code and execute queries directly against it. Because this is the most traditional way when compared to the usual pattern of working with services and WCF service proxies, I'll start with it.

In the Home.xaml.cs file, replace the OnNavigatedTo method with the following short bit of code:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    EmployeeContext context = new EmployeeContext();

    EntityQuery<Employee> query = context.GetEmployeesQuery();

    context.Load<Employee>(query);
    EmployeeGrid.ItemsSource = context.Employees;
}

When the page is navigated to, this code automatically loads all the employees and assigns that collection to the ItemsSource of a DataGrid. The EmployeeContext object, in this instance, serves as the proxy for the domain service. Note that though you don't bother to hook up a method to the Load method asynchronous return, it's still executed asynchronously, and the results appear through binding.

The query system is flexible: you could change the query to add some criteria and a sort if you wanted to. (Be sure to add using System.Linq; to the top of the code before you try to compile.)

EntityQuery<Employee> query =
    from emp in context.GetEmployeesQuery()
    where emp.SalariedFlag == true
    orderby emp.HireDate
    select emp;

This example selects all the employees that are salaried and sorts them by hire date. The query itself is executed on the server, as you learned in the previous section. When using the Entity Framework with SQL Server as you are here, the query is executed all the way back at SQL Server, and only the items matching the query are returned.

You can't test the connection without having something to bind it to. So, time for a trusty DataGrid. Replace everything else in the LayoutRoot, starting with the ScrollViewer, with this XAML:

<Grid Margin="10">
  <Grid.ColumnDefinitions>
    <ColumnDefinition Width="*" />
    <ColumnDefinition Width="350" />
  </Grid.ColumnDefinitions>

  <my:DataGrid x:Name="EmployeeGrid"
               Grid.Column="0" Margin="5" />
</Grid>

It'll be easiest if you first drag the DataGrid onto the design surface in order to set up the correct namespaces and project references. Besides, "it's not a real demo unless someone drags a DataGrid."^[5]

When you run the application, you'll get something that looks like figure 17.8.

Connecting via code allows you to better take advantage of advanced patterns such as MVVM and have complete control over the execution path. As you get more into advanced patterns, that can be a significant benefit.

Figure 17.8. The DataGrid populated using the DomainDataSource control in XAML

I'll cover the domain context class in more detail in various parts of this chapter, primarily in section 17.3 when I discuss update functionality.

There's another approach that's easier to use and includes a ton of built-in functionality. Before making up your mind which approach you want to use, look at the DomainDataSource control.

The DomainDataSource control provides an all-XAML way to interface with the domain service. I've heard this described as a bad thing, akin to wiring your UI directly to your database. I strongly disagree with that assessment, but I do agree that despite the utter simplicity of using the control, there are some drawbacks when it comes to testing, mocking, and application structure.

Before making up your mind that the control is a Bad Thing, let's look at what it can do. After all, some applications may benefit from this approach. Despite how it looks, it's not like you're binding VB3 UI controls directly to tables in an access database;^[6] there are a few layers of abstraction in between.

To use the DomainDataSource control, you'll need to add a Silverlight assembly reference to the RIA Services SDK assembly System.Windows.Controls.DomainServices. When that's done, inside the LayoutRoot Grid of /Views/Home.xaml, add the following markup:

<riaControls:DomainDataSource x:Name="DataSource"
                                AutoLoad="True"
                                QueryName="GetEmployees">
    <riaControls:DomainDataSource.DomainContext>
        <domain:EmployeeContext />
    </riaControls:DomainDataSource.DomainContext>
</riaControls:DomainDataSource>

This markup sets up a new DomainDataSource control, tells it to automatically call the query when loaded, and sets the query name to the one that loads the employee information from the domain service. For this to work, you'll also need to set up the riaControls and domain namespaces in the same XAML file. They are as follows:

The first namespace, riaControls, defines the location for the DomainDataSource control. The second defines the location for the generated domain context class: the client-side proxy for the domain service on the server.

The DataGrid then needs to be bound to the new data source. Because the data source has an assigned context object, the data itself is located in the Data property:

<my:DataGrid Grid.Column="0" Margin="5"
             ItemsSource="{Binding Data, ElementName=DataSource}" />

What you've changed on the grid is the ItemsSource. The markup here binds the DataGrid to the data property of the DomainDataSource. Because the DataGrid instance is set up by default to autogenerate columns and show all data, you'll end up with an application that looks like the previous example in figure 17.8 when run; the UI hasn't changed, just the way you get data on the client. Be sure to comment out or remove the code you previously added.

The DomainDataSource is easy to use. Although "Look ma, no code!" isn't the most important reason to pick one approach over another (and in some cases can be a reason not to pick an approach), the domain data source is powerful and flexible enough to make it a real contender for how you connect to your domain service.

One other reason I like the DomainDataSource control is because both the team and the community are working to come up with better approaches that allow using that control with a ViewModel directly. Yep, using your ViewModel while still taking advantage of most of the coolness of the DomainDataSource is on everyone's radar.

The DomainDataSource and the underlying domain context objects support updating as well as querying, of course. But before we look at that, it's worth exploring one of the more compelling reasons to use the DomainDataSource control: filtering, sorting, grouping, and paging.

Filtering is implemented via two properties on the DomainDataSource. The first is the FilterOperator, which can be And or Or and controls how the filter descriptors are combined. The second is the collection of FilterDescriptor objects named, appropriately, FilterDescriptors.

Filter descriptors are discrete filter instructions that may be combined to produce an effective filter for a query. Conceptually, they're applied like a where clause in SQL, although the actual implementation is ultimately up to how the provider implements the composed where functionality in a LINQ query. Table 17.3 shows the properties of the FilterDescriptor class.

Of these properties, the relationship Property Operator Value is the most interesting and the most relevant to filtering. A number of operators are supported, each of which is described in table 17.4.

It may seem somewhat redundant to list the descriptions for each of these values given their names, but there are three important bits of information to get from this table:

The reason for the lengthy member names is twofold: you can't have operators like >= in XAML without ugly and unreadable escaping like >=, and you need an enumeration to set the property in XAML or from code. Primarily, the list is optimized for using from XAML.

Because it's optimized for XAML, you'd think the properties would all support binding—and you'd be right. It's possible to build a complete filter expression using filters created using binding, meaning you can provide the user with a drop-down list of fields, a drop-down list of operators, and a TextBox for the value. All six properties of the FilterDescriptor class are dependency properties that support binding.

Despite the binding flexibility, you'll implement a simple filter where only the filter value itself is bound. You already have the TextBox for the value in place, so the next step is to add the associated FilterDescriptor to the DomainDataSource. This markup shows the updated filter including the descriptor and FilterOperator:

<riaControls:DomainDataSource x:Name="DataSource"
                              AutoLoad="True" FilterOperator="And"
                              QueryName="GetEmployees">
    <riaControls:DomainDataSource.DomainContext>
        <domain:EmployeeContext />
    </riaControls:DomainDataSource.DomainContext>
    <riaControls:DomainDataSource.FilterDescriptors>
        <riaControls:FilterDescriptor PropertyPath="Title"
                Operator="Contains"
                Value="{Binding Text, ElementName=FilterText}" />
    </riaControls:DomainDataSource.FilterDescriptors>
</riaControls:DomainDataSource>

This markup augments the DomainDataSource to add a FilterDescriptor. That FilterDescriptor targets the Title property of the Employee entity and checks to see that it contains (using the Contains operator) the current value in the Text property of the FilterText field on the same page.

When run, you'll have an experience like that shown in figure 17.9.

Type in the Title Contains field, and pause for a second or two. The pause will kick in the filter, executing the query on the server and displaying the results in the grid.

By adding just a few lines of XAML, you were able to add property-value filtering (which also works with sorting, grouping, and paging, as you'll see in the next sections) without having to wire up anything at the database level or even the service level. This makes sense. Like all the other features in this section, filtering should be a given for an application; there's little point in each of us implementing the same tired old filtering code again and again. The same goes for sorting, the next topic.

Figure 17.9. Filtering the results to those that contain Manager in the title. This was done entirely with the DomainDataSource and a little in-XAML binding.

The DataPager is a fully templatable control, supporting the lookless model Silverlight and WPF are famous for. In addition, the DataPager has a number of properties that control its behavior and appearance.

In addition to helpful utility properties such as CanMoveToFirstPage and CanMoveToNextPage, the DataPager includes a DisplayMode property that is used to control which buttons and boxes are shown in the UI. Table 17.5 shows the different values this property can be set to.

As you can see, the control provides a number of different paging interfaces, covering the gamut typically seen in applications and on the Web. For the ones that show page numbers, you can use the NumericButtonCount property to control how many numbers are displayed. In addition, you can use the AutoEllipsis property to display an ellipsis, rather than a number, to indicate more pages.

The DomainDataSource control makes it easy to add common data-browsing capabilities— filtering, sorting, grouping, and paging—to your applications. Combined, these are high-value, high-effort development tasks in most applications. Having the functionality built in saves you from having to reinvent the wheel or tell your customer "no" when the feature is requested (or worse, assumed).

So far, everything you've done has been with read-only data. Real applications typically need to update data as well.

To submit the changes to the server, you need to have a button wired up to the SubmitChangesCommand of the DomainDataSource. That command does the equivalent of calling SubmitChanges on the domain context from code. Place this right below the DataForm markup:

<Button x:Name="SubmitChanges"
        Grid.Column="1" Margin="5"
        HorizontalAlignment="Right" VerticalAlignment="Top"
        Height="25" Width="120"
        Command="{Binding SubmitChangesCommand, ElementName=DataSource}"
        Content="Submit Changes" />

This adds a Submit Changes button at upper right on the screen. In theory, you have a fully working application at this point; you can perform CRUD^[8] operations using the UI. Use the + button to add a new record and the - button to delete the current record. When you're finished, click the new Submit Changes button to call the SubmitChanges function behind the scenes. This function, like most everything else in the DomainDataSource control, relies on the generated domain context object. In this case, it's the EmployeeContext.

In this example, a client-side invoke operation was created for the CalculateVacationBonus function you added to the domain service. Because all network calls in Silverlight are asynchronous, you can't call the function and get the result. Instead, you need to set up a callback. For example, listing 17.2 includes the client-side code to call the CalculateVacationBonus function and do something useful with the results.

Example 17.2. Calling an invoke operation from the client

This code, from the code-behind for Home.xaml, shows how to call an invoke method. Note the parameters to the CalculateVacationBonus client-side method.

On the server, the method took only a single parameter. On the client, it takes that same parameter, plus a callback and a data item. In this case, the data item is the Employee you're working with. You use that because you need access to the Employee inside the callback method.

The callback method executes when the asynchronous call has completed. The single parameter for the callback is an InvokeOperation object with a number of properties, including the UserState and error information.

In this method, you check for an error. If there's no error, you cast the UserState back to an Employee object, check it for null, and then use the function return value (the calculated bonus) and add that to the existing vacation hours. That object is then marked as HasChanges = true on the entity. The entity is then eligible for the SubmitChanges call.

Referring back to table 17.6, you'll notice that no Insert, Update, or Delete methods were generated. Instead, those are called via SubmitChanges.

SubmitChanges is an asynchronous batching operation. It handles sending all method calls to the server, with the exception of Invoke and Query operations.

When you insert new items or delete existing items, those operations occur only on the client. When you call SubmitChanges, it loops through the entities on the client and sends to the server those entities that require a persistence operation, calling the appropriate operation for each entity.

To cancel all pending changes for the domain context, call the RejectChanges method. It reverts entities back to their previous state, removes any newly inserted items, and reinstates any deleted items.

The domain context is the client-side proxy for the domain service, as well as the container within which all instances of a given entity reside. It provides an interface for invoke operations and query operations, as well as an implicit interface to the insert, update, and delete operations through the SubmitChanges method.

The entity classes Employee and Contact both inherit from a common client-side base class that provides much of the required change-tracking and other plumbing functionality. This class is named, appropriately enough, Entity.

The DataForm labels and the DataGrid column headers have that ugly PascalCase text formatting. It'd be nicer to introduce actual spaces to make the fields more human-readable. You may even want to provide some tooltip descriptive information for certain fields.

In the EmployeeService.metadata.cs class on the server, scroll down to the Employee partial class and the nested EmployeeMetadata class within it. Find the BirthDate field, and add this attribute:

[Display(Name="Birth Date",
         Description="The date this person was born.")]
public DateTime BirthDate { get; set; }

That says to use the string "Birth Date" for column headers and field labels; and if a tooltip or other description approach is available, use this description. Figure 17.14 shows how this looks at runtime.

Figure 17.14. The Display annotation in use on the DataGrid on the left and the DataForm on the right. At lower right is the Description property in a tooltip.

As you learned in chapter 13, annotations can be used for more than display. One of the more powerful uses is for validation.

You get data type validation and the inferred validation (string length, required, and so forth) from the database for free. But you'll typically want to add your own validation to make the UI more bulletproof.

In the EmployeeService.metadata.cs class, scroll down to the Employee partial class and the nested EmployeeMetadata class within it. Find the Gender field, and add this attribute:

[RegularExpression("[MmFf]",
                   ErrorMessage="Specify (M)ale or (F)emale, please")]
public string Gender { get; set; }

Run the application, and attempt to type something else into the Gender field. The regular expression restricts the valid input choices to M, m, F, and f. The metadata entered on the server was automatically carried over to the client. If you open the Chapter17.Web.g.cs file on the client and navigate to the generated Gender property, you'll see the addition of the new attribute:

[DataMember()]
[RegularExpression("[MFmf]",
                   ErrorMessage="Specify (M)ale or (F)emale, please")]
[Required()]
[StringLength(1)]
public string Gender
...

The StringLength, Required, and DataMember attributes were previously there as part of the inferred metadata coming from the data model. ^[9]

Annotation for display and validation is a nice, easy way to add significant robustness to your classes. Because the information goes into metadata buddy classes, you don't have to worry about the autogeneration process stepping on them.

What you've seen so far is a model where the entity generated by the data access layer, typically based directly on tables or views on the database, makes its way from the database through the service to the client and into the UI. That's okay sometimes, especially when you have good mapping at the data access layer, but an additional layer of abstraction could help protect the UI from changes in the database. That layer is called a presentation model.

Because you have the same query name as you used in the EmployeeService domain service, to use the new service from the UI, you need to make only one changechange the DomainContext property of the DomainDataSource to point to the EmployeeContactContext:

<riaControls:DomainDataSource.DomainContext>
    <!--<domain:EmployeeContext />-->
    <domain:EmployeeContactContext />
</riaControls:DomainDataSource.DomainContext>

Be sure to build before making this change; otherwise, the EmployeeContactContext class won't exist on the client. Note that you didn't have to update any service references or add a new service reference—the WCF RIA Services tooling took care of that for you. That alone is worth the price of admission.

Figure 17.15. The UI using the new EmployeePresentationModel class. Note how you have fields from the contact object now available to the UI.

When you run the application, you'll see something like figure 17.15. The new UI has fewer fields and looks a lot better than what you had before.

You have a lot fewer fields in the UI now. Some, like Birth Date, which have had the Display attribute applied, have better labels and column headers. You could set the display name for the remaining ones, and the display order, as well using the same attribute. For space reasons, I didn't include the attributes in the listings here.

The presentation model approach certainly works in this situation. It's not meant just for flattening objects, although you can use it for that. It also shines in situations where you need to do joins in LINQ and combine the results into a single logical object.

Retrieval is fine for a demo, but the real test comes when you need to use this information in an update operation.

In the previous example, you saw how the code went into a file with the .shared.cs extension. That naming is a convention understood by RIA Services. Anything with a .shared.cs name is copied to the client on build as part of the code-generation process. As long as you keep the namespaces clean, this provides an easy way to share classes between the tiers.

Visual Studio has long had the capability to link source files from one project to another. As long as the contained source code (including namespace-using statements) is compatible across both projects, it'll work fine.

This is source-level sharing. I've used it with WCF applications and also when dual-targeting Silverlight and WPF. Just consider one project the master, and add the file to it. Then, choose Add Existing Item in the other project, navigate to the source, and click the Add drop-down button so you can add a link. As my favorite black-helmeted villain would say, "All too easy."

Silverlight 4 along with .NET 4 introduced another option for sharing: .NET 4 applications can add references to a Silverlight class library, as long as that class library uses only certain namespaces. The allowable references and namespaces are strict but are likely to expand over time.

I've never been a big fan of this approach, because it feels a little dirty to me. But for this type of use, it should be perfectly acceptable.

Conceptually, one of the most important pieces of business logic for any given application is often its security model. Business applications must be able to secure data and functions in a way that integrates with existing web sites and systems without requiring yet another mechanism for maintaining security for the application.

Forms-based authentication (FBA) is cookie-based authentication in ASP.NET. Almost any ASP.NET web site with an on-page login form is using a form of forms-based authentication. Rather than relying on system tokens and security credentials provided by the operating system, each site or application can store user information in a database. For the vast majority of applications running outside the firewall, this is the way security is handled.

To configure the users and roles for an application using FBA, you'll use the ASP.NET application configuration site. This site writes to the aspnetdb database (or other database if so configured) where the membership data is stored. More often than not, this database is located in the App_Data folder on the ASP.NET site.

To configure this application, select the web project and choose the ASP.NET Configuration option from the Project menu. Figure 17.18 shows the menu you'll see.

Figure 17.18. The Project menu showing the ASP.NET Configuration option selected. This is the option used to configure the authentication database. If you don't see it, make sure the right project is selected.

You can create new users through the administration site. In addition, the Silverlight Business Application template includes a self-service registration UI (which you can disable if you desire) for allowing self-registration of users. This form, shown in figure 17.19, is wired up through the UserRegistrationService on the server.

Figure 17.19. The Register dialog in the Silverlight Business Application template. For most business applications, you'll secure or eliminate this dialog.

Configuring the site and application to use FBA is a two-step process. The first step is to open the web.config file and ensure that the authentication mode is set to Forms:

<authentication mode="Forms">
  <forms name=".Chapter17_ASPXAUTH" />
</authentication>

The second step is to open App.xaml.cs and check the constructor to ensure the Authentication property of the web context is set to FormsAuthentication:

webContext.Authentication = new FormsAuthentication();

With those two options set and a user created, you're ready to try out the application. Try logging in via the link on the main page. You'll see the UI change to indicate your login name, and the credential information itself will be available throughout the application.

Although FBA is the most common form of authentication, we can't forget good old Windows authentication.

Windows authentication relies on the Windows operating system and security infrastructure to provide the appropriate authentication scheme and tokens. For behind-the-firewall systems, Windows authentication is usually the better approach because there's no separate login process. Instead, the Silverlight application participates in single sign-on (SSO) along with other applications on the client.

To configure the application to use Windows authentication, first set the authentication mode in web.config:

<authentication mode="Windows" />

Then, in the App.xaml.cs file, modify the constructor to set the authentication to Windows:

webContext.Authentication = new WindowsAuthentication();

The business application template has startup logic that attempts to automatically resolve the credentials of the signed-in user. You'll find with WindowsAuthentication that a second or two after the application launches, you're greeted with your credentials in the upper-right corner. No Login dialog required!

Regardless of which approach you use (forms or Windows), you can require authentication from code or via attributes. On a domain service, it's easy to mark a single method as requiring a valid user account by applying the RequiresAuthentication attribute:

[Insert]
[RequiresAuthentication]
public void InsertEmployee(EmployeePresentationModel employeePM)

Technically, this falls under authorization because you're granting access based on security. But the authorization system is even more powerful than this.

Although you could enable access to individual features on a user-by-user basis, role-based authorization is by far the most common way to grant access. In this model, users belong to roles, such as Manager, Administrator, or HR, and individual permissions are granted to the roles.

To enable roles in the RIA Services application, ensure that the roleManager entry in web.config is set to true:

<roleManager enabled="true" />

When that setting is confirmed and you've created some users and added them to appropriate roles, you can start to modify the application to look for those roles. The easiest and most powerful check you can make is on the service methods on the domain service. This is done via the RequiresRole attribute:

[Insert]
[RequiresRole("Manager")]
public void InsertEmployee(EmployeePresentationModel employeePM)

The RequiresRole attribute takes in one or more role names as strings. When the client attempts to access the service method, the server consults the security tokens provided and checks to see whether the user has the correct role. If the user isn't a member of that role, the service call results in an exception, which you must trap on the client.

You must handle this exception and gracefully inform the user that access isn't allowed. When using the DomainDataSource control, you do this in the LoadedData event:

private void DataSource_LoadedData(object sender, LoadedDataEventArgs e)
{
  if (e.HasError)
  {
    if (e.Error is DomainOperationException &&
        e.Error.Message.Contains("denied"))
    {
      MessageBox.Show("Insufficient permissions for operation. Nyah!");
      e.MarkErrorAsHandled();
    }
  }
}

In the case of the EmployeeContactService, you require the Manager role for both the Insert and Update methods and RequiresAuthentication for the query method. For methods tagged with RequiresRole, you don't need to also add RequiresAuthentication; it's assumed in the role check.

The second way to check for authorization is to use the client-side WebContext object. This is useful to enable/disable menu options and buttons, as well as to perform client-side checks. Don't rely on this as your only security check, though, because you always want the server to be secured.

Here's a simple security check in the code-behind:

if (WebContext.Current.User.IsInRole("Manager"))
    SubmitChanges.Visibility = Visibility.Visible;
else
    SubmitChanges.Visibility = Visibility.Collapsed;

I put this in the OnNavigatedTo handler, but that's not the best place. Instead, you want to reevaluate any UI changes like this whenever the user logs in or logs out.

WCF RIA Services makes it easy to integrate authentication and authorization into your own application. Because it builds on ASP.NET membership and security, you know it's using a well-known and time-tested approach, which is already supported by the community.