About the TSToy application

Overview #

For the purposes of the command-based DSC Resource tutorials, you’re creating a DSC Resource to manage the fictional Tailspin Toys application, tstoys.

The application has configuration options that control whether it should look for updates and how frequently to do so. Like many real applications, tstoy uses a combination of arguments, environment variables, and configuration files. For these tutorials, the DSC Resource only needs to manage the configuration files.

Installing TSToy #

go install github.com/PowerShell/DSC-Samples/tstoy@latest

Once you have tstoy installed and added to your path, you can call it to see the available commands:

tstoy

You can enable shell completions for the application to make interacting with it easier.

# bash
tstoy completion bash --help
source <(tstoy completion bash)

# fish
tstoy completion fish --help
tstoy completion fish | source

# PowerShell
tstoy completion powershell --help
tstoy completion powershell | Out-String | Invoke-Expression

# zsh
tstoy completion zsh --help
source <(tstoy completion zsh)

TSToy configuration #

The TSToy application uses two configuration files. The configuration for all users is the machine-scope configuration file. The configuration for the current user is the user-scope configuration file.

When TSToy runs, it starts with a default configuration. If the machine-scope configuration file exists, TSToy overrides the default configuration with the settings in that file. Then, if the user-scope configuration file exists, TSToy overrides the configuration with the settings in that file.

The DSC Resource needs to be able to manage both the machine and user scope configuration files.

TSToy expects the configuration files to be JSON files. It uses settings in the updates key of that JSON file to control the update behavior.

TSToy uses this default configuration:

{
    "updates": {
        "automatic": true,
        "checkFrequency": 90
    }
}

When automatic is set to true, TSToy looks for updates when it starts. The value of checkFrequency indicates how many days it should wait before looking for updates again. TSToy only considers the checkFrequency setting valid when it’s an integer between 1 and 90, inclusive.

Your DSC Resource needs to manage:

• Whether the configuration file in a specific scope should exist
• Whether it sets the configuration to automatically update
• How many days it sets the configuration to wait before looking for updates

TSToy commands #

While working through the tutorials, you’ll need to retrieve the configuration files path that tstoy uses. You can get the paths to the configuration files with the show path command:

# Outputs both paths, with the machine-scope configuration file first.
tstoy show path
# Outputs only the path to the machine-scope configuration file.
tstoy show path machine
# Outputs only the path to the user-scope configuration file.
tstoy show path user

tstoy show path

C:\ProgramData\TailSpinToys\tstoy\tstoy.config.json
C:\Users\mikey\AppData\Local\TailSpinToys\tstoy\tstoy.config.json

tstoy show path machine

C:\ProgramData\TailSpinToys\tstoy\tstoy.config.json

tstoy show path user

C:\Users\mikey\AppData\Local\TailSpinToys\tstoy\tstoy.config.json

tstoy show path

/etc/xdg/TailSpinToys/tstoy/tstoy.config.json
/home/mikey/.config/TailSpinToys/tstoy/tstoy.config.json

tstoy show path machine

/etc/xdg/TailSpinToys/tstoy/tstoy.config.json

tstoy show path user

/home/mikey/.config/TailSpinToys/tstoy/tstoy.config.json

You may also want to see how TSToy is interpreting the configuration files to validate your work. Use the show command to get the application’s default settings, the settings from each configuration scope, and the final merged settings.

# Show all settings
tstoy show

Default configuration: {
  "Updates": {
    "Automatic": false,
    "CheckFrequency": 90
  }
}
Machine configuration: {}
User configuration: {}
Final configuration: {
  "Updates": {
    "Automatic": false,
    "CheckFrequency": 90
  }
}

Use the --only flag to get a subset of configuration.

tstoy show --only machine,user

Machine configuration: {}
User configuration: {}