Precompilation - Precompiling your scripts and stylesheets during the build
For the best possible performance, it is recommended that you precompile your scripts and stylesheets when you build the website. Precompiling will:
- Generate static .css and .js files for the consolidated groups configured in the Assman.config file
- Minify individual scripts and stylesheets that are not part of group
- Compile languages such as dotLess and Coffeescript files to static .js or .css files (if you installed a plugin to support those languages)
- Generates a manifest file (Assman.compiled) that keeps track of all compiled files and their dependencies. This allows Assman to optimize its performance at runtime as it does not need to figure those things out on the fly.
How to precompile
In general, the best thing to do is to set up your automated build to set this property when it builds your website. It is generally not recommended that a developer precompile the resources on their local machine (unless testing out the pre compilation process)
because that will prevent Assman from optimizing for the developer (when resources have been precompiled, it will no longer dynamically consolidate your files...which is not ideal for a developer as he/she is developing the site). If you do accidently (or
intentionally) do precompile and you want to undo that, you can either do a Clean build, or you can manually delete the Assman.compiled file located in the bin directory of your website.
If installed the NuGet package
When you install the Assman.Mvc2 or Assman.Mvc3 NuGet package, it will automatically add a Target to the .csproj file of your Web Application Project. To have the project precompile resources, you simple need to set the msbuild property "PreCompileResources"
to true. One way to set the property is from the command line such as:
msbuild MyWebApp.csproj /p:PreCompileResources=true
If you want to set it up manually:
An MSBuild task is provided an the Assman.dll to do the precompilation. You need to import the task, and then call it within a Target of your choice. Here is an example:
<UsingTask TaskName="Assman.BuildSupport.MSBuild.PreCompileResources" AssemblyFile="Path\To\Assman.dll" />
<PreCompileResources WebRoot="Path\To\WebsiteRoot" />
Outside of MSBuild
If you would prefer to initiate the Precompilation outside of MSBuild, a PreCompileCommand class is provided in the Assman.BuildSupport namespace of the Assman.dll. It has the same properties available as the MSBuild task (properties documented below). The
only required property is WebsiteRootDirectory, which should be a path to the root directory of the website. An .exe to precompile is planned for the future. If you need one, for now you can roll your own and have it use the PreCompileCommand class to do the
PreCompileResources MSBuild Task docs:
Here are the properties of the PreCompileResources MSBuild Task. Only the WebRoot properties is required:
- WebRoot - A file path to the root directory of the website
- Version - By default, the task will generate a version based on the current timestamp. If you would prefer to use your own version (e.g. one based on your build number), you can set this property and it will be used instead.
- Mode - By default, the resources will be compiled in Release mode. If instead you would like to precompile for Debug mode, you can set this property to "Debug". In debug mode, resources will not be minified (though they will still be consolidated
unless configured otherwise in the Assman.config file).