Skip to main content

Persistence: Basics

Synopsis​

Covers the basics of how configuration settings can be persisted.

The Three Types Of Persistence​

Settings can be stored in three kinds of locations:

  • Settings that will be automatically imported when loading the PSFramework module for the first time. These can be stored in both registry or file, can be per user or computer-wide.
  • Settings that are explicitly read and written by a module, but stored in a specific path.
  • You can manually pick a location to export to/import from.

Working with automatic import/export​

Simply remember a setting​

As a user, you can persist any setting on the fly by using the Register-PSFConfig command:

Set-PSFConfig psframework.message.style.breadcrumbs $true -PassThru | Register-PSFConfig

This will make the configuration system remember the setting by writing it to the default per-user location. It will then be loaded automatically each time the PSFramework module is imported.

Forgetting a setting​

If you want to delete a persisted setting - so that it will revert to the default value - use the Unregister-PSFConfig command:

Unregister-PSFConfig -FullName myscript.target

This will not change the setting in the current session, but on new sessions, default values will again apply. (You can of course follow this up by running Set-PSFConfig to explicitly apply the default value for the current session)

In order to forget all settings for a module - effectively returning it to factory default - run the command like this:

Unregister-PSFConfig -Module MyModule

The scopes​

Automatic persistence can be applied in 9 different locations:

FileSystem, FileUserLocal, FileUserShared, SystemDefault, SystemMandatory, UserDefault, UserMandatory, Environment, EnvironmentSimple

Many configuration commands that deal with persistence have a -Scope parameter. This parameter exists to target which of these locations to work with. For full documentation on the paths used for this, see the guide on persistence locations.

Explicit module settings​

Modules have the option to use a dedicated data store, by using the Import-PSFConfig and Export-PSFConfig commands like this:

# Load from file for module 'MyModule'
Import-PSFConfig -ModuleName MyModule

# Write to file for module 'MyModule'
Export-PSFConfig -ModuleName MyModule

The path is automatically managed for the commands, based on modulename. This is designed to allow modules to use this system for persistent caches.

For more information on this, see either the technical guide to module cache or the scenario tutorial on configuration as cache.

Writing to / Reading from file​

Importing settings from file (or writing them to file) is reasonably simple using the same Import-PSFConfig and Export-PSFConfig commands.

# Load from specified file
Import-PSFConfig -Path "C:\temp\example.json"

# Write to specified file
Get-PSFConfig -Module MyModule -Name "*Message*" | Export-PSFConfig -Path "C:\temp\example.json"

For more information on this, see either the technical guide to manual export and import or the scenario guide to CI/CD configuration.