Skip to content

Commit

Permalink
Add a changelog, update README
Browse files Browse the repository at this point in the history
  • Loading branch information
Jaykul committed Aug 24, 2023
1 parent 786ab69 commit 8287640
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 21 deletions.
36 changes: 36 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.6.0] - 2023-08-24

### Added

- Get-ParameterValue. Get parameter values from PSBoundParameters + DefaultValues and optionally, a configuration file.

### Fixed

- Only call Add-MetadataConverter at load if converters are supplied at load time.

## [1.5.1] - 2022-06-06

### Fixed

- Stop re-importing the metadata module at import

## [1.5.0] - 2021-07-03

### Removed

This is the first release without the Metadata module included. This module is now available as a separate module on the PowerShell Gallery.

### Added

Test runs on GitHub Actions now include Linux and Mac OS.

AllowedVariables now flow through the whole module (and into calls to the Metadata module).
44 changes: 23 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,32 @@
[![Build Status](https://github.com/PoshCode/Configuration/actions/workflows/build.yml/badge.svg)](https://github.com/PoshCode/Configuration/actions/workflows/build.yml)
# The Configuration Module

## Metadata commands for working with .psd1:

- Manipulating metadata files
- Extensible serialization of types
- Built in support for DateTime, Version, Guid, SecureString, ScriptBlocks and more
- Lets you store almost anything in readable metadata (.psd1) files
- Serializing (`Export`) to metadata (.psd1) files
- Deserializing (`Import`) from metadata (.psd1) files

## Configuration commands for loading settings:
Configuration commands for storing and loading settings (usually just hashtables, but can be any PSObject). Just pipe your hashtable to `Export-Configuration` and load it back with `Import-Configuration`!

- Ship default configuration files with your module
- Automatically determines where to save your settings
- Supports Windows roaming profiles
- Supports XDG settings for Linux (and MacOS)
- Allow users to configure settings using our commands, or your wrappers
- Supports Windows roaming profiles
- Supports XDG settings for Linux (and MacOS)
- Allow users to configure settings using our commands, or your own custom commands
- Supports _layered_ configurations:
- Machine-level config
- User override files
- Supports automatic configuration of parameters values for a command
- Reads `Noun` configuration files in your working directory
- Filters only values which apply to the current command
- Supports recursively defining defaults in folders
- Supports combining parameter values from PSBoundParameters, DefaultValues, and an optional configuration file.

These modules work back to much older versions of PowerShell, but are currently being tested on Windows PowerShell and PowerShell 7. They depend on the Metadata module for serialization of objects to psd1 format.

## Metadata commands for working with .psd1 are in the [Metadata](https://github.com/PoshCode/Metadata) module

- Manipulating metadata files
- Extensible serialization of types
- Built in support for DateTime, Version, Guid, SecureString, ScriptBlocks and more
- Lets you store almost anything in readable metadata (.psd1) files
- Serializing (`Export`) to metadata (.psd1) files
- Deserializing (`Import`) from metadata (.psd1) files

It supports WindowsPowerShell, as well as PowerShell Core on Windows, Linux and OS X.

Expand Down Expand Up @@ -74,7 +77,7 @@ Of course, you could have imported the configuration, edited that one setting, a

Versioning your configuration is supported, but is only done explicitly (in `Import-Configuration`, `Export-Configuration`, and `Get-ConfigurationPath`). Whenever you need to change your module's configuration in an incompatible way, you can write a migration function that runs at import-time in your new version, something like this:

```posh
```powershell
# Specify a script-level version number
$ConfigVersion = @{ Version = 1.1 }
Expand Down Expand Up @@ -109,9 +112,9 @@ The Configuration module works by serializing PowerShell hashtables or custom ob

When you `Export-Configuration` you can set the `-Scope`, which determines where the Configuration.psd1 are stored:

* **User** exports to `$Env:LocalAppData` or `~/.config/`
* **Enterprise** exports to `$Env:AppData` (the roaming path) or `~/.local/share/`
* **Machine** exports to `$Env:ProgramData` or `/etc/xdg/`
- **User** exports to `$Env:LocalAppData` or `~/.config/`
- **Enterprise** exports to `$Env:AppData` (the roaming path) or `~/.local/share/`
- **Machine** exports to `$Env:ProgramData` or `/etc/xdg/`

Note that the linux paths are controlled by XDG environment variables, and the default paths can be overriden by manually editing the Configuration module manifest.

Expand Down Expand Up @@ -140,13 +143,13 @@ The actual serialization commands (with the `Metadata` noun) are: ConvertFrom, C

In other words, it handles everything you're likely to need in a configuration file. However, it also has support for adding additional type serializers via the `Add-MetadataConverter` command. If you want to store anything that doesn't work, please raise an issue :wink:.

#### One little catch
### One little catch

The configuration module uses the caller's scope to determine the name of the module (and Company or Author name) that is asking for configuration. For this reason you normally just call `Import-Configuration` from within _a function_ **in** your module (to make sure the callstack shows the module scope).

The _very important_ side effect is that you _must not_ change the module name nor the author of your module if you're using this Configuration module, or you will need to manually call `Import-Configuration` with the old information and then `Export` those settings to the new location (see the )

#### Using the cmdlets from outside a module
### Using the cmdlets from outside a module

It is possible to use the commands to Import and Export the configuration for a module from outside the module (or from the main module body, instead of a function), simply pipe the ModuleInfo to `Import-Configuration`. To continue our example from earlier:

Expand All @@ -164,8 +167,7 @@ $Config = Import-Configuration -Name DataModule -Author HuddledMasses.org

Because of how easily this can go wrong, I strongly recommend you don't use this syntax -- but if you do, be aware that you must also specify the `-DefaultPath` if you want to load the default configuration file from the module folder.


# A little history:
# A little history

The Configuration module is something I first wrote as part of the PoshCode packaging module and have been meaning to pull out for awhile.

Expand Down

0 comments on commit 8287640

Please sign in to comment.