Share via


How to: Use Application Library Caching

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

Application library caching can help improve startup performance when users revisit your Web site.

When you use application library caching, Silverlight packages some assemblies as external parts outside the application package (the .xap file). The manifest in the application package specifies the assemblies required at startup and indicates whether they are internal or external to the application package.

When a user first visits your Web page, the Silverlight plug-in downloads the application package and all required external parts. These files are added to the browser cache so that they can be reused on subsequent visits.

All downloaded files are subject to the caching configuration settings on the server and in the browser. In a typical configuration, files are downloaded only if they are not in the cache or if they are newer than the cached versions.

Library assemblies are much less likely to change than application assemblies. Therefore, it makes sense to cache them as separate files. That way, when you change your application code but not your library code, many return visitors will download only the .xap file.

Silverlight provides many libraries with the Silverlight SDK that are not part of the runtime. These libraries are pre-configured for use with application library caching. In Visual Studio, these libraries are located on the .NET tab of the Add Reference dialog box along with the runtime assemblies. You can also access them from the Silverlight SDK folder. By default, the Silverlight SDK is installed in the %ProgramFiles%\Microsoft SDKs\Silverlight folder. You can also configure your own assemblies to support application library caching.

Application library caching affects only assemblies that your application requires at startup. If your application loads some assemblies on demand, it always retrieves them from the server, and never from the browser cache.

The following procedures describe how to enable and use application library caching, and how to configure your own assemblies for caching.

To enable application library caching

  1. In Solution Explorer, select the Silverlight application project for which you want to enable library caching.

  2. On the Project menu, select project name Properties.

    The project designer appears.

  3. On the Silverlight tab, select Reduce XAP size by using application library caching.

    NoteNote:

    You cannot use application library caching and out-of-browser support in the same application. Out-of-browser applications require all startup assemblies to reside in the application package.

  4. Add a reference to a library assembly in the Silverlight SDK, or to any assembly accompanied by a valid assemblyShortName.extmap.xml mapping file.

    This causes the following actions to occur:

    • The assembly reference is added to the project with a Copy Local value of True. This value indicates that the assembly is required at startup, and is the same value that is used by in-package assemblies.

    • When you build the project, the build packages the assembly into a separate zip file and generates an ExtensionPart element in the application manifest.

    • When the Silverlight plug-in loads the application package, it checks the manifest for ExtensionPart elements, and downloads all of the corresponding files. If your application implements a splash screen, it will continue to run until all external parts are loaded.

To configure an assembly for use with application library caching

  1. Create a mapping file in the same location as your assembly. This file must have the same name as your assembly, replacing the .dll file name extension with ".extmap.xml". For example, the Silverlight SDK assembly System.Json.dll has a mapping file that is named System.Json.extmap.xml.

  2. Add configuration data to the mapping file as shown in the following example, replacing the values in the assembly element to match your assembly.

    <?xml version="1.0"?>
    <manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <assembly>
        <name>System.Json</name>
        <version>2.0.5.0</version>
        <publickeytoken>31bf3856ad364e35</publickeytoken>
        <relpath>System.Json.dll</relpath>
        <extension downloadUri="System.Json.zip" />
      </assembly>
    </manifest>
    

    The name, version, and publickeytoken elements must match the corresponding assembly metadata. The relpath element indicates the assembly file name. Finally, the extension element indicates the name of the packaged external part through the downloadUri attribute.

    The downloadUri attribute value is used to populate the ExtensionPart.Source property in the application manifest, as shown in the following manifest excerpt.

    <Deployment.ExternalParts>
      <ExtensionPart Source="System.Json.zip" />
    </Deployment.ExternalParts>
    

    If the downloadUri value is a file name, Visual Studio provides the following support when you add a reference to the assembly:

    • The build system packages the assembly into a zip file that has the specified file name. This file is copied to the output directory alongside the .xap file.

    • If you add references to more than one assembly with the same downloadUri file name, the build system compresses them all into a single zip file.

    • The .zip extension is not added automatically. Although the packaged file is a ZIP file, you can use whichever file name extensions that your server requires.

    If downloadUri is an absolute URI, the build system will not package the assembly. Instead, you are responsible for zipping the assembly and deploying it to the specified URI. This is useful for creating a single repository of libraries used by multiple applications. However, you should consider the following issues when you use an absolute downloadUri value.

    • If the URI is on a different domain than the .xap file, the domain must have a cross-domain policy file in its root folder. For more information, see HTTP Communication and Security with Silverlight.

    • Remember, a URI is a globally unique identifier and can reference a very specific assembly file. This means that you can and should use a different URI for different versions of your assemblies. Additionally, you should continue to maintain each version-specific URI and assembly that you create when you deploy new assembly versions at updated URIs. This helps avoid potential issues when a .xap file built with one version of Silverlight attempts to load a library built with another version.

To test application library caching in Visual Studio

  1. Download and install an HTTP traffic monitor such as Fiddler. This enables you to view HTTP requests and responses, and verify that cached files are not being downloaded.

  2. Turn on the following Windows features:

    • Internet Information Services (IIS)

    • IIS Metabase and IIS 6 Configuration Compatibility

    • ASP.NET

    • Windows Authentication

    IIS is required because the Visual Studio Development Server does not enable caching in its HTTP response headers.

  3. Run Visual Studio in the context of an administrator account.

  4. In the solution that contains your Silverlight project, include a Web project for testing.

  5. Configure the Web project to use IIS and enable localhost monitoring from the HTTP traffic monitor. (For example, Fiddler provides a proxy URL that you can use to replace "localhost" in a Start URL value.)

  6. Perform the following actions and observe the resulting HTTP traffic:

    • Run your application in Visual Studio.

    • Press F5 in the browser to reload the page.

    • Open the page's URL in another browser window.

    • Rebuild the solution in Visual Studio and then reload the page in the browser.

    After the initial download, additional requests for the application package and library files do not generate additional download traffic. Instead, the requests are fulfilled by the cached copies. However, when you rebuild the application, the changes are detected and new copies are downloaded.