PowerShell-Transforming

PowerShell commands for json-, package- and xml-transformation. This is, from version 2.0.0, a portable module that can run on Linux, Mac-OS and Windows. This library is simply a PowerShell layer for .NET-Transforming.

1 Commands

1.1 File-transforming

1.1.1 JSON-transform

New-FileTransform `
    -Destination "C:\Data\Transforms\Out\appsettings.json" `
    -Source "C:\Data\Transforms\In\appsettings.json" `
    -Transformation "C:\Data\Transforms\In\appsettings.Transformation.json";

1.1.2 XML-transform

New-FileTransform `
    -Destination "C:\Data\Transforms\Out\Web.config" `
    -Source "C:\Data\Transforms\In\Web.config" `
    -Transformation "C:\Data\Transforms\In\Web.Transformation.config";

1.2 Package-transforming

1.2.1 Patterns

For handling patterns the Microsoft.Extensions.FileSystemGlobbing.Matcher class is used under the hood.

FileToTransformPatterns
PathToDeletePatterns

Examples: https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.filesystemglobbing.matcher?view=dotnet-plat-ext-5.0#remarks

NuGet: https://www.nuget.org/packages/Microsoft.Extensions.FileSystemGlobbing

Patterns with absolute paths does not result in any matches.

1.2.2 Directory to directory transform

New-PackageTransform `
    -Destination "C:\Data\Transforms\Out\Package" `
    -FileToTransformPatterns "**/*.config", "**/*.json", "**/*.xml" `
    -PathToDeletePatterns "**/Directory-to-delete/**/*", "**/File-to-delete.*" `
    -Source "C:\Data\Transforms\In\Package" `
    -TransformationNames "Release", "Test";

1.2.3 Directory to zip-file transform

New-PackageTransform `
    -Destination "C:\Data\Transforms\Out\Package.zip" `
    -FileToTransformPatterns "**/*.config", "**/*.json", "**/*.xml" `
    -PathToDeletePatterns "**/Directory-to-delete/**", "**/File-to-delete.*" `
    -Source "C:\Data\Transforms\In\Package" `
    -TransformationNames "Release", "Test";

1.2.4 Zip-file to zip-file transform

New-PackageTransform `
    -Destination "C:\Data\Transforms\Out\Package.zip" `
    -FileToTransformPatterns "**/*.config", "**/*.json", "**/*.xml" `
    -PathToDeletePatterns "**/Directory-to-delete/*", "**/File-to-delete.*" `
    -Source "C:\Data\Transforms\In\Package.zip" `
    -TransformationNames "Release", "Test";

1.2.5 Zip-file to directory transform

New-PackageTransform `
    -Destination "C:\Data\Transforms\Out\Package" `
    -FileToTransformPatterns "**/*.config", "**/*.json", "**/*.xml" `
    -PathToDeletePatterns "**/Directory-to-delete/**/*", "**/File-to-delete.*" `
    -Source "C:\Data\Transforms\In\Package.zip" `
    -TransformationNames "Release", "Test";

1.2.6 Cleanup parameter

The actual transforming is done under the %temp%-directory. The "Cleanup" parameter (defaults to true) is for removing the temporary transform-directories or not.

New-PackageTransform `
    -Cleanup false `
    -Destination "C:\Data\Transforms\Out\Package" `
    -FileToTransformPatterns "**/*.config", "**/*.json", "**/*.xml" `
    -PathToDeletePatterns "**/Directory-to-delete/**/*", "**/File-to-delete.*" `
    -Source "C:\Data\Transforms\In\Package" `
    -TransformationNames "Release", "Test";

1.3 Common

All the commands above also have the parameter -AvoidByteOrderMark true/false. The default value for this parameter is:

On Windows: false
On other platforms (Linux/MacOS): true

This parameter controls the result of the transformation. If a source file that will be transformed has a BOM (Byte Order Mark) the destination file should also have a BOM. This is not always desired, e.g. on a Linux system. So if the source file has a BOM but the parameter "AvoidByteOrderMark" is set to true, the destination file will not have a BOM.

1.4 Logging

This PowerShell-module uses .NET-Transforming that may log information. A CommandLogger is used to write the logs to the PowerShell-console.

