Application Structure

Microsoft Silverlight will reach end of support after October 2021. Learn more.

When you create a Silverlight-based application using the managed API, the build process generates an application package. An application package is a zip file (compressed using the Deflate algorithm) that has a .xap file extension. This file typically contains your primary application assemblies and resources. It also contains a build-generated manifest that describes the application and specifies all the assemblies that it required at startup. These assemblies can be internal or external to the application package.

When you embed the Silverlight plug-in in a Web page, you specify the application package that the plug-in should download. The plug-in uses a manifest file in the application package to identify the application class to instantiate. This class is known as the entry point of your application, and it must derive from the Application class.

If you use application library caching, the manifest also indicates which required assemblies are external to the application package. The plug-in will retrieve all such files. For localized applications, the plug-in will also retrieve culture-specific satellite assemblies for all internal and external required assemblies. For more information, see Deployment and Localization.

The Application class provides a Startup event that you can handle to initialize your application and its user interface. The Application class also provides other commonly required application services. For example, you can use it to extract resource files from the application package or from downloaded zip files. For more information, see Application Services. You can also add custom application services. For more information, see Application Extension Services.

The process of downloading the application startup files and instantiating the application class is called the Silverlight activation system. The activation system enables you to specify a minimum initial download of one or more packages to optimize caching. After activation, your application can retrieve additional library assemblies and resource files on demand.

This topic describes the application package structure. It also explains the options for deploying files within the application package, as required but external parts, or as on-demand files.

For information about how to create an application, see How to: Create a New Silverlight Project. For information about hosting your application in a Web page, see Integrating Silverlight with a Web Page.

The Application Package

An application package contains the following files:

  • One AppManifest.xaml file, which identifies the packaged assemblies and the application entry point.

  • One application assembly, which includes your application class.

  • Zero or more library assemblies.

  • Zero or more loose resource files, such as images or video files.

The AppManifest.xaml file is typically generated by the build process, and uses XAML markup to declare a Deployment object for your application.

In the AppManifest.xaml file, the Deployment element includes the following attributes:

The Deployment element also includes a child Deployment.Parts property element that has a child AssemblyPart element for each assembly in the application package.

If you use application library caching, the Deployment element might also include a child Deployment.ExternalParts property element. This element is present if you have added references to library assemblies configured for use with application library caching. The Deployment.ExternalParts property element has a child ExtensionPart element for each external library package.

The application package must include an AppManifest.xaml file and an entry-point application assembly. You can deploy all other application components as in-package files, ExternalPart files, or on-demand files.

In-package files are files that you include in the application package. You typically include the primary files that your application requires at startup or must have readily available in order avoid delays after startup. You might also include shared resources, such as images, which you can embed in assemblies or provide as separate files within the application package.

ExternalPart files are zip files containing one or more assemblies required at application startup. These are typically library assemblies that are less likely to change than your primary application files. You can improve caching efficiency on user computers by factoring these into separate downloads. For more information, see How to: Use Application Library Caching.

On-demand files are files that you deploy on a server, typically in the same location as the application package. Your application can retrieve these files after activation. Depending on the file type and size, there are several options for retrieving on-demand files. For example, you can use direct URI references to retrieve image files, or you can start asynchronous downloads to retrieve library assemblies or zip files. For more information, see the following section.

The following diagram summarizes the application package structure and deployment options for your application files.

Silverlight application structure

Deploying Files In-Package, as External Parts, or On-Demand

You typically deploy all your application files within the application package until you decide that the download and startup time is unacceptable. This decision depends on your application requirements. For example, you might include as many files as possible within the application package in order to improve responsiveness after startup. In this case, you can maintain responsiveness during the initial download by providing a splash screen. For more information, see Silverlight Splash Screens.

You can reduce the size of your application package by using application library caching. However, this does not reduce your initial download time, and it can actually increase the download time due to additional network requests. The benefit of application library caching is that you can change your application code without requiring return visitors to download unchanged library assemblies.

In some cases, the Silverlight plug-in will fail to load very large application packages. When you create large applications, you should minimize the application package size by using application library caching or retrieving some files on demand.

When you decide to move some files out of the application package, you have a few options for redeployment.

The easiest files to redeploy are files that you reference using relative URIs, such as images or video files. When the Silverlight plug-in encounters a relative URI in code or XAML, it looks in the application package first. If the plug-in cannot find the file in the application package, it looks on the host server. This means that you can move any file that you reference by relative URI without requiring a code change. For more information, see Resource Files.

Many file types cannot be referenced by URI, and require special processing if you redeploy them as on-demand files. For example, if you redeploy a library assembly, you must add code that retrieves it on demand and loads it into the application domain. For more information, see How to: Load Assemblies On Demand. In this case, you must still reference the assembly in your application project, but you set the Copy Local value to False. This prevents the build from adding the assembly to the application package or requiring it at startup like an ExternalPart assembly.

You might also want to move several related resource files out of your application package, but retrieve them on demand as a single download. You can do this by bundling them into a zip file that you deploy on your server. You must then add code that retrieves the zip file on demand and extracts its contents. For more information, see Downloading Content on Demand.