Main | Contact | Blog | Documentation

PowerShell Framework

The project dedicated to empowering your PowerShell scripting.

Persistence: Manual Export & Import


Describes how to handle importing and exporting to a specified path / weblink.


The functionality to export to an explicitly specified path and importing configuration from that path, a weblink or straight configuration json is designed for two scenarios:

Exporting: Export-PSFConfig

Selecting what to export

There are several ways to pick what to export:


# Full Name filter
Export-PSFConfig -FullName MyModule.Path.* -OutPath C:\temp\demo.json

# Module and name filter
Export-PSFConfig -Module MyModule -Name Path.* -OutPath C:\temp\demo.json

# Configuration Objects
Get-PSFConfig -Module MyModule -Force | ? Hidden | Export-PSFConfig -OutPath C:\temp\demo.json

Changed settings

When exporting configuration items, it might be convenient to avoid exporting settings that haven’t been changed. This can be done by adding the -SkipUnchanged switch:

# Export all settings from module MyModule that were changed
Export-PSFConfig -Module MyModule -SkipUnchanged` -OutPath C:\temp\demo.json

Unchanged configuration items

The configuration system considers settings to be unchanged, if it wasn’t changed after initializing a setting. Explicitly setting the same value as the default value still constitutes a change. Importing settings are also a change. Pre-Existing settings that were reapplied after initialization also are changes. Attempts to change a setting that fail either validation or handler do not constitute changes.

Path to export to

The destination path is bound to the mandatory -OutPath parameter. It needs to point to the full name of the destination file, the folder must exist, the file need not exist and will be overwritten if it does. The extension chosen - if any - does not matter, the output data stored in it will be a json string.

Importing: Import-PSFConfig

Basic import

Importing a configuration item (from file, weblink or raw string) is uncomplicated, as all that is really needed is the parameter -Path.

# Import from path
Import-PSFConfig -Path C:\temp\demo.json

# Import from site
Import-PSFConfig -Path "https://website.example/config/prod.json"

# Import raw data
$configJsonString | Import-PSFConfig

Imported settings still will be individually validated (if the setting updated contains a validation) and handler events will individually fire. A failed validation or handler event however will not interrupt the import of other settings.

Taking a peek

As it may be of interest in some cases to merely peek at the content of a file, rather than immediately applying settings, Import-PSFConfig provides an option to do so. The -Peek parameter will process the configuration file as it normally would be, but rather than applying the changes will merely return the parsed settings. This does not run validation or handler events however, so some settings may still fail when actually applied.

Import-PSFConfig -Path C:\temp\demo.json -Peek


Settings to import can be filtered by their full name. The -IncludeFilter and -ExcludeFilter parameters ensure that it is granularly possible to target the setting to import. Both are wildcard parameters, that support multiple values to be specified:

Import-PSFConfig -Path C:\temp\demo.json -IncludeFilter MyModule.* -ExcludeFilter "*.Path.*", "*.Test.*"
This will import all settings from demo.json, so long as their names ...
- start with "MyModule.*"
- Do not contain ".Path."
- Do not contain ".Test."

Input Format / Schemata

While in this document we generally speak about Json files/data when importing configuration, that is not strictly required. Import-PSFConfig supports a concept called “Configuration Schema” - a schema defines how the input data needs to be formatted in order to be read. Schemas can be added, and more than one is included by default, so while the default schema is designed to understand the very format Export-PSFConfig produces, more userfriendly and powerful options are available … and you can write your own if you have custom needs.

To use a schema, simply specify it during import:

# Load the configuration file applying the MetaJson format
Import-PSFConfig -Path .\config.json -Schema MetaJson

Builtin schemata that are available out-of-the-box:

Default The simple default schema, designed to understand the output of Export-PSFConfig
MetaJson Advanced Json format, easy to author for a human, very flexible, supports hierarchical processing of multiple files that can react to the environment


Back to Configuration