MintPlayer.TokenReplacer.Targets 1.0.0

MintPlayer.TokenReplacer.Targets

Generic MSBuild token replacement. Declare which files contain $token$ placeholders and where the values come from (literals, MSBuild properties, resolved NuGet package versions); at build time the tokens are replaced and the result written to an output file. Ships buildTransitive targets, so package authors can use it to stamp their own package version into assets they ship — with zero configuration for their consumers.

Installation

dotnet add package MintPlayer.TokenReplacer.Targets

Usage in a project

<ItemGroup>
  <PackageReference Include="MintPlayer.TokenReplacer.Targets" Version="1.0.0" />
</ItemGroup>

<ItemGroup>
  
  <TokenReplaceValue Include="version" Value="$(Version)" />
  <TokenReplaceValue Include="buildConfig" Value="$(Configuration)" />

  
  <TokenReplacePackageVersion Include="Some.Cdn.Library" TokenName="cdnVersion" />

  
  <TokenReplaceFile Include="wwwroot\index.template.html"
                    OutputFile="$(IntermediateOutputPath)tokenreplacer\index.html"
                    IncludeAs="Content" CopyToOutputDirectory="PreserveNewest" Link="wwwroot\index.html" />
</ItemGroup>

index.template.html containing

<script src="https://cdn.example.com/lib@$cdnVersion$/loader.js"></script>

is materialized with the actual resolved version of Some.Cdn.Library, the build configuration and your project version filled in.

Usage by package authors (stamp your own package version)

Reference this package without PrivateAssets="all" (it must flow to your consumers), ship your asset template, and add a thin buildTransitive/<YourPackage>.targets:

<Project>
	<PropertyGroup>
		
		<_MyPackageVersion>$([System.IO.Path]::GetFileName($([System.IO.Path]::GetDirectoryName($([System.IO.Path]::GetDirectoryName($(MSBuildThisFileDirectory)))))))</_MyPackageVersion>
	</PropertyGroup>
	<ItemGroup>
		<TokenReplaceValue Include="version" Value="$(_MyPackageVersion)" />
		<TokenReplaceFile Include="$(MSBuildThisFileDirectory)..\content\web-loader.template.js"
		                  OutputFile="$(IntermediateOutputPath)tokenreplacer\web-loader.js"
		                  IncludeAs="Content" CopyToOutputDirectory="PreserveNewest" Link="web-loader.js" />
	</ItemGroup>
</Project>

Every project that references your package then automatically gets web-loader.js with $version$ replaced by the exact version of your package that NuGet restored.

Reference

Items

Properties

Behavior

• Write-if-changed: outputs are only rewritten when content actually changed.
• Incremental: the replacement target is skipped when outputs are newer than the templates/project files.
• Clean-aware: generated files are registered as FileWrites and removed by dotnet clean (note: MSBuild only tracks files under bin/obj for Clean; outputs elsewhere are left alone).
• UTF-8 with BOM preservation (a template with a BOM produces output with a BOM).
• Token names match [A-Za-z0-9_.-]+ and are case-insensitive; $(Property) constructs are never treated as tokens.

License

Apache-2.0