Client Application Services Overview
Client application services provide simplified access to ASP.NET AJAX login, roles, and profile services from Windows Forms and Windows Presentation Foundation (WPF) applications. ASP.NET AJAX application services are included in the Microsoft ASP.NET 2.0 AJAX Extensions, which is included with Visual Studio 2008 and the .NET Framework version 3.5. These services enable multiple Web and Windows-based applications to share user information and user-management functionality from a single server.
Client application services include client service providers that plug into the Web services extensibility model to enable the following features for Windows-based applications:
Simple client configuration. You can enable and configure the login, roles, and profile services by using the Visual Studio project designer or by specifying client service providers in your project's App.config file. For more information, see How to: Configure Client Application Services.
Simple programmability. After you have enabled and configured client application services, you can access the service providers indirectly through existing .NET Framework 2.0 membership, roles, and application settings classes. You can also directly access the .NET Framework version 3.5 classes that implement client application services. However, in most cases, direct access is unnecessary. For more information about the client application services classes, see the "Client Application Services Classes" section of this topic.
Offline support. Windows-based applications often have to operate in occasionally connected environments. When your application is online, the client service providers will cache values retrieved from the server for use when the application is offline. For more information, see How to: Work Offline with Client Application Services.
Integration with the Visual Studio application settings designer. When you add settings to your project in Visual Studio, you can specify which settings are to be accessed through the client settings service provider.
The following sections describe these features in more detail. For more information about the ASP.NET AJAX application services, see ASP.NET Application Services Overview.
Authentication
You can use client application services to validate a user through an existing ASP.NET AJAX authentication service. You can validate a user by using Windows or forms authentication. Windows authentication means that the user identity is the one supplied by the operating system when a user logs on to a computer or domain. You will typically use Windows authentication with an application deployed on a corporate intranet. Forms authentication means that you must include login controls in your application and pass the acquired credentials to the authentication provider. You will typically use forms authentication with an application deployed on the Internet.
To validate a user, you call the static Membership.ValidateUser method. This method accesses the client service provider configured for your application and returns a Boolean value indicating whether the user is valid. For more information, see How to: Implement User Login with Client Application Services.
When using Windows authentication, you must pass empty strings or null as the parameters of the ValidateUser method. When using Windows authentication, this method call will always return true.
With forms authentication, the ValidateUser method will return a value indicating whether the remote service has authenticated the user. If validation is successful, an authentication cookie is stored on the local hard disk. This cookie is used to confirm validation when accessing the roles and settings services.
When using forms authentication, you can pass a user name and password to the ValidateUser method. You can also pass empty strings or null as the parameters to use a credentials provider. A credentials provider is a class that you provide and specify in your application configuration. A credentials provider class must implement the IClientFormsAuthenticationCredentialsProvider interface, which has a single method named GetCredentials. Using a credentials provider enables you to share a single login dialog box among multiple applications. For more information, see How to: Configure Client Application Services.
When you configure your application to use a credentials provider with forms authentication, you must pass empty strings or null as the parameters of the ValidateUser method. The service provider will then call your IClientFormsAuthenticationCredentialsProvider.GetCredentials method implementation. Typically, you will implement this method to display a dialog box and return a populated ClientFormsAuthenticationCredentials object.
For more information about authentication, see ASP.NET Authentication. For information about how to set up the ASP.NET AJAX authentication service, see Using Forms Authentication with ASP.NET AJAX.
Roles
You can use client application services to retrieve role information from an existing ASP.NET AJAX roles service. To determine whether the current, authenticated user is in a particular role, you call the IsInRole method of the IPrincipal reference retrieved from the static Thread.CurrentPrincipal property. The IsInRole method takes the role name as a parameter and returns a Boolean value indicating whether the current user is in the specified role. This method will return false if the user is not authenticated or is not in the specified role.
For more information, see How to: Access User Roles with Client Application Services. For information about how to set up the ASP.NET AJAX roles service, see Using Roles Information with ASP.NET AJAX.
Settings
You can use client application services to retrieve user application settings from an existing ASP.NET AJAX profile service. The client application services Web settings feature integrates with the application settings feature provided in .NET Framework 2.0. To retrieve Web settings, first generate a Settings class (accessed as Properties.Settings.Default in C# and My.Settings in Visual Basic) for your project by using the Settings tab of the Visual Studio project designer. On the Settings tab, you can use the Load Web Settings button to retrieve Web settings and add them to the generated Settings class. You can use Web settings configured for use by all authenticated users or by all anonymous users.
For more information, see How to: Access User Settings with Client Application Services. For more information about application settings, see Application Settings Overview. For information about how to implement your own settings class instead of generating one in Visual Studio, see How to: Create Application Settings. For information about how to set up the ASP.NET AJAX profile service, see Using Profile Information with ASP.NET AJAX.
Client Application Services Classes
The following table describes the classes that implement the client application services feature.
Applications that use only the primary authentication, roles, and settings features will not have to access these classes directly. Instead, such applications will access the client application service providers indirectly using application configuration and the APIs described in the previous sections. You will access these classes directly to implement additional features, such as user logout and offline capability.
Note
All client application services APIs are synchronous. Client application services do not directly support asynchronous behavior.
The client application service providers implement or extend standard .NET Framework 2.0 types, but do not implement every member and feature defined by these types. For example, you cannot use the client application service providers to implement a user-management application for creating new users and managing role membership. To implement this functionality, you must currently use a Web application and server-side code. To determine which members are not implemented, see the reference documentation, which you can access from the links in this table.
Class |
Description |
|---|---|
This class manages the user identity and authentication cookies for forms authentication. The primary reason to access this class directly is to call the RevalidateUser method, which silently revalidates a user (for example, when switching from offline to online mode). After the user is authenticated using forms authentication, you can retrieve an instance of this class through the Identity property of the IPrincipal reference retrieved through the static Thread.CurrentPrincipal property. |
|
This class manages the user roles. This class does not have any members that cannot be accessed indirectly. However, after the user is authenticated, you can access an instance of this class through the static Thread.CurrentPrincipal property. |
|
This class provides the static IsOffline property that you use to switch your application to offline mode. For more information, see How to: Work Offline with Client Application Services. |
|
This class represents user credentials. You will use this class only as the return value type of the GetCredentials method when you implement the IClientFormsAuthenticationCredentialsProvider interface. |
|
This class manages access to the remote authentication service for forms authentication. The primary reason to access this class directly is to use its Logout and UserValidated members, which are not implemented by the base MembershipProvider class. You can also set the service location programmatically by using the ServiceUri property. You can retrieve an instance of this class through the static Membership.Provider property. |
|
This class manages Windows authentication. The primary reason to access this class directly is to call its Logout method. After logout, the user will still be authenticated for Windows, but will be unable to access the remote application services. You can retrieve an instance of this class through the static Membership.Provider property. |
|
This class manages access to the remote roles service. The primary reason to access this class is to call its ResetCache method. This can be useful if your application is configured to use a non-zero role service cache time-out value. For more information, see How to: Configure Client Application Services. You can also set the service location programmatically by using the ServiceUri property. You can retrieve an instance of this class through the static Roles.Provider property. |
|
This class manages access to the remote Web settings service. The primary reason to access this class is to handle the SettingsSaved event. You can also set the service location programmatically by using the ServiceUri property. |
|
This interface provides an indirect way for your application to acquire user credentials for validation, as described earlier in the Authentication section of this topic. For more information, see How to: Configure Client Application Services. |
|
This class provides a FailedSettingsList property for use within a ClientSettingsProvider.SettingsSaved event handler. |
|
This class provides a UserName property for use within a UserValidated event handler. |
See Also
Tasks
How to: Configure Client Application Services
How to: Implement User Login with Client Application Services
How to: Access User Roles with Client Application Services
How to: Access User Settings with Client Application Services
How to: Work Offline with Client Application Services
Walkthrough: Using Client Application Services
Concepts
ASP.NET Application Services Overview
Using Forms Authentication with ASP.NET AJAX
Using Roles Information with ASP.NET AJAX
Using Profile Information with ASP.NET AJAX
Other Resources
Managing Authorization Using Roles
Creating and Configuring the Application Services Database for SQL Server