How to use Webgrease Configuration Files

WebGrease is a powerful utility for optimizing a web application's static asset files, such as CSS and JS. However manually entering the configuration for the action one wishes to run on the command line, tends to be impractical for anything beyond simple use. As I mentioned in my previous post, WebGrease supports consuming a configuration file to describe inputs and other settings in a reusable fashion.

Overview of a Configuration File Structure

WebGrease's configuration file, while having a lot of options that can be set is divided into 3 primary element types:

  • CssFileSet - Describes the input, output and operation settings for a set of CSS files. There can be multiple instances of this element in a configuration file.
  • JsFileSet - Exactly the same as the CSSFileSet, but for JavaScript files and operations. There can also be multiple instances of this element in a configuration file.
  • Settings - This element and its children describe settings that are not specific to any given FileSet element. There should only be 1 of these elements per configuration file, as subsequent instances will overwrite the previous values
Creating a Sample WebGrease Configuration File

The configuration files used by Webgrease are formatted in XML, so to begin create a new file in your favorite text editor, and fill in the basic XML header and root element:

    <?xml version="1.0" encoding="utf-8"?>
    <WebGrease>
    </WebGrease>

Next, create a Settings element. This element does not need to be first, but since there should only be one of them, it makes sense (to me at least), that it should be at the top so that another person editing the file can find it easily.

    <?xml version="1.0" encoding="utf-8"?>
    <WebGrease>
        <Settings>
        	<ImageDirectories>css\images;content\images</ImageDirectories>
            <ImageExtensions>*.png;*.jpg;*.jpeg;*.gif;*.ico</ImageExtensions>
        </Settings>
    </WebGrease>

The only global settings currently are related to image files. However in later version more options will be added.

The ImageDirectories setting describes a collection of directories, delimited by a semicolon, which contain static image files used by the web application. The files found in these folders that also match the values in the ImageExtensions setting, will be processed when the AutoName operation is executed (-a switch). The output from the renaming of these files will be placed in a folder named 'i', which is located in the output folder for the operation.

Now add a CssFileSet. Since the image settings mentioned earlier only apply to the auto/hash naming operation, we will keep that theme through the rest of this sample. A detailed breakdown on all the settings that can be declared in a CssFileSet or JsFileSet will be explained in the following section.

    <?xml version="1.0" encoding="utf-8"?>
    <WebGrease>
        <Settings>
        	<ImageDirectories>css\images;content\images</ImageDirectories>
            <ImageExtensions>png;jpg;jpeg;gif;ico</ImageExtensions>
        </Settings>

        <CssFileSet name="Sample" output="output\css">
           <Autoname>
               <RenameFiles>true</RenameFiles>
           </Autoname>

           <Inputs>
               <Input>css\basefiles\</Input>
               <Input>css\specificFile.css</Input>
           </Inputs>
       </CssFileSet>
    </WebGrease>

With the CssFileSet element, we can declare an optional name for it, as well as where to put the files. As with all path inputs, the output location can be a relative path or an absolute one. Since we are making a sample config for doing auto naming of files, we declare the Autoname element, and set its RenameFiles setting to true. Next a set of inputs are declared. The value of an Input element can be a folder (as the first one is), and any CSS file found in that folder will be included in the process. Also, as the second input describes, a single file can be declared as an input.

To finish out this sample config file, the JsFileSet will be added. In the case of our example, the structure will look exactly the same as the CssFileSet, only the names and inputs will be different.

    <?xml version="1.0" encoding="utf-8"?>
    <WebGrease>
        <Settings>
            <ImageDirectories>css\images;content\images</ImageDirectories>
            <ImageExtensions>png;jpg;jpeg;gif;ico</ImageExtensions>
        </Settings>

        <CssFileSet name="CssSample" output="output\css">
            <Autoname>
                <RenameFiles>true</RenameFiles>
            </Autoname>

            <Inputs>
                <Input>css\basefiles\</Input>
                <Input>css\specificFile.css</Input>
            </Inputs>
        </CssFileSet>

        <JsFileSet name="JsSample" output="output\js">
            <Autoname>
                <RenameFiles>true</RenameFiles>
            </Autoname>

            <Inputs>
                <Input>js\basefiles\</Input>
                <Input>js\specificFile.css</Input>
            </Inputs>
        </JsFileSet>
    </WebGrease>
Using a Configuration File with WG.EXE

In order to use a configuration xml file, such as the sample created previously, there are some extra command line parameters that can be set.

-c : Use this parameter to declare which config file to use. Paths can be relative or absolute.
-t : This parameter declares what config "type" to use.  Any of the child setting elements in a FileSet can declare a config attribute:

Ex : <Autoname config="Debug">

