Application Services
Microsoft Silverlight will reach end of support after October 2021. Learn more.
When you create an application using the managed API for Silverlight, you must create a class that derives from Application. The Application class provides several services that applications commonly require. Primarily, it represents the entry point of your application code in the Silverlight plug-in life cycle.
The Silverlight plug-in life cycle begins when a user navigates to a Web page that hosts the Silverlight plug-in. If the user has installed Silverlight, the Web browser activates the plug-in and begins downloading your application package.
The plug-in loads the Silverlight core services followed by the Silverlight common language runtime (CLR), which creates an AppDomain for your application. When your application package download is complete, the CLR instantiates your Application class and raises its Startup event.
You can add code to your application class constructor. However, you typically use a Startup event handler for most application initialization tasks, such as displaying a user interface page.
The following diagram illustrates the plug-in activation process and the relationship between components in the process.
.png "Silverlight Browser Components")
For more information about the Silverlight core services and CLR, see Silverlight Architecture. For more information about the Silverlight application package, see Application Structure.
There can be only one Application instance in a Silverlight-based application. After startup, the Application instance provides several services that applications commonly require. You can access these services from any code in your application by retrieving the Application instance from the static Application.Current property.
This topic describes the following features of the Application class.
Application lifetime management.
Application resource file loading.
Unhandled exception processing.
Web host integration.
Extensibility.
Application Lifetime Management
You can add code to your application class that runs at the following points in the application lifetime:
The application class constructor.
The application Startup event.
The application Exit event.
Application Class Construction
You can add code to your application class constructor to perform basic initialization tasks, such as initializing application variables and attaching event handlers.
Most application classes are defined using XAML markup and a code-behind file. The constructor of your application class typically includes a call to an InitializeComponent method, which is responsible for merging the XAML and code-behind files. The build process generates an InitializeComponent method implementation that loads the XAML by calling the Application.LoadComponent method.
Your application XAML can specify application event handlers and populate the Application.Resources dictionary with properties and styles for use by the entire application. For more information, see Resource Dictionaries.
Application Startup
The Application.Startup event occurs when the Silverlight plug-in has finished loading your application package. At this point, all in-package assemblies have been loaded into the application domain and are available for use.
You can use the Startup event to perform common initialization tasks, such as the following:
Process data that you retrieve at startup, such as initialization and URL parameters, or data stored in a previous application session.
Display the application user interface (UI).
Begin asynchronous downloads of additional resource files or assemblies.
The following sections briefly describe how to accomplish these tasks and provide links to more information.
Processing Startup Data
To retrieve initialization parameters specified in the Silverlight plug-in configuration, use the StartupEventArgs.InitParams property. For more information, see How to: Specify and Retrieve Custom Initialization Parameters.
To retrieve URL parameters from the host Web page, use the HtmlDocument.QueryString property. You can retrieve the HtmlDocument object from the static HtmlPage.Document property. Note, however, that the Document property cannot be used if HTML access is disabled. This is typically the case when a Web page hosts a Silverlight-based application from a different domain. For more information, see Security Settings in HTML Bridge.
To retrieve data from a previous application session, use the IsolatedStorageSettings class. For more information, see How to: Store and Retrieve Application Settings Using Isolated Storage.
To make startup data available to your entire application, add it to the Application.Resources dictionary.
Displaying the User Interface
To display the application UI, set the RootVisual property in the Startup event handler.
You can only set this property one time, typically to a UserControl that provides a layout root for your UI. You can change your UI after startup by changing the contents of the root visual's layout root. For more information, see Navigation Overview.
.gif "Note") Note: |
|---|
The Startup event can occur before the host Web page completes its layout calculations. If you use relative sizing with the Silverlight plug-in, the Content.ActualHeight and ActualWidth values are not meaningful at application startup. To scale your UI or perform layout based on the current size of the plug-in, you must handle the Content.Resized event. For more information, see Silverlight Plug-in Sizing. |
Retrieving Additional Resources
To asynchronously download additional resource files or assemblies, use the WebClient class.
If the file is a zip file, you can use the Application.GetResourceStream(StreamResourceInfo, Uri) method to extract its contents after download. For more information, see Downloading Content on Demand.
If the file is an assembly, you can load it into the application's AppDomain by creating a new AssemblyPart object and calling its Load method. For more information, see How to: Load Assemblies On Demand.
Application Exit
The Application.Exit event occurs when one of the following actions takes place:
The user closes the Web page hosting the Silverlight plug-in.
The user refreshes the host Web page.
The user navigates the browser away from the host Web page.
The host Web page uses JavaScript and the HTML DOM to remove the plug-in from the page.
The user logs off or shuts down the operating system.
One common use for the Application.Exit event is to save application settings by using the IsolatedStorageSettings class. For more information, see How to: Store and Retrieve Application Settings Using Isolated Storage.
Application Resource File Loading
Silverlight provides broad support for loading resource files from an application assembly, a library assembly, an application package, and the host server. This support depends on how you configure the resource files, where you deploy them, and how you load them. For more information, see Resource Files and Application Structure.
To programmatically access raw resource files, use the Application.GetResourceStream method. This method provides overloads that enable you to extract resource files from the application package or from a zip file that you retrieve on demand. For more information, see Downloading Content on Demand and How to: Load Assemblies On Demand.
Unhandled Exception Processing
During the lifetime of your application, unanticipated situations might occur that cause the Silverlight plug-in to throw an exception. Although you can catch exceptions in your application code, you might not be able to anticipate all potential exceptions.
Unhandled exceptions will cause the Silverlight plug-in to stop running in the browser. To prevent this from occurring, handle the Application.UnhandledException event. You can use the event data to determine whether the exception is recoverable. If you can recover from the exception, set the ApplicationUnhandledExceptionEventArgs.Handled property to true.
If you do not handle the exception in your managed code, the Silverlight plug-in onError event occurs. This gives you one final opportunity to handle the exception by using JavaScript in the host Web page. The onError event provides access to plug-in error codes, which can be useful for debugging purposes. For more information, see Debugging, Error Handling, and Exceptions. For error code information, see Silverlight Plug-in Error Messages.
Host Integration
It is sometimes useful for your managed code to interact directly with the Silverlight plug-in that hosts it. For example, you might want to retrieve the initial plug-in configuration values, or enable users to display the plug-in in full-screen mode.
To retrieve an object that represents the current host plug-in, use the Application.Host property. This property returns an instance of the SilverlightHost class, which provides functionality parallel to the features described in the Silverlight Plug-in Object Reference.
Extensibility
You can add more services to an Application instance by populating its ApplicationLifetimeObjects property with application extension services. This extensibility mechanism is preferred over using framework-specific subclasses of the Application class. Application extension services enable deep integration with application lifetime events, and make it easy to use multiple extensions together. For more information, see Application Extension Services.
See Also