Scripting & Automation

Sixeyed.Guidance.CodeGeneration: Technical Walkthrough

EltonStoneman — Mon, 09 Mar 2009 23:05:28 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The Code Generation Guidance Package on CodePlex was designed to be extensible and reusable. There are three main C# projects, which isolate logic for code generation, and the UI and GAX components.

Sixeyed.CodeGeneration

This is the core project, defining how metadata is represented and retrieved, and defining configuration for code generation runs. Metadata is defined in terms of:

A metadata source, which contains the logic for connecting to the source
A metadata provider, which uses the source to provide a list of available items, and to populate requested items
Metadata items, which are a representation of the metadata, typically using an appropriate .NET framework class

Code generation and UI logic always works on the interfaces which define these components, and the relationships between them:

In the Add Generated Items recipe, the available source types, sources and providers are populated from the collection of IMetadataSource objects held in the static SourceContainer class (additional sources can be added to the container at runtime using the SourceAssemblyConfiguration recipe argument – described in Sixeyed.Guidance.CodeGeneration Sample Package). When a provider is selected, GetItemNames is called to populate the list of available metadata items. When the selected items are iterated over in a code generation run, GetItem is called and the populated IMetadataItem is loaded as a property for the T4 template. The metadata item exposes the provider, and the provider exposes the source so the template can connect directly to the metadata if it needs to.

Each metadata interface has an abstract base class which implements it and contains core logic. For a given source, there may be an additional base class which abstracts logic common to that type of source. In Sixeyed.CodeGeneration.Metadata.Database.Source, DatabaseSource contains logic for accessing ADO.NET data sources in terms of IDbConnection and IDbCommand objects; SqlServerSource contains overriding logic to specify SqlConnection and SqlCommand usage – any additional database sources would do the same. Similarly for the SOAP metadata source, the logic for accessing WSDL is abstracted into a base class which may be used by other sources (e.g. a WCF specific source):

IMetadataProvider contains logic for accessing the source and retrieving a list of available items, and for populating a named item. The majority of logic is in the generic base class, so provider classes are quite simple. Simpler still are metadata item classes, which inherit the generic ItemBase class, specifying the underlying type of the item (XmlSchema in this case), without requiring any additional code.

Logic for populating template properties and executing T4 templates is located in the Guidance project rather than the code generation project, as it is dependent on the specific T4 engine being used.

Sixeyed.CodeGeneration.UI

The UI project contains generic user controls which represent metadata selections, and expose various events to notify of selection changes. The Guidance package Wizard uses these components rather than defining its own UI – the controls from this assembly allow code generation to be configured and invoked from a different UI host.

Sixeyed.Guidance.CodeGeneration

This project defines the GAX package and links together the code generation and UI components. The Guidance package is quite straightforward – it contains a single class AddGeneratedItems for the action of generating items from metadata and adding them to the selected project. The action expects SourceConfiguration, SelectedItems and TemplateConfiguration arguments; it connects to the source, iterates over the selected items and executes the template for each item.

To collect the argument values, there are custom wizard pages and value providers for each, allowing a recipe to provide ready-configured settings, or build a UI to gather them from the user:

Sixeyed.Guidance.CodeGeneration.CustomWizardPages. The custom Wizard pages use the static Metadata class to share state for the configured metadata source and provider. They override IsDataValid to determine if the page has collected enough information for the Wizard to proceed and the base class provides EnableNextStep which will advance the Wizard by enabling the Next or Finish button as appropriate. The base class will read the SourceAssemblyConfiguration recipe argument if provided, and use it to add any extra metadata assemblies at runtime.
Sixeyed.Guidance.CodeGeneration.ValueProviders. The value provider classes are straightforward, reading optional arguments from the recipe and populating the relevant metadata settings. Custom recipes can specify value providers to load settings instead of Wizard pages, so the Wizard UI can be restricted.

TODOs

There are a couple of minor changes I'd like to make to the current codebase:

