dotnet-transform-xdt - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #ai #llm #go #machine-learning #deep-learning #linux #docker #kubernetes #vue #mcp #ios

dotnet-transform-xdt

(★ 118)

Modern .NET tools and library for XDT (Xml Document Transformation)

File Explorer

Download Latest Version (.zip)

- - ci.yml
- dotnet-xdt.csproj
- IXmlOriginalDocumentService.cs
- IXmlTransformationLogger.cs
- NamedTypeFactory.cs
- PositionTrackingTextReaders.cs
- Program.cs
- SR.Designer.cs
- SR.resx
- XmlArgumentUtility.cs
- XmlAttributePreservationDict.cs
- XmlAttributePreservationProvider.cs
- XmlAttributePreservingWriter.cs
- XmlAttributeTransform.cs
- XmlElementContext.cs
- XmlFileInfoDocument.cs
- XmlFormatter.cs
- XmlLocator.cs
- XmlLocators.cs
- XmlNodeContext.cs
- XmlNodeException.cs
- XmlTransform.cs
- XmlTransformableDocument.cs
- XmlTransformation.cs
- XmlTransformationException.cs
- XmlTransformationLogger.cs
- XmlTransforms.cs
- - .gitattributes
  - AttributeFormatting.log
  - AttributeFormatting_baseline.xml
  - AttributeFormatting_source.xml
  - AttributeFormatting_transform.xml
  - EdgeCase.log
  - EdgeCase_baseline.xml
  - EdgeCase_source.xml
  - EdgeCase_transform.xml
  - TagFormatting.log
  - TagFormatting_baseline.xml
  - TagFormatting_source.xml
  - TagFormatting_transform.xml
  - WarningsAndErrors.log
  - WarningsAndErrors_source.xml
  - WarningsAndErrors_transform.xml
  - Web.config
  - Web.Release.config
- dotnet-xdt.tests.csproj
- TestTransformationLogger.cs
- XmlTransformTests.cs
.editorconfig
.gitignore
appveyor.yml
build.ps1
dotnet-xdt.sln
dotnet-xdt.sln.DotSettings
global.json
LICENSE.txt
README.md
test.ps1

# Installation Guide

1. Get the code

git clone https://github.com/nil4/dotnet-transform-xdt

Downloads the entire project code from GitHub to your computer.

cd dotnet-transform-xdt

Moves into the project folder you just downloaded.

2. .NET

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
.NET SDK The SDK required for the dotnet command.

<DotNetCliToolReference Include="Microsoft.DotNet.Xdt.Tools" Version="2.0.0" />

Type this command into your terminal and run it.

Command="dotnet transform-xdt --xml &quot;$(_SourceWebConfig)&quot; --transform &quot;$(_XdtTransform)&quot; --output &quot;$(_TargetWebConfig)&quot;"

Type this command into your terminal and run it.

<aspNetCore processPath="dotnet" arguments=".\XdtSample.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="false" />

Type this command into your terminal and run it.

<aspNetCore processPath="dotnet" arguments=".\XdtSample.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="false">

Type this command into your terminal and run it.

"Microsoft.DotNet.Xdt.Tools": "1.0.0"

Type this command into your terminal and run it.

✅ After dotnet run, check the message or address shown in the terminal.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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)

