How to: Configure Client Application Services

This topic describes how to use the Visual Studio Project Designer to enable and configure client application services. You can use client application services to validate users and retrieve user roles and settings from an existing ASP.NET AJAX application service. After configuration, you can access the enabled services in your application code as described in Client Application Services Overview. For more information about the ASP.NET AJAX application services, see ASP.NET Application Services Overview.

You can enable and configure client application services on the Services page of the Project Designer. The Services page updates values in your project's App.config file. To access the Project Designer, use the Properties command on the Project menu. For more information about the Services page, see Services Page, Project Designer. For more information about the Project Designer, see Introduction to the Project Designer.

The following procedure describes how to perform basic configuration for client application services. Advanced configuration options are described in later sections.

To configure client application services

1. In Solution Explorer, select a project node and then on the Project menu, click Properties.

   The Project Designer appears.

2. Click the Services tab. The Services page appears, as shown in the following illustration.

   

3. On the Services page, select Enable client application services.

   Note

   Client application services require the full .NET Framework, and are not supported with the framework client profile. If the Enable client application services check box is disabled, clear the Client-only Framework subset checkbox on the Application page of the Project Designer.

4. Select Use Forms authentication if you plan to provide your own login controls or dialog box, or select Use Windows authentication to use the identity supplied by the operating system. For more information, see Client Application Services Overview.

   Note

   If you select Use Windows authentication, client application services will automatically be configured to use a SQL Server Compact Edition version 3.5 database. This is indicated in the Advanced Settings for Services dialog box as described in the next section. If you then select Use Forms authentication, the Use custom connection string setting will not be cleared automatically. This could result in errors if the SQL Server Compact 3.5 database has already been generated for use with Windows authentication. To fix these errors, clear the Use custom connection string setting in the Advanced Settings for Services dialog box.

5. If you selected Use Forms authentication, in the Authentication service location box, specify the URL of the service host, not including the file name. The designer will automatically append the standard file name (Authentication_JSON_AppService.axd) when it writes the value to the configuration file.

6. Optionally, if you selected Use Forms authentication, you can specify a value in the Credentials provider box. The credentials provider must implement the IClientFormsAuthenticationCredentialsProvider interface. By using a credentials provider, you can separate your login user interface from your other application code. This enables you to create a single login dialog box for use in multiple applications. For more information, see How to: Implement User Login with Client Application Services.

   If you specify a credentials provider, you must specify it as an assembly-qualified type name. For more information, see Type.AssemblyQualifiedName and Assembly Names. In its simplest form, an assembly-qualified type name looks similar to the following example:

   MyNamespace.MyLoginClass, MyAssembly
   

7. In the Roles service location and Web settings service location text boxes, specify the service location for each service, not including the file name. The designer will automatically append the standard file names (Role_JSON_AppService.axd and Profile_JSON_AppService.axd) when it writes the value to the configuration file.

8. Optionally, click Advanced to modify advanced settings, such as the local caching behavior. For more information, see the next procedure.

Advanced Configuration

The following procedures describe how to configure client application services for less common scenarios. For example, you can use these configuration options for applications deployed in public locations, or to use an encrypted SQL Server Compact Edition version 3.5 database as the local data cache.

To configure advanced settings for client application services

1. On the Services page of the Project Designer, click Advanced.

   The Advanced Settings for Services dialog box appears, as shown in the following illustration. For more information about this dialog box, see Advanced Settings for Services Dialog Box.

   

2. Select or clear Save password hash locally to enable offline login. When you select this option, an encrypted form of the user's password will be cached locally. This is useful if you implement offline mode for your application. With this option selected, you can validate users even when the IsOffline property has been set to true. For more information about offline mode, see How to: Work Offline with Client Application Services.

3. Select or clear Require users to log on again whenever the server cookie expires. The authentication cookie is configured on the remote service, and indicates how long a user's login will remain active. For more information about how to configure the cookie, see the timeout attribute in forms Element for authentication (ASP.NET Settings Schema).

   If you select this option, attempting to access the remote roles or Web settings services after the authentication cookie has expired will throw a WebException. You can handle this exception and display a login dialog box to revalidate users. For an example of this behavior, see Walkthrough: Using Client Application Services. This option is useful for applications deployed in public locations to make sure that users who leave the application running after use will not remain authenticated indefinitely.

   If you clear this option and attempt to access the remote services after the authentication cookie has expired, users will be revalidated automatically.

