Configuration

At a minimum, you need to specify the following in your web.config:
  • The handler
<!-- ** Section for using IIS 6 -->
<httpHandlers>
  <add verb="*" path="DependencyHandler.axd" type="ClientDependency.Core.CompositeFiles.CompositeDependencyHandler, ClientDependency.Core "/>
</httpHandlers>

<!-- ** Section for using IIS 7 -->
<system.webServer>
  <validation validateIntegratedModeConfiguration="false"/>    
  <handlers>
    <remove name="DependencyHandler"/>
    <add name="DependencyHandler" preCondition="integratedMode" verb="*" path="DependencyHandler.axd" type="ClientDependency.Core.CompositeFiles.CompositeDependencyHandler, ClientDependency.Core "/>
  </handlers>
</system.webServer>
  • The module
<!-- ** Section for using IIS 6 -->
<httpModules>
  <add name="ClientDependencyModule" type="ClientDependency.Core.Module.ClientDependencyModule, ClientDependency.Core"/>
</httpModules>

<!-- ** Section for using IIS 7 -->
<system.webServer>
  <validation validateIntegratedModeConfiguration="false"/>
  <modules runAllManagedModulesForAllRequests="true">      
    <remove name="ClientDependencyModule"/>
    <add name="ClientDependencyModule" type="ClientDependency.Core.Module.ClientDependencyModule, ClientDependency.Core"/>
  </modules>   
</system.webServer>


You don't actually have to specify any ClientDependency configuration as it will just run with pre-defined defaults which should work for most website implementations. However, you can change the defaults by adjusting the configuration as necessary.

This is the configuration section block. This specifies the default providers to use for registering providers as well as the default provider used to combine/compress/minify your JavaScript & CSS files. The core library ships with all providers specified in this configuration block. See below for details about each one.

<!--
Customize the configuration section as required, it is optional,
when it is not specified the defaults will be loaded. YOU DONT NEED
TO SPECIFY ALL OF THIS CONFIG, THE MINIMUM IS JUST THIS:
<clientDependency version="1" />

Each section is optional, so if you're not using Mvc, you don't need
that section and if you're not using Web Forms, you don't need the 
fileRegistration section.
Composite files are used for both types of projects.

** IMPORTANT: If you're web.config setting: compilation debug="true" is set to 'true', then composite files will NOT be enabled no matter what
-->
<clientDependency version="76" fileDependencyExtensions=".js,.css">
  <!-- 
    This section is used for Web Forms only, the enableCompositeFiles="true" is optional and by default is set to true.
    The PlaceHolderProvider is set to default, the javascriptPlaceHolderId, cssPlaceHolderId attributes are optional and default to what is listed below. If using
    this provider, then you must specify both PlaceHolder controls on your page in order to render the JS/CSS.
  -->
  <fileRegistration defaultProvider="PlaceHolderProvider">
    <providers>
      <add name="PageHeaderProvider" type="ClientDependency.Core.FileRegistration.Providers.PageHeaderProvider, ClientDependency.Core" enableCompositeFiles="true"/>
      <add name="LazyLoadProvider" type="ClientDependency.Core.FileRegistration.Providers.LazyLoadProvider, ClientDependency.Core" enableCompositeFiles="true"/>
      <add name="LoaderControlProvider" type="ClientDependency.Core.FileRegistration.Providers.LoaderControlProvider, ClientDependency.Core" enableCompositeFiles="true"/>
      <add name="PlaceHolderProvider" type="ClientDependency.Core.FileRegistration.Providers.PlaceHolderProvider, ClientDependency.Core" enableCompositeFiles="true" javascriptPlaceHolderId="JavaScriptPlaceHolder" cssPlaceHolderId="CssPlaceHolder"/>
    </providers>
  </fileRegistration>
  <!-- This section is used for MVC only -->
  <mvc defaultRenderer="StandardRenderer">
    <renderers>
      <add name="StandardRenderer" type="ClientDependency.Core.FileRegistration.Providers.StandardRenderer, ClientDependency.Core" enableCompositeFiles="true"/>
      <add name="LazyLoadRenderer" type="ClientDependency.Core.FileRegistration.Providers.LazyLoadRenderer, ClientDependency.Core" enableCompositeFiles="true"/>
    </renderers>  
  </mvc>
  <!-- 
