Using the CodePlex MSBuild Tasks

CodePlex provides a set of MSBuild Tasks that provide end to end integration between your Visual Studio environment and your CodePlex project.
API files can be downloaded from here.

Please Note:

The MSBuild task requires Microsoft Visual J# Version 2.0 Redistributable. This is normally installed with Microsoft Visual Studio or can be downloaded and installed from here.

ReleaseTasks

Type class (abstract)
Assembly CodePlex.WebServices.Client.dll
Namespace CodePlex.WebServices.Client.Tasks

Description

ReleaseTasks is an abstract class that forms the base of the CodePlex MSBuild release tasks. It provides basic functionality for authorization, project and release identification. All release based build operations inherit from this class, and as such, must provide values for the required parameters defined by this class.

Constructors

Properties

[Required]
public string ProjectName { get; set; }

Gets or sets the name of the project associated with the release operation.

[Required]
public string ReleaseName { get; set; }

Gets or sets the name of the release to use for the current release task. This is used to identify the target release.

[Required]
public string User { set; }

Sets the user name portion of the credentials to use for the release operation.

[Required]
public string Password { set; }

Sets the password portion of the credentials to use for the release operation.


ReleaseTasks.CreateRelease

Type class
Assembly CodePlex.WebServices.Client.dll
Namespace CodePlex.WebServices.Client.Tasks

Description

CreateRelease provides the ability to create a new release in an existing CodePlex project when the task is executed. This automation is particularly useful when coupled with automatic project deployment.

Constructors

Properties

[Required]
public string Description { get; set; }

Gets or sets the description of the new release.

[Required]
public bool IsDefaultRelease{ get; set; }

Gets or sets a boolean indicating whether the new release will be marked as the default release for this project. When one release is marked as the default, any release previously marked as the default will relinquish that distinction.

public DateTime ReleaseDate { get; set; }

Gets or sets the target date for the new release. Must be a valid date for releases with a status other than Planned. For Planned releases, this value is ignored.

[Required]
public string ReleaseStatus { get; set; }

Gets or sets the release status for the new release. Possible values include: Planned, Released. For a complete definition,
see ReleaseStatus.

[Required]
public bool ShowOnHomePage{ get; set; }

Gets or sets a boolean indicating whether the new release will be shown on the project homepage.

[Required]
public bool ShowToPublic{ get; set; }

Gets or sets a boolean indicating whether the new release will be visible to non team members.

Sample Usage

Below is a sample MSBuild target that you can use to invoke the CreateRelease task. You can include this directly in your .csproj file, or create a valid MSBuild file to operate independently of your codebase.