4. Specify a value for Role service cache timeout. Set this time interval to a small value when roles are updated frequently or to a larger value when roles are updated infrequently. If you implement offline mode, set the time interval to a large value to prevent the role information from expiring while the application is offline.

   The role provider accesses the cached role values or the roles service when you call the IsInRole method. To programmatically reset the cache and force this method to access the remote service, call the ResetCache method.

5. Select or clear Use custom connection string. For more information, see the next procedure.

To configure client application services to use a database for the local cache

1. On the Services page of the Project Designer, click Advanced.

   The Advanced Settings for Services dialog box appears.

2. Select Use custom connection string.

   The default value of Data Source = |SQL/CE| appears in the text box.

3. To generate and use a SQL Server Compact Edition version 3.5 database, keep the default connection string value. Visual Studio will generate a database file and put it in the directory indicated by the Application.UserAppDataPath property.

4. To generate and use an encrypted SQL Server Compact 3.5 database, add password and encrypt database values to the connection string as shown in the following example.

   Note

   Be sure to specify a strong password. You cannot change the password after the database is generated.

   Data Source = |SQL/CE|;password=<password>;encrypt database=true
   

5. To use your own SQL Server database, specify your own connection string. For information about valid connection string formats, see the SQL Server documentation. This database is not generated automatically. The connection string must refer to an existing database that you can create using the following SQL statements.

   CREATE TABLE ApplicationProperties (PropertyName nvarchar(256),
       PropertyValue nvarchar(256))
   CREATE TABLE UserProperties (PropertyName nvarchar(256),
       PropertyValue nvarchar(256))
   CREATE TABLE Roles (UserName nvarchar(256), 
       RoleName nvarchar(256))
   CREATE TABLE Settings (PropertyName nvarchar(256), 
       PropertyStoredAs nvarchar(1), PropertyValue nvarchar(2048))
   

Using Custom Providers

By default, the client application services feature uses the providers in the System.Web.ClientServices.Providers namespace. When you configure your application by using the Services page of the Project Designer, references to these providers are added to your App.config file. These default providers access corresponding providers on the server. Web services are often configured to access user data through providers such as SqlMembershipProvider and SqlRoleProvider.

If you want to use custom service providers, you will typically change the providers on the server side so that they affect all client applications that access the server. However, you do have the option of using non-default providers on the client side. You can specify custom authentication or roles providers in your project's App.config file, as shown in the following procedure. For information about how to create custom authentication and role providers, see Implementing a Membership Provider and Implementing a Role Provider. You can also use a custom settings provider by modifying your project's Settings class (accessed as Properties.Settings.Default in C# and My.Settings in Visual Basic). For more information, see Application Settings Architecture.

To configure client application services to use non-default providers

1. To use a non-default authentication or roles service provider, first complete all other configuration settings by using the Services page.

2. Close the Project Designer. This is necessary because the Services page will automatically update your App.config file even if you do not modify any settings. If you manually modify your App.config file as described in this procedure and then return to the Services page, your modifications will be reset.

3. In Solution Explorer, double-click App.config.

   The application configuration file opens in the text editor.

4. Find the <providers> element within the <membership> or <roleManager> element. These elements are children of the <system.web> element. The <membership> element is used to specify authentication providers, and the <roleManager> element is used to specify role providers.

5. Add an <add> element as a child of the <providers> element. You must specify name and type attributes as shown in the following example. The type attribute value must be an assembly-qualified type name. For more information, see Type.AssemblyQualifiedName and Assembly Names.

   <add name="MyCustomRoleProvider" type="MyNamespace.MyRoleProvider, MyAssembly" />
   

6. Modify the defaultProvider attribute of the <membership> or <roleManager> element to specify the name value from the <add> element that you added in the previous step.

   <roleManager enabled="true" defaultProvider="MyCustomRoleProvider">
   

See Also

Tasks

How to: Implement User Login with Client Application Services

How to: Work Offline with Client Application Services

Walkthrough: Using Client Application Services

Concepts

Client Application Services Overview

Introduction to the Project Designer

Implementing a Membership Provider

Implementing a Role Provider

Application Settings Architecture

Reference

Services Page, Project Designer

Advanced Settings for Services Dialog Box

Other Resources

Client Application Services

Creating and Configuring the Application Services Database for SQL Server