-
Notifications
You must be signed in to change notification settings - Fork 6
Build Script
Automation is a life saver.
The build script is used to automate tasks that aid in getting the project in a production ready state. The script is located in the [build directory] (https://github.com/moov2/dotnet-mvc-boilerplate/tree/master/build) and requires [Ant] (http://ant.apache.org/) for it to be executed. Ant is a free to use command line tool that allows us to compile, assemble, run & test our projects. Ant can be easily integrated into a continuous integration setup that enables an automated production process.
The /build directory is where all the files that make up the build script are located. Navigating to this directory via the command line and executing the 'ant' command (provided you have Ant correctly installed) will kick start the build script.
This file is the build script. An ant build script is an XML file made up of targets that represent tasks. We will go through the individual targets in more detail in the targets section of this document.
This file is also a build script, however it is a NAnt build script. NAnt is very similiar to ant, however it is catered for .NET specific tasks like MSBuild & NUnit. The targets in this NAnt build script are accessed by the ant build script using Apache .NET Ant Library that enables ant to support .NET related tasks. In our build.xml file the .NET ant library is used to execute speecific targets in the NAnt build script.
This directory stores all the external tools that are used by the ant & NAnt build scripts.
Both the ant & NAnt build script contain lots of properties that help configure the build process. The config directory contains the properties for the ant build script and is the file you need to be changing in order to configure the build script to your own requirements. The project.properties file is full of comments to help give understanding to what each of the properties configures.
The [build script] (https://github.com/moov2/dotnet-mvc-boilerplate/blob/master/build/build.xml) is composed of many targets, which are essentially tasks that do various jobs to validate the project and then get it ready for production. Targets that aren't prepended with a '-' are known as public targets that can be solely executed when given as a command argument when running ant. When they are prepended with a '-' the target can't be solely executed and has to be called within the build script itself.
The build target defines the order to run other targets in the script. This target is the defined in the build script as the default, so when no targets are supplied in the command arguments, this target is the one that is executed. This target represents the complete build process and will creat a production ready website.
As the only other public target, this target simply invokes the -less target which is responsible for converting any specified less files into css files.
Responsible for deleting artifacts that were produced from a previous run. The artifacts that are currently deleted is the /deploy folder that holds reports from testing, the intermediate project and the published production.
Creates all the directories that are required to be there so the build script doesn't error. As you have probably realised, it is essentially just creating the directories that have been deleted by the -clean target.
Compiles the solution using MSBuild with the Clean & Build flags. Essentially this is replicating the "Clean Solution" & "Build Solution" options that are presented to you when right clicking the solution in Visual Studio. This task validates any code changes that have been made to the project don't break the project. If the compile fails, then the build will fail, this is perfect for integrating with a continuous integration process to ensure any changes pushed to the source code repository can't break the build.
Because the previous target was the -compile target, the unit testing project will have also been built, as the -compile target builds the entire solution. This means the dlls that hold the unit tests is available and can be executed, that is exactly what this target is responsible for. The NUnit test runner is used to run the tests and it also dumps and XML output of the results from the tests into a test-reports directory inside the artifacts folder. If a unit test fails, then the build script is deemed to have failed as well.
Similar to the -compile target, the solution is built again however this time the configuration is set to Release. The Release configuration will tell MSBuild to compile the solution ready for a final release, meaning that the solution will contain no debugging information and be heavily optimized.
Loops through all the specified .less files and compiles them into .css files using the lessc command line tool . The .less files are specified in a comma separated list that is set on a property in the properties folder.
In order to improve performance of the final product we need to decrease the amount of page requests (for js & css files) and the size of those requests. In order to do this, modification of the css, js, images and the html pages needs to be done. When doing this, we don't want to modify the development code so to avoid this, the files that make up the project are copied into an intermediate directory. Once in this intermediate directory, the files can be manipulated with the confidence that files that the developer works on are not changed.
This target is responsible for managing the css, it does this via multiple other targets that help organise the css. The overall goal of this target is to load the websites css as quickly as possible to ensure fast page loads for the end user.
The first task is changing any <link> tags that load external less stylesheets to load their compiled css versions. This modification is only done on pages that are specified in a comma separated format on a property in the project.properties file.
In order to develop on .less files and see changes reflected instantly in the development environment, the .less files are compiled on the client using the less.js javascript library. However, for the production version of the project we definitely don't want the user to have a dependency on having javascript enabled in order to view our website with pretty css. This target will remove the loading of the less.js javascript library from the HTML tag in all the files specified in a comma separated format on a property in the project.properties file.
This target will concatenate all the specified css files into a single css file. This reduces the amount of page requests when access a page on the website. Because we no longer need the HTML to load all the stylesheets, this target will also go into the specified HTML pages and remove any external stylesheet loads for the concatenated css files.
This target performs minification on the concatenated stylesheet using YUICompressor. Minification is the process of removing comments & white space in order to reduce the size of a file, while preserving its functionality.
By this point the HTML should be left loading a single external css file, by default this is the style.css file. The style.css now has a concatenated version (style-concat.css) and a minified version of that file (style-concat.min.css) to play with. Also all the other external stylesheets that have been concatenated have had their external loads removed. The final stage with the css is to ensure when the production version is published into the live environment, the user doesn't get served up a cached stylesheet that is related to older versions. This target will create a randomly generated filename and copy the style-concat.min.css to a new file in the css directory that takes the generated filename. Finally we replace the external stylesheet load of style.css with an external load of our new file that contains the minified css. So when the user loads the site for the first time since a new release, you can be confident that the styles won't be loaded from cache because the url will be completely unique.
Like the -css target, this target is split into multiple other targets. The overall goal of this target is exactly the same as the -css, to load the javascript for the website as quickly as possible.
This target will concatenate all the javascript files that are loaded between the comment markers in the HTML pages specified. An example of the marker comments and some javascript loads are shown below.
<!-- scripts concatenated and minified via build script -->
<script src="js/libs/jquery.form.js"></script>
<script src="js/libs/jquery.validate.js"></script>
<script src="js/libs/jquery.validate.unobtrusive.js"></script>
<script src="js/mylibs/boilerplate.js"></script>
<!-- end scripts -->
For the code above, the four javascript files that are loaded between the comments will be concatenated and placed into a single javascript file (scripts-concat.js).
This target will perform minification on the concatenated javascript file just like we did on the css using YUICompressor. This will produce a much smaller file (scripts-concat.min.js) that can be loaded much quicker.
Starting to sound familiar? The -js target is very similar to the -css target, which is no surprise since they have the same goals. The final target called by the -js target removes all the <script> tags between the markers comments in the specified page files and replaces it with a <script> tag that loads the cache busting javascript file containing the contents of scripts-concat.min.js.
This target utilises the aspnet_compiler.exe to compile our ASP.NET project that is located in the intermediate directory and place the result in a publish directory. The contents of the publish directory is your website and is ready to be placed into a live environment.
Uses optipng to shave off a small amount of KBs off all the PNG images used in the website. This can have a small affect on the time taken to load your website.
Uses smush.it to shave off a small amount of KBs off all the images in the website. This process is described in more detail here.