{"id":37036703,"url":"https://github.com/nil4/dotnet-transform-xdt","last_synced_at":"2026-01-14T04:22:12.400Z","repository":{"id":55888666,"uuid":"59967083","full_name":"nil4/dotnet-transform-xdt","owner":"nil4","description":"Modern .NET tools and library for XDT (Xml Document Transformation)","archived":true,"fork":false,"pushed_at":"2020-12-09T17:27:15.000Z","size":193,"stargazers_count":118,"open_issues_count":0,"forks_count":13,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-12-31T20:54:07.074Z","etag":null,"topics":["cli","dotnet-cli","global-tool","netstandard20","transformation","xdt","xml"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nil4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-29T22:46:55.000Z","updated_at":"2025-10-21T21:35:27.000Z","dependencies_parsed_at":"2022-08-15T08:40:40.262Z","dependency_job_id":null,"html_url":"https://github.com/nil4/dotnet-transform-xdt","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/nil4/dotnet-transform-xdt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nil4%2Fdotnet-transform-xdt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nil4%2Fdotnet-transform-xdt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nil4%2Fdotnet-transform-xdt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nil4%2Fdotnet-transform-xdt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nil4","download_url":"https://codeload.github.com/nil4/dotnet-transform-xdt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nil4%2Fdotnet-transform-xdt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28409451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","dotnet-cli","global-tool","netstandard20","transformation","xdt","xml"],"created_at":"2026-01-14T04:22:11.609Z","updated_at":"2026-01-14T04:22:12.384Z","avatar_url":"https://github.com/nil4.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dotnet-xdt [![AppVeyor build](https://ci.appveyor.com/api/projects/status/559na9y3iswe9hbh/branch/master?svg=true)](https://ci.appveyor.com/project/nil4/dotnet-transform-xdt/branch/master) ![GitHub Actions build](https://github.com/nil4/dotnet-transform-xdt/workflows/CI/badge.svg)\r\n\r\nTools and library for applying [XML Document Transformations](https://msdn.microsoft.com/en-us/library/dd465326.aspx)\r\nto e.g. .NET configuration files, or any other XML-structured content.\r\n\r\n### \u003ca name=\"dotnet-xdt-tool\"\u003e\u003c/a\u003e Global tool for .NET Core 2.1 and later  [![NuGet package](https://img.shields.io/nuget/dt/dotnet-xdt.svg)](https://www.nuget.org/packages/dotnet-xdt/)\r\n\r\n.NET Core 2.1 introduces the concept of [global tools](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools),\r\nmeaning that you can install `dotnet-xdt` using the .NET CLI and use it everywhere. One advantage of this approach\r\nis that you can use the same command, for both installation and usage, across all platforms.\r\n\r\n\u003e :warning: To use global tools, .Net Core SDK 2.1.300 or later is required.\r\n\r\nInstall `dotnet-xdt` as a global tool (only once):\r\n\r\n```cmd\r\ndotnet tool install --global dotnet-xdt --version 2.2.1\r\n```\r\n\r\nAnd then you can apply XDT transforms, from the command-line, anywhere on your PC, e.g.:\r\n\r\n```shell\r\ndotnet xdt --source original.xml --transform delta.xml --output final.xml\r\n```\r\n\r\nGlobal tools are not ideal when an application needs to build completely self-contained,\r\nwithout relying on tools installed in the surrounding environment. They are also only\r\navailable on the latest .NET Core.\r\n\r\nRead on if this is a concern for your application.\r\n\r\n### \u003ca name=\"dotnet-transform-xdt-tool\"\u003e\u003c/a\u003e Project tool for .NET Core 2.0 and earlier\r\n\r\n.NET Core 2.0 and earlier do not support global tools.\r\n\r\nThe \"classic\" version of this tool, however, *can* be installed as a\r\n[project-level tool](https://docs.microsoft.com/en-us/dotnet/core/tools/extensibility#per-project-based-extensibility)\r\non both the latest .NET Core, as well as on previous versions.\r\n\r\nThe tradeoff is that in this usage model, the tool can only be invoked\r\nvia `dotnet transform-xdt`, and only from the folder of the project that references it.\r\n\r\nSee the [project-level `dotnet-transform-xdt` tool](#legacy) section\r\nbelow for details. [A separate repository](https://github.com/nil4/xdt-samples/) provides a\r\nfew self-contained sample projects that use `dotnet-transform-xdt`\r\nfor Web.config transformations at publish time.\r\n\r\n### \u003ca name=\"dotnet-xdt-exe\"\u003e\u003c/a\u003eStandalone executable for Windows\r\n\r\nYou can also download a standalone `dotnet-xdt.exe` that runs on any Windows PC with .NET\r\nFramework 4.6.1 installed. It has no external dependencies, nor does it require .NET Core.\r\nIt *might* run on Mono, but this scenario is not tested.\r\n\r\nDownload the latest build of `dotnet-xdt.exe` from the [releases page](https://github.com/nil4/dotnet-transform-xdt/releases).\r\n\r\n### \u003ca name=\"dotnet-xdt-lib\"\u003e\u003c/a\u003e.NET Standard 2.0 library [![NuGet package](https://img.shields.io/nuget/dt/DotNet.Xdt.svg)](https://www.nuget.org/packages/DotNet.Xdt/)\r\n\r\nFor complete flexibility, reference the cross-platform `DotNet.Xdt` NuGet package in your application:\r\n\r\n```cmd\r\ndotnet add package DotNet.Xdt --version 2.2.1\r\n```\r\n\r\nYou can apply XDT transforms to any XML file, or other XML sources that can be read from\r\nand written to a .NET `Stream`.\r\n\r\nDefine a class `MyXdtLogger` that implements `IXmlTransformationLogger`.\r\nThen, apply transformations using code similar to:\r\n\r\n```csharp\r\nvar document = new XmlTransformableDocument { PreserveWhitespace = true };\r\n\r\nusing (var sourceStream = File.OpenRead(sourceFilePath))\r\nusing (var transformStream = File.OpenRead(transformFilePath))\r\nusing (var transformation = new XmlTransformation(transformStream, new MyXdtLogger()))\r\n{\r\n    document.Load(sourceStream);\r\n    transformation.Apply(document);\r\n}\r\n\r\nusing (FileStream outputStream = File.Create(outputFilePath))\r\nusing (var outputWriter = XmlWriter.Create(outputStream, new XmlWriterSettings { Indent = true }))\r\n{\r\n    document.WriteTo(outputWriter);\r\n}\r\n```\r\n\r\n## \u003ca name=\"legacy\"\u003e\u003c/a\u003e Project-level `dotnet-transform-xdt` tool [![NuGet package](https://img.shields.io/nuget/dt/Microsoft.DotNet.Xdt.Tools.svg)](https://www.nuget.org/packages/Microsoft.DotNet.Xdt.Tools/)\r\n\r\n*`dotnet-xdt` is a [global tool](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools) that can only be installed on .NET Core 2.1 or later.*\r\n\r\n**`dotnet-transform-xdt`** is an alternative version that can be installed\r\nas a project-level tool, on all .NET Core versions.\r\n\r\n### \u003ca name=\"msbuild\"\u003e\u003c/a\u003e Use with MSBuild/csproj tooling\r\n\r\n**Note**: if you are using project.json tooling (CLI 1.0.0 preview 2 or earlier, or Visual Studio 2015),\r\nplease refer to the [project.json section below](#project-json).\r\n\r\nRun `dotnet --version` in a command prompt and make sure you're using version **`2.0.0`** or later.\r\n\r\nCreate a new folder (`XdtSample`) and run `dotnet new web` inside it. Verify that the files\r\n`XdtSample.csproj` and `web.config` file are present. Create a new file named `Web.Release.config`\r\ninside that folder and set its content to:\r\n\r\n```xml\r\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\r\n\u003cconfiguration xmlns:xdt=\"http://schemas.microsoft.com/XML-Document-Transform\"\u003e\r\n  \u003csystem.webServer\u003e\r\n    \u003caspNetCore\u003e\r\n      \u003cenvironmentVariables xdt:Transform=\"Insert\"\u003e\r\n        \u003cenvironmentVariable name=\"DOTNET_CLI_TELEMETRY_OPTOUT\" value=\"1\" /\u003e\r\n      \u003c/environmentVariables\u003e\r\n    \u003c/aspNetCore\u003e\r\n  \u003c/system.webServer\u003e\r\n\u003c/configuration\u003e\r\n```\r\n\r\nWe will use this sample XDT file to add an environment variable that disables dotnet CLI telemetry when\r\nyour project is published using the `Release` configuration. See the [MSDN XDT reference](https://msdn.microsoft.com/en-us/library/dd465326.aspx)\r\nfor the complete transformation syntax.\r\n\r\nEdit the `XdtSample.csproj` file and inside an `\u003cItemGroup\u003e` element, add a reference to this XDT tool.\r\nNote that you cannot use the NuGet Package Manager UI in Visual Studio 2017 to CLI tool references;\r\nthey must currently be added by editing the project file.\r\n\r\n```xml\r\n  \u003cItemGroup\u003e\r\n    \u003cDotNetCliToolReference Include=\"Microsoft.DotNet.Xdt.Tools\" Version=\"2.0.0\" /\u003e\r\n    ... other package references ...\r\n  \u003c/ItemGroup\u003e\r\n```\r\n\r\nRun `dotnet restore` and `dotnet build` in the `XdtSample` folder. If you now run `dotnet transform-xdt`\r\nyou will see the available  options, similar to:\r\n\r\n```\r\n.NET Core XML Document Transformation\r\nUsage: dotnet transform-xdt [options]\r\nOptions:\r\n  -?|-h|--help    Show help information\r\n  --xml|-x        The path to the XML file to transform\r\n  --transform|-t  The path to the XDT transform file to apply\r\n  --output|-o     The path where the output (transformed) file will be written\r\n  --verbose|-v    Print verbose messages\r\n```\r\n\r\nSo far we added the XDT tool to the project, and now we will invoke it when the project is being published.\r\nWe want to call it before the built-in publish target that makes sure that the `Web.config` file has a reference\r\nto the `aspNetCore` handler, because that target always runs when publishing web projects, and it also formats\r\nthe config file to be nicely indented.\r\n\r\nEdit the `XdtSample.csproj` file and add this snippet at the end, right before the closing `\u003c/Project\u003e` tag:\r\n\r\n```xml\r\n\u003cProject ToolsVersion=\"15.0\" Sdk=\"Microsoft.NET.Sdk.Web\"\u003e\r\n  ... everything else ...\r\n\r\n  \u003cTarget Name=\"ApplyXdtConfigTransform\" BeforeTargets=\"_TransformWebConfig\"\u003e\r\n    \u003cPropertyGroup\u003e\r\n      \u003c_SourceWebConfig\u003e$(MSBuildThisFileDirectory)Web.config\u003c/_SourceWebConfig\u003e\r\n      \u003c_XdtTransform\u003e$(MSBuildThisFileDirectory)Web.$(Configuration).config\u003c/_XdtTransform\u003e\r\n      \u003c_TargetWebConfig\u003e$(PublishDir)Web.config\u003c/_TargetWebConfig\u003e\r\n    \u003c/PropertyGroup\u003e\r\n    \u003cExec\r\n        Command=\"dotnet transform-xdt --xml \u0026quot;$(_SourceWebConfig)\u0026quot; --transform \u0026quot;$(_XdtTransform)\u0026quot; --output \u0026quot;$(_TargetWebConfig)\u0026quot;\"\r\n        Condition=\"Exists('$(_XdtTransform)')\" /\u003e\r\n  \u003c/Target\u003e\r\n\u003c/Project\u003e\r\n```\r\n\r\nHere's a quick rundown of the values above:\r\n\r\n  - `BeforeTargets=\"_TransformWebConfig\"` schedules this target to run before the build-in target that adds\r\n    the `aspNetCore` handler, as described earlier.\r\n  - `_SourceWebConfig` defines the full path to the Web.config file in your **project** folder. This\r\n    will be used as the source (input) for the transformation.\r\n  - `_XdtTransform` defines the full path to the XDT transform file in your **project** folder to be applied.\r\n    In this example, we use `Web.$(Configuration).config`, where $(Configuration) is a placeholder for the publish\r\n    configuration, e.g. `Debug` or `Release`.\r\n  - `_TargetWebConfig` defines the path where the transformed `Web.config` file will be written to, in the **publish** folder.\r\n  - `Exec Command` invokes the XDT transform tool, passing the paths to the input file (`Web.config`), transform\r\n    file (e.g. `Web.Release.config`) and target file (`\u003cpublish-folder\u003e\\Web.config`).\r\n  - `Exec Condition` prevents the XDT transform tool from running if a transform file for a particular publish\r\n    configuration does not exist (e.g. `Web.Debug.config`).\r\n\r\nNow run `dotnet publish` in the `XdtSample` folder, and examine the `Web.config` in the publish output folder\r\n(`bin\\Debug\\netcoreapp2.0\\publish\\Web.config`). It should look similar to this:\r\n\r\n```xml\r\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\r\n\u003cconfiguration\u003e\r\n  \u003csystem.webServer\u003e\r\n    \u003chandlers\u003e\r\n      \u003cadd name=\"aspNetCore\" path=\"*\" verb=\"*\" modules=\"AspNetCoreModule\" resourceType=\"Unspecified\" /\u003e\r\n    \u003c/handlers\u003e\r\n    \u003caspNetCore processPath=\"dotnet\" arguments=\".\\XdtSample.dll\" stdoutLogEnabled=\"false\" stdoutLogFile=\".\\logs\\stdout\" forwardWindowsAuthToken=\"false\" /\u003e\r\n  \u003c/system.webServer\u003e\r\n\u003c/configuration\u003e\r\n```\r\n\r\nSince we have not defined a `Web.Debug.config` file, no transformation occured.\r\n\r\nNow let's publish again, but this time using the `Release` configuration. Run `dotnet publish -c Release`\r\nin the `XdtSample` folder, and examine the `bin\\Release\\netcoreapp2.0\\publish\\Web.config` file.\r\nIt should look similar to this:\r\n\r\n```xml\r\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\r\n\u003cconfiguration\u003e\r\n  \u003csystem.webServer\u003e\r\n    \u003chandlers\u003e\r\n      \u003cadd name=\"aspNetCore\" path=\"*\" verb=\"*\" modules=\"AspNetCoreModule\" resourceType=\"Unspecified\" /\u003e\r\n    \u003c/handlers\u003e\r\n    \u003caspNetCore processPath=\"dotnet\" arguments=\".\\XdtSample.dll\" stdoutLogEnabled=\"false\" stdoutLogFile=\".\\logs\\stdout\" forwardWindowsAuthToken=\"false\"\u003e\r\n      \u003cenvironmentVariables\u003e\r\n        \u003cenvironmentVariable name=\"DOTNET_CLI_TELEMETRY_OPTOUT\" value=\"1\" /\u003e\r\n      \u003c/environmentVariables\u003e\r\n    \u003c/aspNetCore\u003e\r\n  \u003c/system.webServer\u003e\r\n\u003c/configuration\u003e\r\n```\r\n\r\nNote that under `\u003caspNetCore\u003e`, the `\u003cenvironmentVariables\u003e` section was inserted, as configured in the\r\n`Web.Release.config` file.\r\n\r\n\u003ch3\u003e\u003ca name=\"project-json\"\u003e\u003c/a\u003eUse with \u003ccode\u003eproject.json\u003c/code\u003e tooling\u003c/h3\u003e\r\n\r\n\u003cdetails\u003e\r\nAdd `Microsoft.DotNet.Xdt.Tools` to the `tools` sections of your `project.json` file:\r\n\r\n```json\r\n{\r\n  ... other settings ...\r\n  \"tools\": {\r\n    \"Microsoft.DotNet.Xdt.Tools\": \"1.0.0\"\r\n  }\r\n}\r\n```\r\n\r\n##### Using [.NET Core 1.1](https://blogs.msdn.microsoft.com/dotnet/2016/11/16/announcing-net-core-1-1/) or [ASP.NET Core 1.1](https://blogs.msdn.microsoft.com/webdev/2016/11/16/announcing-asp-net-core-1-1/)?\r\n\r\nIn the sample above, replace `1.0.0` with `1.1.0`.\r\n\r\n### How to Use (project.json tooling)\r\n\r\nThe typical use case is to transform `Web.config` (or similar XML-based files) at publish time.\r\n\r\nAs an example, let's apply a transformation based on the publish configuration (i.e. `Debug` vs.\r\n`Release`). Add a `Web.Debug.config` file and a `Web.Release.config` file to your project, in the\r\nsame folder as `Web.config` file.\r\n\r\nCall the tool from the `scripts/postpublish` section of your `project.json` to invoke it after publish:\r\n\r\n```json\r\n{\r\n  \"scripts\": {\r\n    \"postpublish\": [\r\n        \"dotnet transform-xdt --xml \\\"%publish:ProjectPath%\\\\Web.config\\\" --transform \\\"%publish:ProjectPath%\\\\Web.%publish:Configuration%.config\\\" --output \\\"%publish:OutputPath%\\\\Web.config\\\"\",\r\n        \"dotnet publish-iis --publish-folder %publish:OutputPath% --framework %publish:FullTargetFramework%\"\r\n\t]\r\n  }\r\n}\r\n```\r\n\r\nThe following options are passed to `dotnet-transform-xdt`:\r\n- `xml`: the input XML file to be transformed; in this example, the `Web.config` file in your **project** folder.\r\n- `transform`: the XDT file to be applied; in this example, the `Web.Debug.config` file in your **project** folder.\r\n- `output`: the XML file with the transformed output (input + XDT); in this example, the `Web.config` file\r\n  in your **publish** folder (e.g. `bin\\Debug\\win7-x64\\publish`).\r\n\r\nWith the above setup, calling `dotnet publish` from your project folder will apply the XDT transform\r\nduring the publishing process. The tool will print its output to the console, prefixed with\r\n**`[XDT]`** markers.\r\n\r\nYou can pass an explicit configuration (e.g. `-c Debug` or `-c Release`) to `dotnet publish`\r\nto specify the configuration (and thus applicable XDT file) to publish. A similar option is available in the Visual\r\nStudio publish dialog.\r\n\r\nPlease note that varying the applied transform by configuration as shown above is just an example.\r\nAny [dotnet publish variable](https://github.com/dotnet/cli/blob/f4ceb1f2136c5b0be16a7b551d28f5634a6c84bb/src/dotnet/commands/dotnet-publish/PublishCommand.cs#L108-L113)\r\ncan be used to drive the transformation process.\r\n\r\nTo get a list of all available options, run `dotnet transform-xdt` from the project folder:\r\n\r\n```\r\n.NET Core XML Document Transformation\r\nUsage: dotnet transform-xdt [options]\r\nOptions:\r\n  -?|-h|--help    Show help information\r\n  --xml|-x        The path to the XML file to transform\r\n  --transform|-t  The path to the XDT transform file to apply\r\n  --output|-o     The path where the output (transformed) file will be written\r\n  --verbose|-v    Print verbose messages\r\n```\r\n\u003c/details\u003e\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnil4%2Fdotnet-transform-xdt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnil4%2Fdotnet-transform-xdt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnil4%2Fdotnet-transform-xdt/lists"}