Using Dynamic Properties

It is possible to implement custom targets in a help file builder project that create or set properties and make them available for tag substitution during the build. Normally such new or updated property values are not available to the help file builder task. However, by adding their values to the SubstitutionTags property in the project, the dynamic properties can be passed to the help file builder task and the new or updated values will be used. This method works whether the project is built using MSBuild from the command line or on a build server or from within Visual Studio.

This example runs a custom third-party task during the build to update the help file version and add various other properties related to a specific Git commit. These elements are added to the end of the help file builder project file.

The dynamic properties are set as the value of the SubstitutionTags property. The property names within it can then be used in the values of other help file builder project properties. When built, those properties will be replaced with their values at the time of the build. For example, you could enter the value "Version {@HelpFileVersion}, Git Commit ID: {@GitCommitId}" in the Additional footer text property to show the version number and Git commit ID in the footer of each page.

 
<PropertyGroup>
  <!-- Add the custom target so that it runs before the help file is built-->
  <BuildDependsOn>
    GetBuildGitVersion;
    $(BuildDependsOn)
  </BuildDependsOn>
</PropertyGroup>

<!-- Define the target and its properties -->
<Target Name="GetBuildGitVersion" Returns="$(BuildVersion)">
  <Nerdbank.GitVersioning.Tasks.GetBuildVersion
    BuildingRef="$(_NBGV_BuildingRef)"
    BuildMetadata="@(BuildMetadata)"
    DefaultPublicRelease="$(PublicRelease)"
    GitRepoRoot="$(GitRepoRoot)">

    <Output TaskParameter="Version" PropertyName="BuildVersion" />
    <Output TaskParameter="AssemblyInformationalVersion" PropertyName="HelpInformationalVersion" />
    <Output TaskParameter="AssemblyFileVersion" PropertyName="HelpFileVersion" />
    <Output TaskParameter="SimpleVersion" PropertyName="BuildVersionSimple" />
    <Output TaskParameter="PrereleaseVersion" PropertyName="PrereleaseVersion" />
    <Output TaskParameter="MajorMinorVersion" PropertyName="MajorMinorVersion" />
    <Output TaskParameter="AssemblyVersion" PropertyName="AssemblyVersion" />
    <Output TaskParameter="GitCommitId" PropertyName="GitCommitId" />
    <Output TaskParameter="GitCommitIdShort" PropertyName="GitCommitIdShort" />
    <Output TaskParameter="GitVersionHeight" PropertyName="GitVersionHeight" />
    <Output TaskParameter="BuildNumber" PropertyName="BuildNumber" />
    <Output TaskParameter="BuildNumber" PropertyName="BuildVersionNumberComponent" />
    <Output TaskParameter="PublicRelease" PropertyName="PublicRelease" />
    <Output TaskParameter="CloudBuildNumber" PropertyName="CloudBuildNumber" Condition="
      '$(CloudBuildNumber)' == '' "/>
    <Output TaskParameter="BuildMetadataFragment" PropertyName="SemVerBuildSuffix" />
    <Output TaskParameter="NuGetPackageVersion" PropertyName="NuGetPackageVersion" />
    <Output TaskParameter="NPMPackageVersion" PropertyName="NPMPackageVersion" />
    <Output TaskParameter="CloudBuildVersionVars" ItemName="CloudBuildVersionVars" />
  </Nerdbank.GitVersioning.Tasks.GetBuildVersion>

  <PropertyGroup>
    <!-- Add the dynamic properties as the value of the SubstitutionTags property -->
    <SubstitutionTags>$(SubstitutionTags);HelpInformationalVersion=$(HelpInformationalVersion);
      HelpFileVersion=$(HelpFileVersion);Version=$(BuildVersion);GitCommitId=$(GitCommitId);
    </SubstitutionTags>
  </PropertyGroup>
</Target>

See Also