LogLevel.Critical & LogLevel.Error write errors (Cmdlet.WriteError).
LogLevel.Debug write debug (Cmdlet.WriteDebug).
LogLevel.Information write information (Cmdlet.WriteInformation).
LogLevel.Trace write verbose (Cmdlet.WriteVerbose).
LogLevel.Warning write warnings (Cmdlet.WriteWarning).

To write debug logs to the console you need to add the -Debug parameter:

New-FileTransform `
    -Destination "C:\Data\Transforms\Out\appsettings.json" `
    -Source "C:\Data\Transforms\In\appsettings.json" `
    -Transformation "C:\Data\Transforms\In\appsettings.Transformation.json" `
    -Debug;

To write verbose (trace) logs to the console you need to add the -Verbose parameter:

New-PackageTransform `
    -Destination "C:\Data\Transforms\Out\Package" `
    -FileToTransformPatterns "**/*.config", "**/*.json", "**/*.xml" `
    -PathToDeletePatterns "**/Directory-to-delete/**/*", "**/File-to-delete.*" `
    -Source "C:\Data\Transforms\In\Package" `
    -TransformationNames "Release", "Test" `
    -Verbose;

Note: At the moment [.NET-Transforming](https://github.com/RegionOrebroLan/.NET-Transforming/) don't write any logs. The logging functionality is recently implemented.

2 Development

2.1 Signing

Drop the "StrongName.snk" file in the repository-root. The file should not be included in source control.

2.2 Build warnings

At the moment we get the following warning (PowerShell-7-tests):

NETSDK1206

Haven't investigated it further.

3 Tests

The tests in this solution are a mix of integration- and unit-tests together.

3.1 Links

4 Deployment/installation

4.1 PowerShell-Gallery

If you want to set up a local PowerShell-Gallery to test with:

Register-PSRepository -Name "PowerShell-Transforming" -InstallationPolicy Trusted -SourceLocation "{SOLUTION-DIRECTORY}\.powershell-repository";

or run the following script:

If you want to remove it:

Unregister-PSRepository -Name "PowerShell-Transforming";

or run the following script:

Unregister.ps1

Get all module repositories:

Get-PSRepository

Get module repositories by name (with wildcard):

Get-PSRepository -Name "*Something*"

More information:

PowerShellGet

4.2 Install

Download this repository and build.
Run Publish-Module.ps1 in the output-directory (bin\Release).
Enter the NuGetApiKey if required and the name of the Repository or leave it blank to publish to "PSGallery". If you are testing with your local one, press enter for the NuGetApiKey parameter and enter "PowerShell-Transforming" for the Repository parameter.

Then you can try to install the module:

Install-Module "RegionOrebroLan.Transforming";

or (local)

Install-Module "RegionOrebroLan.Transforming" -Repository "PowerShell-Transforming";

or save it:

Save-Module -Name "RegionOrebroLan.Transforming" -Path "C:\Data\Saved-PowerShell-Modules";

To uninstall the module:

Uninstall-Module "RegionOrebroLan.Transforming";

4.2.1 Example

Install on a Linux build-agent via cmd.exe on Windows. The scenario is that you have version 2.0.0 installed and you want to install version 2.1.0. You also want to uninstall version 2.0.0 before installing version 2.1.0.

Open cmd.exe
ssh user@build-agent
sudo pwsh
(Get-InstalledModule RegionOrebroLan.Transforming).InstalledLocation - should give "/usr/local/share/powershell/Modules/RegionOrebroLan.Transforming/2.0.0" if it was installed with scope "AllUsers"
Uninstall-Module RegionOrebroLan.Transforming - if you want to remove previous versions
Install-Module RegionOrebroLan.Transforming -Scope "AllUsers"
(Get-InstalledModule RegionOrebroLan.Transforming).InstalledLocation - should give "/usr/local/share/powershell/Modules/RegionOrebroLan.Transforming/2.1.0"

4.3 Other

To see if anything is installed from your local PowerShell-repository:

Find-Module -Repository "PowerShell-Transforming"

The files in .powershell-repository:

give warnings but it seem to work anyhow.

RegionOrebroLan / PowerShell-Transforming

readme