First, you must specify that the MSBuild file will be using the ReleaseTasks defined in the CodePlex .Net API assembly. Place the assembly in a well-known location (such as your project's /bin folder), and add a UsingTask element:

<UsingTask TaskName="CreateRelease" AssemblyFile="CodePlex.WebServices.Client.dll" />

or

<UsingTask TaskName="CreateRelease" AssemblyName="CodePlex.WebServices.Client" />


Besides the parameters required by the base ReleaseTasks class, there are several parameters required to execute the CreateRelease task; these can come from any valid MSBuild source, such as a PropertyGroup:

<PropertyGroup>
	<ProjectName>ProjectName</ProjectName>
	<ReleaseName>1.0 Production</ReleaseName>
	<IsDefaultRelease>true</IsDefaultRelease>
	<ShowToPublic>true</ShowToPublic>
	<ShowOnHomePage>true</ShowOnHomePage>
	<Description>This is a description</Description>
	<ReleaseDate>1/1/2007</ReleaseDate>
	<ReleaseStatus>Planned</ReleaseStatus>
	<User>User</User>
	<Password>Password</Password>
</PropertyGroup>


Lastly, create a target for MSBuild to invoke, and specify all of the parameters required by both the base ReleaseTasks class, and the CreateRelease class:

<Target Name="CreateRelease">
	<CreateRelease 
		ProjectName="$(ProjectName)" 
		ReleaseName="$(ReleaseName)" 
		IsDefaultRelease="$(IsDefaultRelease)" 
		ShowToPublic="$(ShowToPublic)" 
		ShowOnHomePage="$(ShowOnHomePage)" 
		Description="$(Description)" 
		ReleaseDate="$(ReleaseDate)" 
		ReleaseStatus="$(ReleaseStatus)" 
		User="$(User)" 
		Password="$(Password)"
	></CreateRelease>
</Target>


Once you've finished, you can test your task by executing the MSBuild file in any command prompt that has the location of the .Net Framework in the Path. If you have Visual Studio installed, you can use the "Visual Studio Command Prompt" in the "Visual Studio Tools" directory under your Visual Studio application group in the Start Menu.

msbuild ProjectName.csproj /target:CreateRelease


That's it! The release you just created with the MSBuild task will be immediately available on your CodePlex project site.


ReleaseTasks.UploadFiles

Type class
Assembly CodePlex.WebServices.Client.dll
Namespace CodePlex.WebServices.Client.Tasks

Description

UploadFiles provides the ability to upload files to an existing release in a CodePlex project when the task is executed. This automation is particularly useful when coupled with automatic project deployment.

Constructors

Properties

[Required]
public ITaskItem[] ReleaseFiles { get; set; }

Gets or sets the ItemGroup collection of files to upload to the specified CodePlex project release.

Each Item in the ItemGroup collection defines a file or list of files as allowed by the built-in MSBuild wild card selection.

In addition to the file itself, there are optional Metadata elements that can be specified for each entry:

Metadata
Name A user friendly label to display instead of the file name on your project site.
MimeType The MIME type to store for the file or files being uploaded.
FileType The name of a ReleaseFileType. Possible values include: RuntimeBinary, SourceCode, Documentation and Example. For a complete definition, see ReleaseFileType.

Sample Usage

Below is a sample Target that you can use to invoke the UploadFiles task. You can include this directly in your .csproj file, or create a valid MSBuild file to operate independently.

First, you must specify that the MSBuild file will be using the ReleaseTasks defined in the CodePlex .Net API assembly. Place the assembly in a well-known location (such as your project's /bin folder), and add a UsingTask element:

<UsingTask TaskName="UploadFiles" AssemblyFile="CodePlex.WebServices.Client.dll" />

or

<UsingTask TaskName="UploadFiles" AssemblyName="CodePlex.WebServices.Client" />


Besides the parameters required by the base ReleaseTasks class, there is one parameter required to execute the UploadFiles; this can come from any valid MSBuild source, such as an ItemGroup:

<ItemGroup>
	<ReleaseFile Include="ProjectInstaller.msi">
		<FileType>RuntimeBinary</FileType>
	</ReleaseFile>
	<ReleaseFile Include="C:\Documentation\ProjectName\Documentation.txt">
		<Name>Project Documentation</Name>
		<FileType>Documentation</FileType>
		<MimeType>text/plain</MimeType>
	</ReleaseFile>
	<ReleaseFile Include="*.cs">
		<FileType>SourceCode</FileType>
		<MimeType>text/plain</MimeType>
	</ReleaseFile>
</ItemGroup>


You can also specify a PropertyGroup to handle the parameters required by the base ReleaseTasks class. Note that the release specified by the Name must exist in the project specified:

<PropertyGroup>
	<ProjectName>ProjectName</ProjectName>
	<ReleaseName>1.0 Production</ReleaseName>
	<User>User</User>
	<Password>Password</Password>
</PropertyGroup>


Lastly, create a target for MSBuild to invoke, and specify all of the parameters required by both the ReleaseTasks class, and the UploadFiles class:

<Target Name="UploadReleaseFiles" DependsOnTargets="Build">
	<UploadFiles 
		ProjectName="$(ProjectName)" 
		ReleaseName="$(ReleaseName)" 
		ReleaseFiles="@(ReleaseFile)" 
		User="$(User)" 
		Password="$(Password)"
	></UploadFiles>
</Target>


Once you've finished, you can test your task by executing the MSBuild in any command prompt that has the location of the .Net Framework in the Path. If you have Visual Studio installed, you can use the "Visual Studio Command Prompt" in the "Visual Studio Tools" directory under your Visual Studio application group in the Start Menu.

msbuild ProjectName.csproj /target:UploadReleaseFiles


That's it! The files you just uploaded with the MSBuild task will be immediately available on your CodePlex project site under the release specified. Be aware that running this task multiple times will create multiple entries for each file specified, rather than replacing the file of that name.

Last edited Mar 28, 2011 at 6:58 PM by RobinClowers, version 5