How SideWaffle Works

SideWaffle consists of the following components.

1. VSIX Project
2. Template/Snippet content
3. TemplateBuilder NuGet package

The TemplateBuilder NuGet package contains all of the logic, which is invoked during build, to populate the created .vsix file. Since that's the case this article is going to be more of a How does TemplateBuilder work.

TemplateBuilder has a main MSBuild targets file,ligershark.templates.targets (source). When the TemplateBuilder NuGet package is installed into a project the build process for that project is extended. In SideWaffle the TemplatePack project is a VSIX project that has this NuGet package installed. When this NuGet package is installed into a VSIX or VS Package project (any project that outputs a .vsix file) an import to ligershark.templates.targets is inserted into the project file. An assets tag that looks like the following will be inserted into the .vsixmanifest file

   <Assets>
    <Asset Type="Microsoft.VisualStudio.ItemTemplate" Path="Output\ItemTemplates" />
    <Asset Type="Microsoft.VisualStudio.ProjectTemplate" Path="Output\ProjectTemplates" />  
  </Assets>

These asset tags enable the .vsix to contain item and project templates.

The build process will be modified in the following ways.

1. Before compile remove files under ItemTemplates,ProjectTemplates, and Snippets from the list of files to be built.
2. Convert contents under ItemTemplates into item templates in the generated .vsix
3. Convert contents under ProjectTemplates into project templates in the generated .vsix
4. Convert contents under Snippets into snippets in the generated .vsix.

During the build process TemplateBulider will write all of it's files under obj\debug\ls-Templates or the more general obj<build-config>\ls-Templates path. As templates and snippets are processed the .zip files will be written into this folder as well. Those .zip files will be embedded in the generated .vsix in the following locations.

• Output\ItemTemplates
• Output\ProjectTemplates
• Snippets

After the .targets file has been imported into the project there is no other special work needed to light up creating templates or snippets. You just have to create the files in the correct folder locations and naming conventions.

How to build SideWaffle

Building SideWaffle is pretty simple, there are three options depending on your needs.

• Building SideWaffle in VS
• Building a Release version of SideWaffle from command line (preparing for a release for example)
• Building SideWaffle in "debug" mode

We will spell out each option below.

Note: Currently there is a known issue in which you will receive a build failure on the first build (build before package restore). This is caused by the .targets file not being on disk before the build starts.

Building SideWaffle in VS

If you are working in VS, building SideWaffle is the same as building any other project. You can simply build the solution or project as you normally would. You can switch build configurations as you could any other project as well. If you build in Release mode the templates that start with "_Sample" will be excluded from the generated .vsix.

Building a Release version of SideWaffle from command line

To build SideWaffle from the command line you can use the .cmd file at /build.cmd. This will call msbuild.exe on build.proj to execute the build process. There are some properties that can be overridden. If you are interested take a look at build.proj. Here are some important default values.

• Default output dir: \OutputRoot\
• Default config: Release
• Default to restore NuGet packages

Building SideWaffle in "debug" mode

If you are working on modifying the build process (which lives in TemplateBuilder) then you'll need to build SideWaffle such that you can override the MSBuild targets and tasks. There is a .ps1 file that will be your friend here.

You can use build-debug.ps1 from the root directory of the project to build SideWaffle in debug mode.

This script will build SideWaffle with the following customizations.

1. Build the solution in Debug mode (which includes all templates)
2. Override .targets path to point to TemplateBuilder source
3. Override tasks path to point to output directory of TemplateBuilder source

Environment setup

In order to invoke this script you may need to make two small tweaks to your PS environment, which are.

1. msbuild alias must be defined and pointing to msbuild.exe
2. TemplateBuilderDevRoot env variable should be defined to point to the template-builder root directory. For example $env:TemplateBuilderDevRoot = "C:\Data\mycode\template-builder\". *Note: this must end with a slash *

The script will override two key MSBuild properties to enable you to consume TemplateBuilder properties.

1. TemplateBuilderTargets which is declared as $templateBuilderTargetsPath = ("{0}tools\ligershark.templates.targets" -f $env:TemplateBuilderDevRoot)
2. ls-TasksRoot which is declared as $templateTaskRoot = ("{0}src\LigerShark.TemplateBuilder.Tasks\bin\Debug\" -f $env:TemplateBuilderDevRoot)

Also make sure to have build the TemplateBuilder solution at least once. By default the script will pickup the assemblies from LigerShark.TemplateBuilder.Tasks\bin\Debug.

The console log is limited for brevity and to increase perf. If you have issues take a look at the build logs which will be placed at the following locations.

• msbuild.d.log
• msbuild.diag.log

Options when invoking build-debug.ps1

There are two optional parameters that build-debug.ps1 supports. They are described below.

extraBuildArgs

Using this parameter you can pass additional parameters to msbuild.exe. You can either pass a single string to be appended, or an array of strings. Here is an example .\build-debug.ps1 -extraBuildArgs '/t:demo'.

preventOverridingTargetsPath

By default the .targets and tasks path will be updated to the TemplateBuilder source location. If you want to prevent those from being overridden you can use this parameter.

TODO: WORK IN PROGRESS