Sixeyed.Guidance.CodeGeneration.CustomWizardPages.SelectTemplate defines its own UI, which should be moved to a user control in the UI project;
Sixeyed.CodeGeneration.Generation.MemberName contains methods for providing valid field and property names, but the Pascal and camel-case conversion is very basic;
Sixeyed.CodeGeneration.UI.SourceUri has some ugly hard-coding to decide which UI dialog it should show for different types of URI. It should be configurable, but I'm not happy moving it to an attribute of IMetadataSource, as that brings the UI into the core project.

And some additional metadata sources which I'll add at a future point – a Clipboard source providing access to clipboard data through text or XML providers, and a BizTalk source which will use the ExplorerOM for providers supplying application, group and instance information as metadata.

Sixeyed.Guidance.CodeGeneration Sample Package

EltonStoneman — Sun, 08 Mar 2009 22:46:00 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The basic Code Generation Guidance Package on CodePlex comes with an additional sample Guidance package. This sample is intended to demonstrate how the functionality of the base package can be customised to create a project-specific Guidance package, where you can easily add tailored code generation recipes to your package. In the basic package are the Wizard steps necessary to configure ad-hoc code generation, but there are also ValueProviders which can read configuration from recipes without requiring the whole user interface.

Installation

You'll need to modify the hard-coded paths and URIs in the sample package, so it doesn't come with an installed release. If you open the Sixeyed.Guidance.CodeGenerationSample solution you'll see that it references the base Sixeyed.Guidance.CodeGeneration and Sixeyed.CodeGeneration assemblies. The sample contains a set of T4 templates in the \Templates\Text directory, the XML configuration for the package and the XML includes for individual recipes. There's no additional code in the sample project, all the required functionality is in the referenced base package.

Together with the GAX project, there's a database project which you can use to create a SQL Server database suitable for the data-bound recipes to run against. To install, run the CreateDatabase script and then execute the SSIS package to populate data from the included Excel workbook (this is only necessary if you want to run the recipes as-is, otherwise you can modify the XML to use your own database).

Sample T4 Templates

There are T4 templates for each of the metadata providers in the base package. The scripts named _Simple.tt are straightforward and begin with the name of the expected provider; to run them, you can use Add Generated Items from the base package, select the relevant metadata and point to the template. To demonstrate more useful code generation, there are two more substantial templates:

ConfigurationSection.cs.tt – use the File source and the Text provider on this template. If you select Configuration.txt (from the database project) as the source, the recipe will generate a typed configuration class, which has a static property to access the current config settings. The template can be easily extended to add a Default value for optional settings, and the same text file can be used to drive a different T4 template to generate the actual configuration settings;
StoredProcedure.cs.tt – use the SQL Server database source and the Stored Procedure provider. Select a procedure and the recipe will generate a DAL class to execute the stored procedure. This class won't compile, as it inherits from a base class which isn't provided, but it demonstrates one approach for DAL generation.

Sample Recipes

The included recipes demonstrate configuring one or more settings for code generation so that the Wizard can be tailored or avoided altogether. Generate Stored Procedure shows this best, configuring the metadata provider using the SourceConfigurationValueProvider:

<ValueProvider Type="SourceConfigurationValueProvider"

SourceTypeName="Database"

SourceName="SqlServer Database"

SourceUri="Data Source=x\y;Integrated Security=True;Initial Catalog=Scratchpad;"

ProviderName="Stored Procedure Provider">

</ValueProvider>

</Argument>

These settings are the equivalent of the first Wizard page, selecting the metadata source. It specifies the source type and source name, the URI for the source (in this case, the Scratchpad database included with the sample), and the metadata provider name. Having the SourceConfiguration argument pre-populated means the first Wizard page will be skipped. The recipe also specifies the T4 template to use with the TemplateConfigurationValueProvider:

<ValueProvider Type="TemplateConfigurationValueProvider"

TemplatePath="x:\y\z\Templates\Text\StoredProcedure.cs.tt">

</ValueProvider>

</Argument>

Only the template path is specified here, but other settings (target namespace, class name etc.) can also be provided. Having the TemplateConfiguration argument populated means the third Wizard page will not be shown. Running this recipe gives you a Wizard form which only contains the second page, for selecting metadata items, pre-populated with the list which has already been loaded from the configured database:

