Execution module for creating shortcuts on Windows. Handles file shortcuts (.lnk) and url shortcuts (.url). Allows for the configuration of icons and hot keys on file shortcuts. Changing the icon and hot keys are unsupported for url shortcuts.
New in version 3005.
Create a new shortcut. This can be a file shortcut (.lnk
) or a url
shortcut (.url
).
path (str) -- The full path to the shortcut. Must have a .lnk or .url file extension.
target (str) -- The full path to the target.
arguments (str
, optional) --
Any arguments to be passed to the target.
Default is "".
description (str
, optional) --
The description for the shortcut. This is shown in the Comment
field of the dialog box.
Default is "".
hot_key (str
, optional) --
A combination of hot Keys to trigger this shortcut. This is
something like Ctrl+Alt+D
. This is shown in the Shortcut key
field in the dialog box. Available options are:
Ctrl
Alt
Shift
Ext
Default is "".
icon_index (int
, optional) --
The index for the icon to use in files that contain multiple icons.
Default is 0.
icon_location (str
, optional) --
The full path to a file containing icons. This is shown in the
Change Icon
dialog box by clicking the Change Icon
button.
If no file is specified and a binary is passed as the target,
Windows will attempt to get the icon from the binary file.
Default is "".
window_style (str
, optional) --
The window style the program should start in. This is shown in the
Run
field of the dialog box. Valid options are:
Normal
Minimized
Maximized
Default is "Normal".
working_dir (str
, optional) --
The full path to the working directory for the program to run in.
This is shown in the Start in
field of the dialog box.
Default is "".
backup (bool
, optional) --
If there is already a shortcut with the same name, set this value to
True
to backup the existing shortcut and continue creating the
new shortcut.
Default is False
.
force (bool
, optional) --
If there is already a shortcut with the same name and you aren't
backing up the shortcut, set this value to True
to remove the
existing shortcut and create a new with these settings.
Default is False
.
make_dirs (bool
, optional) --
If the parent directory structure does not exist for the new shortcut, create it.
Default is False
.
user (str
, optional) --
The user to be the owner of any directories created by setting
make_dirs
to True
. If no value is passed, Salt will use the
user account that it is running under.
Default is "".
True
if successful.
CommandExecutionError -- If the path is not a .lnk
or .url
file
extension.
CommandExecutionError -- If there is an existing shortcut with the same
name and backup
and force
are both False
CommandExecutionError -- If the parent directory is not created and
make_dirs
is False
CommandExecutionError -- If there was an error creating the parent directories
CLI Example:
# Create a shortcut and set the ``Shortcut key`` (``hot_key``)
salt '*' shortcut.create 'C:\path\to\shortcut.lnk' 'C:\Windows\notepad.exe' hot_key='Ctrl+Alt+N'
# Create a shortcut and change the icon to the 3rd one in the icon file
salt '*' shortcut.create 'C:\path\to\shortcut.lnk' 'C:\Windows\notepad.exe' icon_location='C:\path\to\icon.ico' icon_index=2
# Create a shortcut and change the startup mode to full screen
salt '*' shortcut.create 'C:\path\to\shortcut.lnk' 'C:\Windows\notepad.exe' window_style='Maximized'
# Create a shortcut and change the icon
salt '*' shortcut.create 'C:\path\to\shortcut.lnk' 'C:\Windows\notepad.exe' icon_location='C:\path\to\icon.ico'
# Create a shortcut and force it to overwrite an existing shortcut
salt '*' shortcut.create 'C:\path\to\shortcut.lnk' 'C:\Windows\notepad.exe' force=True
# Create a shortcut and create any parent directories if they are missing
salt '*' shortcut.create 'C:\path\to\shortcut.lnk' 'C:\Windows\notepad.exe' make_dirs=True
Gets the properties for a shortcut
path (str) -- The path to the shortcut. Must have a .lnk or .url file extension.
shortcut
CLI Example:
salt '*' shortcut.get path='C:\path\to\shortcut.lnk'
Modify an existing shortcut. This can be a file shortcut (.lnk
) or a
url shortcut (.url
).
path (str) -- The full path to the shortcut. Must have a .lnk or .url file extension.
target (str
, optional) --
The full path to the target.
Default is "".
arguments (str
, optional) --
Any arguments to be passed to the target.
Default is "".
description (str
, optional) --
The description for the shortcut. This is shown in the Comment
field of the dialog box.
Default is "".
hot_key (str
, optional) --
A combination of hot Keys to trigger this shortcut. This is
something like Ctrl+Alt+D
. This is shown in the Shortcut key
field in the dialog box. Available options are:
Ctrl
Alt
Shift
Ext
Default is "".
icon_index (int
, optional) --
The index for the icon to use in files that contain multiple icons.
Default is 0.
icon_location (str
, optional) --
The full path to a file containing icons. This is shown in the
Change Icon
dialog box by clicking the Change Icon
button.
If no file is specified and a binary is passed as the target,
Windows will attempt to get the icon from the binary file.
Default is "".
window_style (str
, optional) --
The window style the program should start in. This is shown in the
Run
field of the dialog box. Valid options are:
Normal
Minimized
Maximized
Default is "Normal".
working_dir (str
, optional) --
The full path to the working directory for the program to run in.
This is shown in the Start in
field of the dialog box.
Default is "".
True
if successful.
CLI Example:
# Modify an existing shortcut. Set it to target notepad.exe
salt '*' shortcut.modify 'C:\path\to\shortcut.lnk' 'C:\Windows\notepad.exe'