build readme

/Build/Readme
==============
This project aims to make building, publishing and deploying Umbraco web applications easier.
It also enables team members who do not have Visual Studio to create and edit content without Visual Studio.
It encourages a seperation between the Visual Studio .csproj file and a user generated .targets which in my view makes MSBuild easier to grasp.

It automates the following:
- Including the Umbraco Application
- Including files created within Umbraco (e.g. a new stylesheet)
- Ensures required files are avalible for the build (e.g. installedPackages.config)
- Enviroment based permissions (Debug & Release) (Media, etc)
- ACL's (permissions) are correctly set on custom folders (Media, etc)
 
It does this in an extensible way.

## Quick Start

.Tasks = reusable functionality (gives functionality)
.Props = call tasks (does things using tasks)
.Targets = reusable processes (affects build process)

So if you need to write new functionality you would create a task. If you want to leverage an existing task, you would create a .props. 
In this project it is most likely that you will want to edit the Umbraco.props file, to set ACL's on additional folders.

## But how do I use it?

To use you need to hook into each Visual Studio project. Oh boy, I wish there was a 'convention over configuration' avalible for this, 
but sadly I don't think there is. Sorry.

So open your *.csproj in your favorite'st ever text editor

Scroll to the bottom:

And before </project>

Add

<Import Project="$(MSBuildProjectName).targets" Condition="Exists('$(MSBuildProjectName).targets')" />

This line will import a MSBuild targets file, that has the name of your project.

So if your project is called company.widgets.Website

It will look for a file called:

company.widgets.Website.targets

Next create these files:

#### The Targets File = company.widgets.Website.targets

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  
  <!-- Before Build -->
  <Import Project="../Build/VooDoo.Umbraco.targets" />
  
  <!-- Hook into BeforeBuild and ensure the ABOVE Targets run (DependsOnTargets)-->
  <Target Name="BeforeBuild" DependsOnTargets="Umbraco">
  </Target>
  
  <!-- After Build -->
  <Target Name="AfterBuild">
  </Target>
  
</Project>

#### The Web Publishing Profile Targets File = company.widgets.Website.wpp.targets

* hurrah! Convention over Configuration here! :D

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <!-- Propertys -->
  <Import Project="../Build/VooDoo.MSDeploy.Global.Umbraco.props" />

  <!-- Tasks -->
  <Import Project="../Build/VooDoo.MSDeploy.Global.tasks" />
  <Import Project="../Build/VooDoo.MSDeploy.Debug.tasks" Condition="$(Configuration)=='Debug'"/>
  
</Project>


## Building with MSBuild

Open Visual Studio Command Line

Build solution
> msbuild company.widgets.sln

Build project
> cd company.widgets.Website
> msbuild company.widgets.Website.csproj

Package project (debug)
> msbuild company.widgets.Website.csproj /T:Package /P:Configuration=Debug

Package project (release)
> msbuild company.widgets.Website.csproj /T:Package /P:Configuration=Release

Package and Deploy to IIS
> msbuild company.widgets.Website.csproj
  /P:Configuration=Debug
  /P:DeployOnBuild=True
  /P:DeployTarget=MSDeployPublish
  /P:MsDeployServiceUrl=localhost
  /P:AllowUntrustedCertificate=True
  /P:MSDeployPublishMethod=WMSvc
  /P:CreatePackageOnPublish=True
  /P:UserName=Administrator

## Build files

### VooDoo.Umbraco.Targets
Ensures all Umbraco application and user generated files are included in the build.
Regardless of if they are included in the Visual Studio project.

### VooDoo.MSDeploy.Global.tasks
Contains custom tasks used when Deploying the website. Currently for setting custom ACLs.

### VooDoo.MSDeploy.Debug.tasks
Contains custom tasks used when Deploying the website in Debug mode.
- Ensures the entire 'wwwroot' is writable for development/debug purposes

### VooDoo.MSDeploy.Global.Umbraco.props

- Sets correct ACL's on /Media (you can uncomment uSync if you use this)
- Ensures server unique caches in App_Data are not deleted on Deploy
- Ensures new media files are not deleted on Deploy

## Many thanks to:

Sayed Ibrahim Hashimi, http://www.sedodream.com/