The composite file section configures the compression/combination/minification of files.
You can enable/disable minification of either JS/CSS files and you can enable/disable the 
persistence of composite files. By default, minification and persistence is enabled. Persisting files
means that the system is going to save the output of the compressed/combined/minified files
to disk so that on any subsequent request (when output cache expires) that these files don't have
to be recreated again and will be based on the persisted file on disk. This saves on processing time.
-->
  <compositeFiles defaultFileProcessingProvider="CompositeFileProcessor" compositeFileHandlerPath="~/DependencyHandler.axd">
    <!--
    File processing providers perform the file combination, compression and storage.
    Generally there would be no reason to replace.
    NOTE: The pathUrlFormat is much nicer as {dependencyId}.{version}.{type} which is the default,
    however, it is specified below with '/' as the delimiter to demonstrate using it with Cassini
    since Cassini does not support '.' chars in the path.
    --> 
    <fileProcessingProviders>
      <add name="CompositeFileProcessor"
            type="ClientDependency.Core.CompositeFiles.Providers.CompositeFileProcessingProvider, ClientDependency.Core" 
            enableCssMinify="false" 
            enableJsMinify="false" 
            persistFiles="true"     
            compositeFilePath="~/App_Data/ClientDependency" 
            bundleDomains="localhost:54153" 
            urlType="MappedId"
            pathUrlFormat="{dependencyId}/{version}/{type}"/>
    </fileProcessingProviders>
    <!-- 
    A file map provider stores references to dependency files by an id to be used in the handler URL when using the MappedId Url type
    -->
    <fileMapProviders>
      <add name="XmlFileMap" 
            type="ClientDependency.Core.CompositeFiles.Providers.XmlFileMapper, ClientDependency.Core" 
            mapPath="~/App_Data/ClientDependency"/>
    </fileMapProviders>
    <!-- 
  Defines the mime types to compress when requested by the client.
  Path is a regex selector, or a * can be used as in place of 'any'.
  Generally mime types are only set by client browsers in the request for things
  such as JSON or XML ajax requests.
  -->
    <mimeTypeCompression>
      <add type="application/json" path="^.*?/Services/.*"/>
    </mimeTypeCompression>
    <!-- 
  Defines the paths to match on to enable rogue file compression.
  Path is a regex selector, or a * can be used as in place of 'any'.
  jsExt and cssExt are comma seperated list of extensions to match to have the dependencies
  replaced with the composite file handler. You can even include ASP.Net web service JS proxies.
  -->
    <rogueFileCompression>
      <add path="*" compressJs="true" compressCss="true" jsExt=".js,asmx/js" cssExt=".css">
        <!--<exclusions>
          <add path="^.*test.aspx.*"/>
        </exclusions>-->
      </add>
    </rogueFileCompression>
  </compositeFiles>
</clientDependency>

Versioning

As seen in the above configuration, a version can be specified. This accomplishes the following:
  • Appends a version number as a query string to each JavaScript/CSS file request when in debug mode (see below). This is useful for new web application deployments as it will force all browsers to request an un-cached file. This solves the issue of having to clear your browser cache all of the time (or getting your clients to clear their cache)
  • When not in debug mode, forces the system to create newly versioned composite files. This refreshes the server output cache. This also solves the problem listed above with browser cache as well.

File registration providers (Web Forms)

The file registration provider controls how your script and css files get rendered into the HTML markup. The Client Dependency core ships with 3 providers: PageHeaderProvider, LoaderControlProvider and LazyLoadProvider. All file registration providers inherit from the BaseFileRegistration provider class.

PlaceHolderProvider

  • This provider gives you full control over where your JS and CSS references are rendered in your page. In order for this provider to work you must declare 2 Asp.Net PlaceHolder control's in your page with specific Ids assigned. By default, these Ids are: "JavaScriptPlaceHolder" and "CssPlaceHolder" but these can be changed via config if you want to specify different Ids. When the page renders, the JavaScript will be rendered where the JavaScriptPlaceHolder is found and the CSS will be rendered where the CssPlaceHolder is found.
  • This is most common provider used as it gives you full control over where in the page your dependencies are rendered.

PageHeaderProvider

  • This provider will render all script and link tags in the pages header tag

LoaderControlProvider

  • This provider will render all script and link tags in the same location in the page's markup that the ClientDependencyLoader control is found.

LazyLoadProvider

  • This is a specialized provider dynamically registers/injects JavaScript and CSS files using JavaScript
  • This is commonly used to improve page performance as the page will display before CSS and JavaScript files are downloaded, however, this generally means you'll need to have some sort of page loader renderred until the files are loaded.

MVC Renderers (MVC)

MVC renders the output for client dependencies using Renderer providers. The renderers included are: Standard Renderer and Lazy Load Renderer. A render simply outputs the script or style (link) markup to support all of the dependencies registered. With MVC, you need to specify in your markup where you would like to render the script or style tags in your html. Unlike webforms, MVC will render out the script/style (link) blocks wherever you put the following markup
<%= Html.RenderCssHere() %>
<%= Html.RenderJsHere() %>
So you need to make sure that you only use the syntax above in one spot throughout your views (such as on your master page).

fileDependencyExtensions

  • By default this property is set to "js,css" it is not mandatory to specify this property in the configuration.
  • This property indicates what files to process as file based dependencies as opposed to request based dependencies.
    • An example of a request based dependency could be an .ashx page that dynamically generates JavaScript, or a request to an .asmx/js webservice JavaScript proxy.
    • It is more overhead to process a request based dependency since the server will actually make the request on the server side to include it in the composite files generated.
    • If the system detects a file request that doesn't end in the extensions specified by this property, it treats the request as a request based dependency.

Composite file processing

  • This library ships with one composite file processing provider which uses a .Net handler to do the processing.
  • The configuration options are pretty self explanatory

Mime Type Compression

  • If you would like to add compression to requests based on mime type, you can easily add it here.
  • This is mostly useful for request such as JSON based requests

Rogue File Compression

  • Here you can specify how the system detects 'rogue' scripts and styles and how to treat them
  • Though its better to register scripts and styles with ClientDependency, the system will automatically compress/minify scripts and styles that haven't explicitly been registered, but again, you can change the config.

Last edited Jan 24, 2012 at 3:51 PM by Shandem, version 7