How to add custom scripts

This quick guide explains how to add custom scripts to Auto Dark Mode that trigger on light or dark theme switches respectively. Currently, this feature is meant to be set up using a yaml configuration file. Rudimentary UI support will be added (enabling/disabling and opening of the config file via UI). We may eventually provide full UI support for this at a later point. Please do not ask for UI support or an ETA.

How do I find the scripts config file?

• Open the Auto Dark Mode config folder (right click the tray icon and select "Open Config Directory" or go to the Settings page in the app and select "Open config folder").
• Open the scripts.yaml file.

Note: If you mess up your scripts.yaml file, you can delete it and restart the service. That will create a new file.

Guide

Once you open the file with your favorite editor, you will see an already defined example. Below there are some comments describing what each entry is for:

# If you want to make use of the scripts feature, set this to true
Enabled: false
Component:
  Scripts:
  - Name: MyApp
    # Command is the path to the executable, it can be something in your PATH, or a full file path
    Command: C:\Users\Mypath\MyExecutable.exe
    # The working directory is optional.
    # You can omit it if you don't care about where your script is executed
    WorkingDirectory: C:\Users\YourUserName\AppData\Roaming\AutoDarkMode
    # The arguments that are passed when the script is called for light and dark mode.
    # They can be omitted as well if not needed.
    # You can either use flow style which is comma separated...
    ArgsLight: [--light, I am another light command]
    # ...or the normal syntax
    ArgsDark: 
      - --dark
      - I am another dark command
    # Specifies the allowed switch sources for better control when to run scripts
    AllowedSources: [Any, TimeSwitchModule, BatteryStatusChanged, SystemResume, Manual]
    # the maximum allowed time each script is allowed to run in milliseconds. Default is 10000 if omitted
    TimeoutMillis: 10000

  - Name: Powershell Example
    Command: powershell 
    ArgsLight: [C:\test.ps1, -message light -emotion 'happy']
    ArgsDark: [C:\test.ps1, -message dark -emotion 'happy']
    AllowedSources: [Any]

  - Name: MyOtherApp
    Command: cmd
    ArgsLight: 
      - /c
      - echo I am a light command
    ArgsDark: [/c, echo I am a dark command]

  - Name: MyMinimalAppNoParameters
    Command: C:\Users\MyUsername\test.exe

Each argument in ArgsLight or ArgsDark is wrapped with "" when called by default.

Auto Dark Mode will then run the scripts when the theme switches or on the next timer tick if the configuration file was changed. It is possible to run any script.

Please note that we will not provide support if your script doesn't work or if you don't escape your arguments or commands properly. The burden of proof that Auto Dark Mode is at fault if your script doesn't run is on you.

Allowed Sources

The script event handler is aware of which module within Auto Dark Mode performed the switch.

The different events are:

• Any - permits all sources (default)
• TimeSwitchModule - permits script to run if the source is a timed switch (at sunrise/sunset)
• NightLightTrackerModule - permits script to run if the source is windows night light
• BatteryStatusChanged - permits script to run if the source was a battery charge state event
• SystemResume - permits script to run if the source was a system resume event (wakeup from sleep)
• Manual - permits script to run if the source was a manual user-invoked event (force theme, in the UI, via shell)

Output

In the service.log file, Auto Dark Mode will show your script's error and standard output streams including all thrown exceptions by the process runner, should you be in need of debugging.