repository·main·Indexed 43 days ago
https://github.com/microsoft/slow-cheetahA tool for automated XML and JSON file transformations during the MSBuild process, enabling environment-specific configurations for different build profiles. It supports XDT (XML Document Transform) and JDT (JSON Document Transform) and is provided as a NuGet package (Microsoft.VisualStudio.SlowCheetah) and a Visual Studio extension for generating and previewing transforms.
app.config) and JSON files. It is designed to facilitate environment-specific configuration management.slow-cheetah is a tool for performing transformations on XML (e.g., app.config) and JSON files during the build process. It allows you to apply different configurations based on your build configuration or publish profiles.
It consists of two main components:
slow-cheetah supports two primary file types using specific transformation languages:
SlowCheetah uses a specific sequence of targets to manage file transformations during the build process. The core workflow involves collecting files marked for transformation and then applying those transformations after files have been copied to the output directory.
ScCollectTransformFiles: Scans the project for files where TransformOnBuild is set to true. It populates the ScFilesToTransform item group with the necessary metadata. This runs before ScApplyTransforms.ScApplyTransforms: Creates the destination directories and applies the transformation task to every item in ScFilesToTransform. This runs after CopyFilesToOutputDirectory.If you encounter bugs, have feature requests, or need help using slow-cheetah, use GitHub Issues.
Before filing a new issue, search the existing issues to ensure your topic hasn't already been addressed. For new problems, file a bug report or a feature request as a new Issue.
If SlowCheetah has never been installed on your computer or used in any of your projects, simply install the latest NuGet package: Microsoft.VisualStudio.SlowCheetah.
https://www.nuget.org/packages/Microsoft.VisualStudio.SlowCheetah/If you are upgrading from an older version of SlowCheetah, you must manually clean up your project files before installing the new NuGet package and Visual Studio extension. The new version uses a NuGet package for build/transformation logic and a VS extension for UI assistance, whereas older versions relied on manual project file edits and local app data installations.
Remove the following elements from your .csproj (or equivalent) file:
<PropertyGroup Label="SlowCheetah"> block.<Import Project="$(SlowCheetahTargets)" ... /> line.<None Include="..." /> entries related to packageRestore.proj or SlowCheetah.Transforms.targets.Note: The only SlowCheetah-related lines that should remain in your project file are the transformation files themselves, which are marked with <IsTransformFile>true</IsTransformFile>.
Delete the following from your project directory:
Properties\SlowCheetah folder.packageRestore.proj file.Once the project is cleaned:
Microsoft.VisualStudio.SlowCheetah NuGet package via the NuGet Package Manager.If you no longer intend to use any older versions of SlowCheetah on your machine, you can safely delete the following folder:
%LocalAppData%\Microsoft\MSBuild\SlowCheetah
<!-- Remove this PropertyGroup -->
<PropertyGroup Label="SlowCheetah">
<SlowCheetahToolsPath>$([System.IO.Path]::GetFullPath( $(MSBuildProjectDirectory)\..\packages\SlowCheetah.2.5.15\tools\))</SlowCheetahToolsPath>
<SlowCheetah_EnableImportFromNuGet Condition=" '$(SlowCheetah_EnableImportFromNuGet)'=='' ">true</SlowCheetah_EnableImportFromNuGet>
<SlowCheetah_NuGetImportPath Condition=" '$(SlowCheetah_NuGetImportPath)'=='' ">$([System.IO.Path]::GetFullPath( $(MSBuildProjectDirectory)\Properties\SlowCheetah\SlowCheetah.Transforms.targets ))</SlowCheetah_NuGetImportPath>
<SlowCheetahTargets Condition=" '$(SlowCheetah_EnableImportFromNuGet)'=='true' and Exists('$(SlowCheetah_NuGetImportPath)') ">$(SlowCheetah_NuGetImportPath)</SlowCheetahTargets>
</PropertyGroup>
<!-- Remove this Import -->
<Import Project="$(SlowCheetahTargets)" Condition="Exists('$(SlowCheetahTargets)')" Label="SlowCheetah" />
<!-- Remove these Includes -->
<None Include="packageRestore.proj" />
<None Include="Properties\SlowCheetah\SlowCheetah.Transforms.targets" />If you are upgrading from version 2.5.15 or an earlier version, please refer to the official update guide for migration instructions and breaking changes.
https://github.com/Microsoft/slow-cheetah/blob/main/doc/update.mdThe SlowCheetah Visual Studio extension provides a UI for managing file transformations within the IDE.
To add transformations:
Add Transform option.This automatically creates transform files corresponding to your project's build configurations (e.g., Debug, Release) and any existing publish profiles.
To preview changes:
Preview Transform option to see the resulting file or the diff.To enable transformations during the build process without using the Visual Studio extension, you must install the Microsoft.VisualStudio.SlowCheetah NuGet package.
You can manually configure transformations in your project file (.csproj, .vbproj, etc.) by setting specific metadata on the files:
<TransformOnBuild>true</TransformOnBuild>.<IsTransformFile>True</IsTransformFile>.<DependentUpon> metadata pointing to the original file.This approach allows for automated transformations in environments where the Visual Studio extension is not present (e.g., CI/CD pipelines).
<None Include="App.config">
<TransformOnBuild>true</TransformOnBuild>
</None>
<None Include="App.Debug.config">
<DependentUpon>App.config</DependentUpon>
<IsTransformFile>True</IsTransformFile>
</None>
<None Include="App.Release.config">
<DependentUpon>App.config</DependentUpon>
<IsTransformFile>True</IsTransformFile>
</None>Slow Cheetah is consumed as a NuGet package. To use it in your project, install the package via the NuGet Package Manager or the .NET CLI.
dotnet add package LibraryDepending on your version of Visual Studio, install the appropriate extension from the Visual Studio Marketplace to enable transform generation and previewing: