** Moved to GitHub **

Configuration

MSBuild Properties

White Tie offers several MSBuild properties with sensible default values. Any of White Tie's properties can be overridden in your project file or as global parameters passed to the MSBuild program directly.

$(SolutionDir)
A string property referring to the full path of the directory containing the solution (.sln) file.
  • This property is normally undefined when building outside of Visual Studio; however, White Tie ensures that it is assigned. (Note: It is assumed that WhiteTie.props is located under your solution's packages folder at its default location, as installed by NuGet. Changing the location of WhiteTie.props or the location of the packages folder may cause White Tie to fail.)
$(SourceDir)
A string property referring to the full path of the solution's Source directory.

$(BuildDir)
A string property referring to the full path of the solution's Build directory.

$(DeploymentDir)
A string property referring to the full path of the solution's Deployment directory.

$(TestingDir)
A string property referring to the full path of the solution's Testing directory.

$(NuGetDir)
A string property referring to the full path of the solution's .nuget directory.
  • The .nuget directory is created automatically by Visual Studio when the NuGet Package Restore feature is enabled for the solution. (Only required in Visual Studio 2013.)
$(PreRelease)
A string property indicating whether a pre-release version is being built and its name.
  • Any value is permitted; e.g., Alpha, Beta, RC, Private, etc.
  • This property is automatically assigned if a semantic version string is specified in the AssemblyInformationalVersionAttribute of the output assembly; e.g., 1.4.0-Alpha
  • Any non-empty value effects the version of the NuGet package and whether compiled documentation is marked as preliminary.
$(StaticAnalysisEnabled)
A boolean property that enables static analysis; e.g., FxCop, StyleCop and Code Contracts.
  • Only static analysis tools that are already installed are executed.
  • Specifying this property overrides a corresponding setting for each tool in the project file. Therefore, setting this property to True enables all static analysis. Setting it to False disables all static analysis. Omitting it causes each tool to inherit its specific setting from the project file.
  • This property is automatically set to True when the Configuration property equals Release. Other configurations will inherit settings from the project file.
$(DeploymentEnabled)
A boolean property that allows the Deploy, DeployPackage and CleanDeploy targets to execute.
  • This property is automatically set to True when the Configuration property equals Release.
$(BuildDocumentationEnabled)
A boolean property that indicates whether the BuildDocumentation target can be executed.
  • This property is automatically set to True when Sandcastle is installed and the Configuration property equals Release.
$(BuildPackage)
A boolean property that causes a NuGet package to be built as part of the project's output.
  • Building a NuGet package requires NuGet Package Restore to be enabled on the solution in Visual Studio 2013 only. In Visual Studio 2015, White Tie automatically downloads NuGet.exe before building the package.
  • A .nuspec file is generated automatically from the properties listed below. NuGet replacement tokens are used as some of the default values. White Tie derives these tokens from attributes in the output assembly.
  • This property is automatically set to True when the Configuration property equals Release.
$(PackageReferencedProjects)
A boolean property that indicates whether to generate dependencies from project references.
  • The default value is True.
  • A reference to a project that uses White Tie and generates a package is added as a dependency.
  • A reference to a project that does not use White Tie or does not generate a package is automatically merged into the NuGet package that is created for the current project.
$(PackageSymbols)
A boolean property that indicates whether the NuGet package will include .pdb files, when available, for assemblies in the 'lib' folders.
  • The default value is False for Release builds and True for Debug builds.
$(PackageXmlDocumentation)
A boolean property that indicates whether the NuGet package will include .xml documentation files, when available, for assemblies in the 'lib' folders.
  • The default value is True.
$(PackageCompiledDocumentation)
A boolean property that indicates whether the NuGet package will include .chm documentation files, when available, for assemblies in the 'lib' folders.
  • The default value is True.
$(PackageContent)
A boolean property that indicates whether the NuGet package will include Content items, when available.
  • The default value is False.
NuSpec Properties
The following properties are used to generate a .nuspec file when $(BuildPackage) equals True.

Property Default Value
$(NuSpecId) $id$
$(NuSpecVersion) $version$
$(NuSpecTitle) $title$
$(NuSpecAuthors) $author$
$(NuSpecOwners) $author$
$(NuSpecDescription) $description$
$(NuSpecReleaseNotes)
$(NuSpecSummary) $product$
$(NuSpecLanguage) en-us
$(NuSpecProjectUrl)
$(NuSpecIconUrl)
$(NuSpecLicenseUrl)
$(NuSpecCopyright) $copyright$
$(NuSpecRequireLicenseAcceptance) false
$(NuSpecTags)
$(NuSpecDevelopmentDependency) false

Documentation Properties
The following properties are used to generate documentation when $(BuildDocumentationEnabled) equals True.

Property Description Default Value
$(DocumentationProjectName) Name of project. Value of AssemblyTitleAttribute
$(DocumentationProductName) Name of product. Value of AssemblyProductAttribute
$(DocumentationCompanyName) Name of company. Value of AssemblyCompanyAttribute
$(DocumentationCopyright) Copyright string. Value of AssemblyCopyrightAttribute
$(DocumentationVersion) Product version. Value of AssemblyVersionAttribute
$(DocumentationProjectSummary) Project summary string.
$(DocumentationRootTopicEnabled) Generates a topic container. True
$(DocumentationRootTopicTitle) Title of the root container. Namespaces
$(DocumentationFeedbackEmail) Email address for feedback.
$(DocumentationFeedbackLinkText) Email link text for feedback. Send Feedback to $(DocumentationCompanyName)
$(DocumentationHeader) Header string for all topics.
$(DocumentationFooter) Footer string for all topics. Updated on $([System.DateTime]::Today.ToString('D'))
$(DocumentationStyle) Name of presentation style. VS2013
$(DocumentationLanguage) Language identifier. en-US

MSBuild Items

@(Deploy)
Provides additional items for local deployment.
  • Project output and Content items are automatically included for deployment, so there's no need to add them to @(Deploy).
  • DeployTarget metadata is optional. The default value is the root deployment directory and the original filename.
  • DeployTarget metadata may be specified relative to the root deployment directory.
Example:
<Deploy Include="$(BuildDir)Extras\License.txt">
    <DeployTarget>Extras\License.txt</DeployTarget>
</Deploy>

@(NuGetPackage)
Additional files to be embedded in the NuGet package.
  • Include path must be specified relative to the project directory.
  • PackageTarget metadata is optional. The default value is lib.
  • When PackageTarget is lib, assemblies are automatically placed into an appropriate Framework subfolder based on the project's target framework. Portable libraries are also supported.
  • PackageTarget metadata must be specified relative to the NuGet package's root.
  • Exclude metadata is optional.
Example:
<NuGetPackage Include="$(BuildDir)tools\*.ps1">
    <PackageTarget>tools</PackageTarget>
    <Exclude>$(BuildDir)tools\not_for_nuget.ps1</Exclude>
</NuGetPackage>

@(NuGetDependency)
Dependencies to be embedded in the NuGet package.
  • Version metadata is required.
Example:
<NuGetDependency Include="Rx-Main">
    <Version>2.1.30214.0</Version>
</NuGetDependency>

@(NuGetFlavor)
Project references whos output is to be embedded in the current project's NuGet package as additional target framework flavors. Note that including a project as a NuGetFlavor may cause the build order to change, regardless of the build order configuration in Visual Studio.
  • Projects that are referenced directly via ProjectReference items can not be included as NuGetFlavor items.
  • Referenced assemblies, contract assemblies, documentation files and symbols are also included (subject to the states of the various Package* properties above.
Example:
<NuGetFlavor Include="..\other\other.csproj" />

@(DocumentationContent)
Files to be included in the output of the BuildDocumentation target.
  • ExcludeFromToc metadata is optional.
Example:
<DocumentationContent Include="$(BuildDir)Extras\License.txt">
    <ExcludeFromToc>False</ExcludeFromToc>
</DocumentationContent>

@(DocumentationImage)
Images to be included in the output of the BuildDocumentation target.
  • ImageId metadata is optional. The default value is the name of the file without its extension.
  • AlternateText metadata is optional. The default value is empty.
Example:
<DocumentationImage Include="Images\Example.png">
    <ImageId>Example1</ImageId>
    <AlternateText>Example #1</AlternateText>
</DocumentationImage>

@(DocumentationNamespace)
Reference documentation for individual namespaces.
  • Summary metadata is optional. The default value is empty, which causes the namespace to be excluded.
Example:
<DocumentationNamespace Include="MyApi.MyNamespace">
    <Summary>Contains my API's types.</Summary>
</DocumentationNamespace>

@(DocumentationSource)
Additional managed assemblies and documentation files to be included in the reference documentation.
  • Project output is included by default, so there's no need to add it to DocumentationSource.
  • Project references are included by default, so there's no need to add them to DocumentationSource.
Example:
<DocumentationSource Include="DocSources\Another.dll" />

@(DocumentationReference)
Additional managed assembly references.
  • Assembly references are included by default, so there's no need to add them to DocumentationReference.
Example:
<DocumentationReference Include="Refs\Dependency.dll" />

@(DocumentationFrameworkReference)
Additional named references, typically found in the GAC.
  • Framework references are included by default, so there's no need to add them to DocumentationFrameworkReference.
Example:
<DocumentationFrameworkReference Include="OtherSoft.GAC.Utils, Version=1.0.0.0" />

MSBuild Targets

Deploy
Copies the project's build output and Content items to $(DeploymentDir).
  • This target automatically executes after the project's Build target runs successfully.
  • Condition: $(DeploymentEnabled) equals True.
  • Additional files can be specified in the @(Deploy) item group.
DeployPackage
Copies the project's NuGet package to $(DeploymentDir).
  • This target automatically executes after NuGet's BuildPackage target runs successfully.
  • Condition: $(DeploymentEnabled) equals True.
  • Additional files can be specified in the @(NuGetPackage) item group.
CleanDeploy
Deletes the project's entire output folder in $(DeploymentDir).
  • This target automatically executes after the project's Clean target runs successfully.
  • Condition: $(DeploymentEnabled) equals True.
BuildDocumentation
Builds reference documentation for the output assembly.
  • This target automatically executes after the Build target runs successfully, but before the Deploy target runs.
  • Condition: $(BuildDocumentationEnabled) equals True.
  • Condition: Sandcastle must be installed.
  • Additional content and configuration files can be specified in various item groups.
GetCommonAssemblyAttributes
Reflects into the output assembly, reads common assembly attributes and stores them in MSBuild properties.
  • This target is automatically executed when building documentation or a NuGet package. You can also execute it yourself at any time.
  • Executing this target causes the Build target to be executed, if it wasn't executed already.
Output properties:
  • $(TargetAssemblyVersion)
  • $(TargetAssemblyInformationalVersion)
  • $(TargetAssemblyTitle)
  • $(TargetAssemblyDescription)
  • $(TargetAssemblyConfiguration)
  • $(TargetAssemblyProduct)
  • $(TargetAssemblyCompany)
  • $(TargetAssemblyCopyright)

Last edited May 24, 2016 at 9:33 PM by davedev, version 27