- note that the other pages are not available, so the user is constrained to using the configured source and T4 template.

Other recipes demonstrate configuring all or part of the settings needed for code generation. Generate Simple runs a template which requires no metadata, so it connects to the metadata source, runs the template and adds the project output with no user intervention. Additional Source demonstrates how you can extend the base code generation guidance package with additional metadata sources and providers of your own, without rebuilding the base package. Specify the SourceAssemblyConfiguration argument:

<ValueProvider Type="SourceAssemblyConfigurationValueProvider"

AssemblyList="Sixeyed.CodeGeneration.Tests">

</ValueProvider>

</Argument>

- and the .NET assemblies named in AssemblyList (semi-colon separated) will be interrogated at run-time to identify IMetadataSource and IMetadataProvider implementations (there'll be more detail on those interfaces in a coming post). Any available classes will be added to the list of sources and providers shown in Add Generated Items, and can also be used in SourceConfiguration argument values.

Usage

By providing custom recipes, you can tailor your own Guidance packages which contain recipes for generating classes or other artifacts based on established patterns. This gives the project team an easy way of ensuring consistency for common coding problems in the domain – configuration sections and stored procedure wrappers are simple examples. Note that the URIs and paths are hard-coded. The code generation guidance package will attempt to find a T4 template if the path is not fully stated, but it won't always succeed (there's an issue with returning the running GuidancePackage instance that I haven't tracked down). In a typical project though, templates would be in SCM and source URIs would be consistent among developers, so fully-qualified hard-coded text shouldn't be a problem.

I'll be extending the sample package to include other templates that may be useful starting points for common code generation tasks – enums to represent reference data, unit tests for .NET and BizTalk artifacts, MSBuild scripts and anything else that occurs. If you have any templates of your own which would fit in a standard library, let me know and I'll add you as a CodePlex contributor.

Code Generation Guidance Package

EltonStoneman — Sun, 08 Mar 2009 01:51:14 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

I've been working on a Guidance package which lets you use Visual Studio as a front end to generate items from T4 templates. Using a recipe wizard you choose your metadata from a Web service, database or file system source, and the template is rendered against each of the metadata objects you select. It's on CodePlex here: Code Generation Guidance Package, and comes in two flavours. The basic Guidance package has a single recipe "Add generated items" – when you run it, you specify a metadata provider, select the items to use for metadata and the T4 template to render against the items.

The second package is a sample which extends the functionality of the main Guidance package with custom recipes. This demonstrates how you can define recipes for pre-configured generation types, so the user does not need to complete all the wizard pages – one example specifies a database connection string and a T4 template for generating stored procedure wrappers; to add a new DAL class, the user runs the recipe and just selects which stored procedure(s) they want generated.

Neither package comes with any Visual Studio solution or project templates, and they do not need to be used to create the original solution. Any existing project can make use of the code generation features by enabling the package(s) through Tools…Guidance Package Manager.

In this post I'll give an overview of using the basic Sixeyed.Guidance.CodeGeneration package, and in future posts I'll add some technical detail and give a walkthrough of the sample project.

Add Generated Items

Run the Add generated items recipe from the Guidance Package Manager, or from the context menu of any project in Solution Explorer. The wizard loads to collect settings - in the first page you select the metadata source type, configure the source and select the metadata provider:

During generation, the provider will load each of the selected metadata items and provide them as a property which can be accessed in the T4 template. For instance if you use the SQL Server Stored Procedure provider, your T4 script will have a populated SqlCommand object available to use.

Provided with the basic Guidance package are the following Sources and Providers:

File System
- File source – for using one or more files as metadata
  - XML File provider – for using XML file contents, exposed to the template as an XmlDocument instance
  - Text File provider – for using text file contents, exposed as a string
  - Assembly File provider – for using a .NET assembly, exposed as an Assembly instance
- Directory source – for using a list of directory contents as metadata
  - File List provider – for using a list of file names, exposed as a List<string> instance
  - Directory provider – for using a directory, exposed as a DirectoryInfo instance
Database
- SQL Server Database
  - Query Result provider – for executing a SQL query and exposing the results in a populated DataSet
  - Table provider – for using a table as metadata, exposed as an empty DataTable with the correct structure
  - Stored Procedure provider – for using stored procedures, exposed as a populated SqlCommand object
WSDL
- SOAP source
  - Web Method provider – for using a Web service method, exposed as a MethodInfo object
  - Schema provider – for using the WSDL of the service, exposed as an XmlSchema object

When you select a provider, it will load a list of all available metadata items, and you select which items you want to run the T4 template against:

The item selection is always a simple list displaying the item name – this will be the name of the file, table, Web method etc (an exception is the QueryResult provider which uses this page to capture the SQL query to be executed).

In the final screen, select the T4 template to use:

The file dialog will default to the "Templates" folder of the Guidance package, but you can navigate to any T4 file. If you want to override the output settings from the T4 file, specifying a different target filename, namespace extension or class name you can do it in the additional properties in this step:

Finish the wizard and the recipe will iterate over each of the selected items, populating a representation of the metadata and passing it to the T4 template property.

T4 Template Properties

In order to access metadata item information and create the output, your T4 script needs to specify two properties which will be populated using the Guidance PropertyProcessor engine:

<#@ property processor="PropertyProcessor" name="MetadataItem" #>

<#@ property processor="PropertyProcessor" name="TemplateConfiguration" #>

The MetadataItem property is an object implementing Sixeyed.CodeGeneration.Metadata.Interfaces.IMetadataItem:

The underlying Item property gives you access to the populated metadata item – the object type will depend on the provider, and will be specified in the ItemType property. The Key for the item (the name shown in the Select Items wizard page) is available, as is the metadata Provider which can be used to navigate up to the source.

The TemplateConfiguration property allows you to control the output of the template, setting default values for the target file name etc. (which can be overridden in the Select Template wizard page). It's an object of type Sixeyed.CodeGeneration.Generation.TemplateConfiguration:

Sample Templates

The CodeGeneration.Sample Guidance package contains a sample template for each of the metadata providers, demonstrating the type of object they expose and how it can be used. The scripts don't do much other than demonstrate usage, but there are fully-fledged scripts for generating wrappers for SQL Server stored procedures, and configuration sections from text files. The full script for the Table provider sample makes straightforward use of the underlying DataTable object:

<#@ template language="C#" #>

<#@ property processor="PropertyProcessor" name="MetadataItem" #>

<#@ property processor="PropertyProcessor" name="TemplateConfiguration" #>

<#@ assembly name="System.dll" #>

<#@ assembly name="System.Data.dll" #>

<#@ assembly name="System.Xml.dll" #>

<#@ assembly name="Sixeyed.CodeGeneration.dll" #>

<#@ import namespace="System.Data" #>

<#@ import namespace="Sixeyed.CodeGeneration.Generation" #>

<# PrepareOutput(); #>

Table name (from metadata): <#= MetadataItem.Key #>

Table name (from table): <#= dataTable.TableName #>

Columns:

<# foreach (DataColumn column in dataTable.Columns)

{

#>Column Name: <#= column.ColumnName #>

Data Type: <#= column.DataType #>

<#} #>

<#+

private DataTable dataTable

{

get{ return MetadataItem.Item as DataTable; }

}

private void PrepareOutput()

{

TemplateConfiguration.ClassName = string.Format("Table_{0}", MemberName.ToPascalCase(MetadataItem.Key, true));

TemplateConfiguration.FileExtension = "cs";

}

(If you don't already have it, the T4 Editor Community Edition from Clarius makes editing templates much easier).

The directives specify the expected properties, and import the relevant reference assemblies and namespaces. The script provides the dataTable property to easily access the metadata item as a typed DataTable object. In the PrepareOutput method (called at the start of the template), the script sets up the target class name and file extension. In this case a target filename is not specified, so the engine will use the class name and file extension for the filename. Note there are some helper methods in Sixeyed.CodeGeneration.Generation.MemberName for preparing valid member names.

Selecting a single table called Manufacturers for this script generates and adds a file called Table_Manufacturers.cs to the selected project, containing the following output:

Table name (from metadata): Manufacturers

Table name (from table): Manufacturers

Columns:

Column Name: ManufacturerId

Data Type: System.Int16

Column Name: ManufacturerName

Data Type: System.String

Column Name: AvailableFromDate

Data Type: System.DateTime

Column Name: AvailableToDate

Data Type: System.DateTime

Usage

For ad-hoc code generation, this basic Guidance package lets you specify metadata to execute against a T4 template. For commonly used scripts and standard patterns you can build a custom Guidance package which contains your solution structure, and specific recipes for generating known types of item – for DAL classes, entities, configuration sections, proxies or anything else that is based on external metadata.

Creating Shortcuts in MSBuild

EltonStoneman — Sat, 25 Oct 2008 00:13:52 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

Windows shortcuts are .LNK files – a proprietary binary format which is not simple to generate. If you want to create shortcuts as part of an MSBuild deployment, the main issue is that the paths are not relative, they need to be explicit, so you can't create your own shortcuts and copy them. Alternatives are to create .URL or batch files containing relative paths, but they don't have the niceties of shortcuts.

You can generate .LNK shortcuts in MSBuild by shelling out to some VBScript at runtime, when you've deployed your files and know the exact paths. It's not a pretty solution, but it's fast and reliable. Create a .VBS file with the following content to generate a shortcut from given parameters:

'CreateShortcut.vbs

'Generates a .LNK shortcut to the specified program

'Usage: CreateShortcut.vbs <pathToExe> <exeName> <shortcutName>

Dim args, arg

Set args = WScript.Arguments

Dim workingDirectory, exeName, shortcutName

workingDirectory=args(0)

exeName=args(1)

shortcutName=args(2)

Dim WshShell

Set WshShell = WScript.CreateObject("WScript.Shell")

Dim objLink

Set objLink = WshShell.CreateShortcut("Shortcuts\" & shortcutName & ".lnk")

objLink.Description = shortcutName

objLink.TargetPath = workingDirectory & "\" & exeName

objLink.WindowStyle = 1

objLink.WorkingDirectory = workingDirectory

objLink.Save

Then call it from MSBuild after you've deployed the target file and know the path:

Points to note:

If you have any spaces in the arguments (C:\Program Files\etc) you need to wrap them in triple double-quotes ("""C:\Program Files\etc"""), otherwise each word is parsed as a separate argument in VBScript;
The friendly name of the shortcut can end in any extension – Windows hides the final .LNK , so if you specify a .EXE it will display as an EXE;
Shortcuts aren't limited to executables, if you pass a Word file as the exeName argument and end the shortcutName with .DOC, it'll launch the document in Word and show it with the Word icon in Explorer;
You have a lot of control over the link from the CreateShortcut call – including the startup window type, arguments and the icon. The example above is a straightforward one which just sets the minimum necessary.

Quick registration of Package in progress… This may take a while

EltonStoneman — Wed, 15 Oct 2008 05:33:47 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The Guidance Automation Extensions Toolkit (see GAX Toolkit) gives you this lovely message when you use the "Quick Register" action in your GAX package development. It's true that it can take a while, although it's substantially quicker than the full registration action.

When you're in development though, solutions using your GAX package will read the contents from the project's bin\Debug, so you may not need to re-register between builds at all. Experiments with registration types suggest that they need to be used in the following situations:

Full Register – needed the first time you register the package, and may be needed following an Unregister if the package has been corrupted or isn't functioning as expected. Takes several minutes and does a variety of interesting things (check Task Manager while it's running); builds the solution and validates package XML before deploying.
Quick Register – may take a while, but usually in the order of tens of seconds rather than minutes. Also builds the solution and validates the package XML, but doesn't do the full suite of registration tasks. Not necessary in normal use, although if you've modified the XML it's worth having it validated before trying to use it.
No registration – in dev, the package is read from bin\Debug, so if you're adding or modifying templates, you can just rebuild and they'll be immediately available. Similarly if you change or add to the code in the project or dependencies, close any solutions using the GAX package and rebuild and the changes will take effect when you re-open. Interestingly, if you modify the XML – e.g. to add a new action – you can also just rebuild and not register, and the new action will be listed when you open a solution using the package. If not, disable then re-enable the package, and the new action should appear.

Obviously this only applies in dev, and if you deploy your GAX package using the MSI, you'll need to redeploy in full for changes to take effect. Useful to know though, and may mean your GAX development takes less of a while.

ExecuteT4Template MSBuild task: Updated

EltonStoneman — Sat, 04 Oct 2008 14:14:31 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

As Cory pointed out, my original task to execute T4 templates under MSBuild (replacing property markers in the T4 script with evaluated values from the build, see: An MSBuild task to execute T4 templates), fails under MSBuild 3.5. This is down to a change in the object model in the framework. All the useful classes are internal and all the useful properties are private, so they have to be reflected over - which makes my code brittle.

I've updated the task as part of a set here: Sixeyed MSBuild tasks, and it now works with either MSBuild 2.0 or 3.5.

Another update will be coming soon, to allow you to use named item group values, as well as property values and whole item groups in the script. A script can be marked with %(Collection.Identity) and when the task is called iteratively over a collection, the script will be populated with the current collection value each time. I'm also planning to change it to use the T4 engine directly rather than invoking the TextTransform console app, to hopefully speed up the execution time.

I'm using this task increasingly in builds now. It's a lot neater than having multiple XML or Regex file updates, and the template can be used to isolate logic so the builds stay clean. Currently it's used to dynamically generate Wix scripts, generate BizTalk bindings file for a set of environments, generate documentation projects for Sandcastle Help File Builder and produce config files for running DevPartner code coverage. Some of those templates may be generically useful, so I'll add them to MSDN when I get to the next update.

An MSBuild task to execute T4 templates

EltonStoneman — Fri, 25 Jul 2008 18:54:23 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

I was looking for an MSBuild task which could execute a T4 template, replacing tags in the template with the value of properties or item groups from the build - giving your T4 templates access to all the runtime values used in the build scripts. So you start with a T4 template like this:

<#@ template language="C#" #>

<#@ output extension=".txt" #>

<#@ assembly name="System.dll" #>

***START

Property value: StartDir= $(StartDir)

Item Group value: TextFiles = @(TextFiles)

***END

- execute it through a call to ExecuteT4Template in your build target:

</PropertyGroup>

</ItemGroup>

</Target>

- and it produces the following output:

***START

Property value: StartDir= C:

Item Group value: TextFiles = \zeros.txt

***END

There wasn't one that I could find so I put a simple one together. A couple of fiddly things worth noting if you do something similar:

the project's property values are not exposed to the executing task in an accessible way, so you have to reflect around BuildEngine to get hold of the executing project;
if you don't want to write an ITextTemplatingEngineHost or rely on a GAX or other host, you'll end up shelling out to TextTransform.exe (as I have).

Full source for the task is here: ExecuteT4Template.cs (note this uses version 1.1 of the TextTransform tool).

A couple of things to note: this task will update all instances of property and item tags in the template - $(propertyName) or @(itemGroupName) (it's not clever enough to deal with %(itemGroupName.ValueName))- with the value from MSBuild, if the named property/item group exists in the project. Potentially you may want to leave certain tags in place in the template, in which case you'll need to ensure there are no matching properties in the build, or extend the task to take a list of names to ignore.

Also, if you're using a value in your script which is the output from another task, then the task which produces the output must be in a separate target which completes before the call to ExecuteT4Template. MSBuild seems only to store properties/item groups from task outputs when targets are completed, so if the output is created in the same target as the T4 task, the property won't be registered and the tag in the template won't be replaced.

I have a couple of other tasks which all relate to deploying BizTalk and ESB Service Providers, so I'll add them to the ESBSimpleSamples CodePlex project along with this one.

Scripting Branch Creation in Perforce

EltonStoneman — Fri, 04 Apr 2008 16:17:40 GMT

To simplify the branching process, allow automation and remove the errors likely from manually branching, I'd like the whole process to be scripted. The P4 command allows us to do this, but there are complications as it requires user input via the specification forms for most of its commands. You can direct it to read the input from a file, but that's not much help when you want to use variables to specify branch names etc.

Generating Specification Forms on the Fly

My solution was to create a simple console app to generate spefication forms based on input parameters. The variables in the script go into the generator which stores them as files, which P4 can use as input. It's not terribly elegant, but it's efficient and I haven't found any other solutions out there. The code is on CodePlex here: Generate Perforce Specification Form

Using the console app, it's easy to take the manual steps from Branching with Perforce and script them for automation. In this case, I'm expecting branching to be an occassional job so the purpose of scripting it is to reduce the possibility of error and simplify the branching process for anyone who needs to do it and doesn't want to trawl through these blogs.

With this in mind, the script is a Windows batch file (the full script is BranchWorkspace.bat in the Samples directory of the CodePlex source) rather than a build task. It should be straightforward to read, but I'll dissect it here to show how the commands fit in with the manual process.

Walkthrough

Firstly the batch file sets up parameters for all the variables we'll use - branch name, branch master workspace name, views etc. Then it follows the same order as the manual process, generating the specification forms where needed, then invoking the P4 command and telling it to read from the spec form.

1. Create the branch view

::generate spec form for the branch:
set branchSpecPath=C:\%branchName%.p4
GenerateP4SpecForm "WRITE" "%branchSpecPath%" "|" "Branch: %branchName%|Owner: elton.stoneman|Description: Created by elton.stoneman.|Options: unlocked|View: %mainView% %branchView%"

The console app takes parameters telling it where to create the spec form, how the form options are separated (I use a pipe as there are colons in the options), and then the pipe-separated option list.

What goes into the list depends on the type of spec form P4 wants; there are samples in the CodePlex source, or you can copy and paste from a real spec form, or many of the commands take a -o parameter so you can output an existing spec form and use that as the basis.

::create the branch view:
p4 branch -i <%branchSpecPath%
- the branch view is created and we pass the spec form path to P4 so there's no user intervention.

2. Create the master workspace

As before, generate the relevant spec form and pass it into P4:

::generate spec form for the branch master workspace:
set branchClientSpecPath=C:\%branchClient%.p4
GenerateP4SpecForm "WRITE" "%branchClientSpecPath%" "|" "Client: %branchClient%|Owner: elton.stoneman|Host: myHost|Description: Created by elton.stoneman.|Root: %branchClientRoot%|Options: noallwrite noclobber nocompress unlocked nomodtime normdir|SubmitOptions: submitunchanged|LineEnd: local|View: %branchView% %branchClientView%"

::create branch workspace:
p4 client -i <%branchClientSpecPath%

3. Flag files to be branched

No spec form needed here, but the batch file allows you to branch from the current revisions or from a specified label:

::integrate the branch back to main - branch to label if provided:
IF "%label%"==" " p4 -c%branchClient% integrate -b %branchName%
IF NOT "%label%"==" " p4 -c%branchClient% integrate -b %branchName% @%label%

4. Submit the change list

This is a bit different as the submit command launches a spec form listing the files to be submitted, and requires you to add a description. We can't generate the spec form here, as we'll lose the file list, so instead we output the file list first:

::get a list of the changes (required for Submit):
set changePath=c:\%branchClient%.chg
p4 -c%branchClient% change -o >%changePath%

- and then use the UPDATE mode of the console app to set the description (P4 always uses the same text for the default description):

IF "%label%"==" " GenerateP4SpecForm "UPDATE" "%changePath%" "<enter description here>" "MASTER created from branch: %branchName%"
IF NOT "%label%"==" " GenerateP4SpecForm "UPDATE" "%changePath%" "<enter description here>" "MASTER created from branch: %branchName%, label: %label%"

This way we get the full change list from Perforce and add in our description (in this case, specifying the branch view and label used to get the files). Now we submit using the updated change list:

::submit to create branch in depot:
p4 -c%branchClient% submit -i <%changePath%

And the branch is complete and populated.

Note, the sample batch file leaves the generated spec forms in place, in case of any issues. It's a simple change to make the script delete them at the end.