Note: If the type parameter is set on the command line, and assigned the value of "Debug" then the settings elements with the matching attribute will be used. This parameter is optional, and if omitted, the respective settings parser will read in the first setting block it finds, or will generate a default configuration. If a config type is specified, but the config parser cannot find a matching name, it will also just generate a default config.

-in : The Input parameter takes on a special meaning when a config file is used. It defines the "base" input path, which will be prepended to any relative paths in the config file. This parameter is optional and defaults to the current directory if omitted.

-out : Similar to the input parameter, the output parameter will be used as the base path prepended to any output relative paths in the config file.

An example run of WG.EXE to do an autonaming operation, using a config file called "sample.config" could look something like this:

Wg.exe -a -c:sample.config -in:c:\www\content -out:c:\www\crunched\ -t:Release
Configuration Settings in Detail

Near the top of this long post, I mentioned that WebGrease configuration files have 3 types of configuration sections. There are a lot of configurable settings in each section and I will attempt to explain each one.

FileSet Configuration Section

The declaration of a FileSet is very straight forward. There are only 2 attributes that can be set:

  • Name: The name of the file set. Currently not used programatically however.
  • Output: Where the results of any operation run on this set should go.
    However there are sub sections that can be defined, and each one can have a config attribute defined on them to specify the type name the settings should be applied to (when the -t parameter is used on the command line)
CssFileSet Specific Settings

Minification

  • Minify : Enables or disables minification processing for the config type. The default is 'true'.
  • ProhibitedSelectors : A comma delimited collection of CSS selectors, that if found in the processed files, should cause an error. Default is 'empty'.
        <Minification config="Debug">
            <!-- disables minification for the debug config type-->
            <Minify>False</Minify>
            <!--Selectors that should be considered invalid and have an error raised if used-->
            <ProhibitedSelectors>*>html,html>body</ProhibitedSelectors>
        </Minification>

Spriting

  • SpriteImages: Toggles spriting of images referenced in the processed CSS files. Default is 'true'
          <Spriting config="Debug">
           <SpriteImages>false</SpriteImages>
          </Spriting>

JsFileSet Specific Settings

Minification (it is different from CssFileSets)

  • Minify : Enables or disables minification processing for the config type. The default is 'true'.
  • MinifyArguments: You can specify "AjaxMin style" arguments here for fine tailoring of javascript minification. Please refer to the Ajaxmin documentation for details.
  • GlobalsToIgnore: This is a semicolon collection that is passed to the minifier, of globals that should not be minified.
         <Minification config="Release">
            <Minify>True</Minify>
            <MinifyArguments>-h -d -m -k</MinifyArguments>
           <GlobalsToIgnore>jQuery;Foo</GlobalsToIgnore>
         </Minification>

Validation

  • Analyze: Toggles analysis of JavaScript files. Default is true.
  • AnalyzeArgument: Ajaxmin style arguments for validation.
        <Validation config="Release">
             <Analyze>True</Analyze>
             <AnalyzeArguments>-analyze -WARN:4</AnalyzeArguments>
        </Validation>

Common Settings

AutoNaming

  • RenameFiles : Toggles the renaming (via hashing) of included files. The default is 'true'
         <Autoname config="Debug">
             <RenameFiles>false</RenameFiles>
         </Autoname>

Bundling

  • AssembleFiles : Toggles bundling of the files into a single output file. The default is 'true', however if the output attribute of the FileSet is pointed at a folder and not a file path, an error will occur when the bundling option is invoked.
        <Bundling config="Release">
              <AssembleFiles>false</AssembleFiles>
        </Bundling>

Input Settings

The <Inputs> (and child <Intput>) elements are common between both the JsFileSet and CssFileSets, however they do not have named config attributes associated with them. However, the <Input> elements do have options in the way they are declared, as the following example will show:

    <Inputs>
      <!-- just get this from combining the relative path with base input path-->
      <Input>css\site.css</Input>
 
      <!-- will get this regardless of the base input path -->
      <Input>f:\webgrease files\css\site.css</Input>
 
      <!-- will recursively get everything under [base input path] + css\*.css -->
      <Input>css\</Input>
 
      <!-- will get first dir level files under [base input path] + realworldcss\*.css -->
      <Input searchPattern="*.css" searchOption="TopDirectoryOnly">realworldcss</Input>
    </Inputs>

A Tip for Using Config Files with WG.EXE

Even though you can set configuration values for all the operations WG.EXE supports, you can still only do 1 operation per execution of WG.EXE. The operation switch on the command line is the one which will be honored and the settings used. Because of that fact, it is easier to create a config file for each operation you plan on doing. This especially applies if you are attempting to create a script that will run at build time. If you try and use a single file with all the FileSets needed, the specific sets will get cluttered with operation disable settings, since you have to explicitly exclude sets. It is easier to make smaller inclusive config files.

I hope you found this post informative on how to structure a config file and use it with WebGrease.