Tools and library for applying [XML Document Transformations](https://msdn.microsoft.com/en-us/library/dd465326.aspx)
to e.g. .NET configuration files, or any other XML-structured content.

### <a name="dotnet-xdt-tool"></a> 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/)

.NET Core 2.1 introduces the concept of [global tools](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools),
meaning that you can install `dotnet-xdt` using the .NET CLI and use it everywhere. One advantage of this approach
is that you can use the same command, for both installation and usage, across all platforms.

> :warning: To use global tools, .Net Core SDK 2.1.300 or later is required.

Install `dotnet-xdt` as a global tool (only once):

```cmd
dotnet tool install --global dotnet-xdt --version 2.2.1
```

And then you can apply XDT transforms, from the command-line, anywhere on your PC, e.g.:

```shell
dotnet xdt --source original.xml --transform delta.xml --output final.xml
```

Global tools are not ideal when an application needs to build completely self-contained,
without relying on tools installed in the surrounding environment. They are also only
available on the latest .NET Core.

Read on if this is a concern for your application.

### <a name="dotnet-transform-xdt-tool"></a> Project tool for .NET Core 2.0 and earlier

.NET Core 2.0 and earlier do not support global tools.

The "classic" version of this tool, however, *can* be installed as a
[project-level tool](https://docs.microsoft.com/en-us/dotnet/core/tools/extensibility#per-project-based-extensibility)
on both the latest .NET Core, as well as on previous versions.

The tradeoff is that in this usage model, the tool can only be invoked
via `dotnet transform-xdt`, and only from the folder of the project that references it.

See the [project-level `dotnet-transform-xdt` tool](#legacy) section
below for details. [A separate repository](https://github.com/nil4/xdt-samples/) provides a
few self-contained sample projects that use `dotnet-transform-xdt`
for Web.config transformations at publish time.

### <a name="dotnet-xdt-exe"></a>Standalone executable for Windows

You can also download a standalone `dotnet-xdt.exe` that runs on any Windows PC with .NET
Framework 4.6.1 installed. It has no external dependencies, nor does it require .NET Core.
It *might* run on Mono, but this scenario is not tested.

Download the latest build of `dotnet-xdt.exe` from the [releases page](https://github.com/nil4/dotnet-transform-xdt/releases).

### <a name="dotnet-xdt-lib"></a>.NET Standard 2.0 library [![NuGet package](https://img.shields.io/nuget/dt/DotNet.Xdt.svg)](https://www.nuget.org/packages/DotNet.Xdt/)

For complete flexibility, reference the cross-platform `DotNet.Xdt` NuGet package in your application:

```cmd
dotnet add package DotNet.Xdt --version 2.2.1
```

You can apply XDT transforms to any XML file, or other XML sources that can be read from
and written to a .NET `Stream`.

Define a class `MyXdtLogger` that implements `IXmlTransformationLogger`.
Then, apply transformations using code similar to:

```csharp
var document = new XmlTransformableDocument { PreserveWhitespace = true };

using (var sourceStream = File.OpenRead(sourceFilePath))
using (var transformStream = File.OpenRead(transformFilePath))
using (var transformation = new XmlTransformation(transformStream, new MyXdtLogger()))
{
    document.Load(sourceStream);
    transformation.Apply(document);
}

using (FileStream outputStream = File.Create(outputFilePath))
using (var outputWriter = XmlWriter.Create(outputStream, new XmlWriterSettings { Indent = true }))
{
    document.WriteTo(outputWriter);
}
```

## <a name="legacy"></a> 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/)

*`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.*

**`dotnet-transform-xdt`** is an alternative version that can be installed
as a project-level tool, on all .NET Core versions.

### <a name="msbuild"></a> Use with MSBuild/csproj tooling

**Note**: if you are using project.json tooling (CLI 1.0.0 preview 2 or earlier, or Visual Studio 2015),
please refer to the [project.json section below](#project-json).

Run `dotnet --version` in a command prompt and make sure you're using version **`2.0.0`** or later.

Create a new folder (`XdtSample`) and run `dotnet new web` inside it. Verify that the files
`XdtSample.csproj` and `web.config` file are present. Create a new file named `Web.Release.config`
inside that folder and set its content to:

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.webServer>
    <aspNetCore>
      <environmentVariables xdt:Transform="Insert">
        <environmentVariable name="DOTNET_CLI_TELEMETRY_OPTOUT" value="1" />
      </environmentVariables>
    </aspNetCore>
  </system.webServer>
</configuration>
```

We will use this sample XDT file to add an environment variable that disables dotnet CLI telemetry when
your project is published using the `Release` configuration. See the [MSDN XDT reference](https://msdn.microsoft.com/en-us/library/dd465326.aspx)
for the complete transformation syntax.

Edit the `XdtSample.csproj` file and inside an `<ItemGroup>` element, add a reference to this XDT tool.
Note that you cannot use the NuGet Package Manager UI in Visual Studio 2017 to CLI tool references;
they must currently be added by editing the project file.

```xml
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.DotNet.Xdt.Tools" Version="2.0.0" />
    ... other package references ...
  </ItemGroup>
```

Run `dotnet restore` and `dotnet build` in the `XdtSample` folder. If you now run `dotnet transform-xdt`
you will see the available  options, similar to:

```
.NET Core XML Document Transformation
Usage: dotnet transform-xdt [options]
Options:
  -?|-h|--help    Show help information
  --xml|-x        The path to the XML file to transform
  --transform|-t  The path to the XDT transform file to apply
  --output|-o     The path where the output (transformed) file will be written
  --verbose|-v    Print verbose messages
```

So far we added the XDT tool to the project, and now we will invoke it when the project is being published.
We want to call it before the built-in publish target that makes sure that the `Web.config` file has a reference
to the `aspNetCore` handler, because that target always runs when publishing web projects, and it also formats
the config file to be nicely indented.

Edit the `XdtSample.csproj` file and add this snippet at the end, right before the closing `</Project>` tag:

```xml
<Project ToolsVersion="15.0" Sdk="Microsoft.NET.Sdk.Web">
  ... everything else ...

<Target Name="ApplyXdtConfigTransform" BeforeTargets="_TransformWebConfig">
    <PropertyGroup>
      <_SourceWebConfig>$(MSBuildThisFileDirectory)Web.config</_SourceWebConfig>
      <_XdtTransform>$(MSBuildThisFileDirectory)Web.$(Configuration).config</_XdtTransform>
      <_TargetWebConfig>$(PublishDir)Web.config</_TargetWebConfig>
    </PropertyGroup>
    <Exec
        Command="dotnet transform-xdt --xml &quot;$(_SourceWebConfig)&quot; --transform &quot;$(_XdtTransform)&quot; --output &quot;$(_TargetWebConfig)&quot;"
        Condition="Exists('$(_XdtTransform)')" />
  </Target>
</Project>
```

Here's a quick rundown of the values above:

- `BeforeTargets="_TransformWebConfig"` schedules this target to run before the build-in target that adds
    the `aspNetCore` handler, as described earlier.
  - `_SourceWebConfig` defines the full path to the Web.config file in your **project** folder. This
    will be used as the source (input) for the transformation.
  - `_XdtTransform` defines the full path to the XDT transform file in your **project** folder to be applied.
    In this example, we use `Web.$(Configuration).config`, where $(Configuration) is a placeholder for the publish
    configuration, e.g. `Debug` or `Release`.
  - `_TargetWebConfig` defines the path where the transformed `Web.config` file will be written to, in the **publish** folder.
  - `Exec Command` invokes the XDT transform tool, passing the paths to the input file (`Web.config`), transform
    file (e.g. `Web.Release.config`) and target file (`<publish-folder>\Web.config`).
  - `Exec Condition` prevents the XDT transform tool from running if a transform file for a particular publish
    configuration does not exist (e.g. `Web.Debug.config`).

Now run `dotnet publish` in the `XdtSample` folder, and examine the `Web.config` in the publish output folder
(`bin\Debug\netcoreapp2.0\publish\Web.config`). It should look similar to this:

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="dotnet" arguments=".\XdtSample.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="false" />
  </system.webServer>
</configuration>
```

Since we have not defined a `Web.Debug.config` file, no transformation occured.

Now let's publish again, but this time using the `Release` configuration. Run `dotnet publish -c Release`
in the `XdtSample` folder, and examine the `bin\Release\netcoreapp2.0\publish\Web.config` file.
It should look similar to this:

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="dotnet" arguments=".\XdtSample.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="false">
      <environmentVariables>
        <environmentVariable name="DOTNET_CLI_TELEMETRY_OPTOUT" value="1" />
      </environmentVariables>
    </aspNetCore>
  </system.webServer>
</configuration>
```

Note that under `<aspNetCore>`, the `<environmentVariables>` section was inserted, as configured in the
`Web.Release.config` file.

<h3><a name="project-json"></a>Use with <code>project.json</code> tooling</h3>

<details>
Add `Microsoft.DotNet.Xdt.Tools` to the `tools` sections of your `project.json` file:

```json
{
  ... other settings ...
  "tools": {
    "Microsoft.DotNet.Xdt.Tools": "1.0.0"
  }
}
```

##### 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/)?

In the sample above, replace `1.0.0` with `1.1.0`.

### How to Use (project.json tooling)

The typical use case is to transform `Web.config` (or similar XML-based files) at publish time.

As an example, let's apply a transformation based on the publish configuration (i.e. `Debug` vs.
`Release`). Add a `Web.Debug.config` file and a `Web.Release.config` file to your project, in the
same folder as `Web.config` file.

Call the tool from the `scripts/postpublish` section of your `project.json` to invoke it after publish:

```json
{
  "scripts": {
    "postpublish": [
        "dotnet transform-xdt --xml \"%publish:ProjectPath%\\Web.config\" --transform \"%publish:ProjectPath%\\Web.%publish:Configuration%.config\" --output \"%publish:OutputPath%\\Web.config\"",
        "dotnet publish-iis --publish-folder %publish:OutputPath% --framework %publish:FullTargetFramework%"
	]
  }
}
```

The following options are passed to `dotnet-transform-xdt`:
- `xml`: the input XML file to be transformed; in this example, the `Web.config` file in your **project** folder.
- `transform`: the XDT file to be applied; in this example, the `Web.Debug.config` file in your **project** folder.
- `output`: the XML file with the transformed output (input + XDT); in this example, the `Web.config` file
  in your **publish** folder (e.g. `bin\Debug\win7-x64\publish`).

With the above setup, calling `dotnet publish` from your project folder will apply the XDT transform
during the publishing process. The tool will print its output to the console, prefixed with
**`[XDT]`** markers.

You can pass an explicit configuration (e.g. `-c Debug` or `-c Release`) to `dotnet publish`
to specify the configuration (and thus applicable XDT file) to publish. A similar option is available in the Visual
Studio publish dialog.

Please note that varying the applied transform by configuration as shown above is just an example.
Any [dotnet publish variable](https://github.com/dotnet/cli/blob/f4ceb1f2136c5b0be16a7b551d28f5634a6c84bb/src/dotnet/commands/dotnet-publish/PublishCommand.cs#L108-L113)
can be used to drive the transformation process.

To get a list of all available options, run `dotnet transform-xdt` from the project folder:

```
.NET Core XML Document Transformation
Usage: dotnet transform-xdt [options]
Options:
  -?|-h|--help    Show help information
  --xml|-x        The path to the XML file to transform
  --transform|-t  The path to the XDT transform file to apply
  --output|-o     The path where the output (transformed) file will be written
  --verbose|-v    Print verbose messages
```
</details>