Citrix provider supports common provider commands such as the Get-ChildItem command and the Set-ItemProperty command.
What is Windows Registry?
Let’s get our basics straight before diving in. The Windows Registry is the nerve center of your Windows operating system and the apps that call it home. It’s a database storing vital configuration info.
Meddling in the Registry without care is like juggling chainsaws — thrilling but risky!
The Registry is a maze of keys within keys, storing values with specific data types. It’s a flexible repository for system and application settings, organized into ‘hives’ — logical groupings that Windows loads during startup.
Remember the days when editing the Registry was a daredevil’s game, done through regedit.exe?
Windows NT changed the game with the reg.exe command, ushering in safer programmatic management. And let’s not forget WMI (Windows Management Instrumentation), another powerful tool for Registry wrangling.
How to Set a Registry Key with PowerShell
For IT professionals working with PowerShell, life got easier with the introduction of the Registry provider. This nifty tool simplifies Registry tasks, transforming complex chores into a walk in the park.
PowerShell could have gone the route of creating a zillion cmdlets for every data store — Registry, files, certificates, you name it.
But instead, it introduced providers, an intermediary layer that turns these data stores into something akin to a file store. You can use familiar commands across different data types, thanks to these providers.
Curious about available providers? Run the `Get-PSProvider` cmdlet. It’ll introduce you to:
- Registry: This provider deals with the Windows Registry, offering access to keys like HKLM (local machine) and HKCU (current user).
- Alias, Environment, and Function: These providers handle aliases, environment variables, and functions.
- FileSystem: This one’s for managing files and folders.
- Certificate: For working with certificates.
Registry Value Entries: The Building Blocks
Let’s explore Registry Value Entries and how they play a role in PowerShell scripting.
Think of Registry Value Entries as attributes of registry keys. PowerShell’s *-ItemProperty cmdlets are your tools for managing these.
Here’s how you can use them in real-world scenarios:
Scenario 1
Imagine creating a “Version” registry value under the key “HKCU:\Software\Test\MyKey” with a value of “12“.
You might be tempted to use the `New-ItemProperty` cmdlet like this:
$RegistryPath = 'HKCU:\Software\Test\MyKey’ $Name = 'Version' $Value = ‘12’ New-ItemProperty -Path $RegistryPath -Name $Name -Value $Value -PropertyType DWORD -Force
But if “HKCU:\Software\Test\MyKey” doesn’t exist, you’ll hit an error.
To avoid this, use Test-Path to check for the key’s existence, and New-Item to create it if needed:
New-ItemProperty : Cannot find path 'HKCU:\Software\Test\MyKey' because it does not exist.
To address this issue more gracefully, you can take a safer approach:
# Set variables to indicate value and key to set
$RegistryPath = 'HKCU:\Software\Test\MyKey’
$Name = 'Version'
$Value = '12'
# Create the key if it does not exist
If (-NOT (Test-Path $RegistryPath)) { New-Item -Path $RegistryPath -Force | Out-Null
}
# Now set the value
New-ItemProperty -Path $RegistryPath -Name $Name -Value $Value -PropertyType DWORD -ForceThis modified script first checks whether the registry key exists using `Test-Path`. If it doesn’t exist, it creates the key using `New-Item`. This way, you ensure that the required registry structure is in place before setting the value entry.
If we know that the registry key value already exists and we want to modify the value, we can use the `Set-ItemProperty` cmdlet. Think of each Registry Value Entry as an attribute of a particular registry key.
Scenario 2
Imagine you have a scenario where you want to update an existing registry value entry called “Version” under the key “HKCU:\Software\CommunityBlog\Scripts” with a new value, let’s say “13.”
You can achieve this using the `Set-ItemProperty` cmdlet. Here’s an example of how you can do it:
# Define the registry path and property name $RegistryPath = 'HKCU:\Software\Test\MyKey’ $PropertyName = 'Version' # Specify the new value $NewValue = '13' # Use Set-ItemProperty to update the registry value Set-ItemProperty -Path $RegistryPath -Name $PropertyName -Value $NewValue
By running this script, you can effectively change the “Version” value in the specified registry key to “13.”
This demonstrates how `Set-ItemProperty` can be a valuable tool for managing and updating registry values within your PowerShell scripts.
Tinkering with the registry, whether through the Registry Editor or PowerShell commands, can have serious consequences if done improperly.
Always exercise caution, back up critical data, and be certain of the changes you’re making. The power of the registry comes with the responsibility to use it wisely!
Set a registry key with PowerShell App Deployment Toolkit
Now, for the IT pros responsible for getting software up and running on a bunch of Windows computers. Sometimes, you need to tweak things behind the scenes to make sure the software behaves just right. That’s where the `Set-RegistryKey` function steps in.
This custom cmdlet makes it much easier to work with registry keys as opposed to the example we just had a look above. With this you don’t need to worry about additional checks in the registry by using Test-Path cmdlet.
This handy tool lets you tinker with the Windows Registry, a database that holds all sorts of settings for your operating system and applications. With `Set-RegistryKey`, you can make changes, create new settings, or fine-tune existing ones to match your needs.
Picture this: you’re deploying a new app, and it’s got a particular setting that needs to be just so. You can use `Set-RegistryKey` to make sure that setting is dialed in perfectly on all the computers you’re working with. No need to manually mess around in the Registry – it’s all automated.
Here’s a quick example of how you might use it:
Let’s say you’re deploying a new application, and it needs a specific registry setting to work correctly. You can use `Set-RegistryKey` to create that setting and make sure it’s set to the right value. No fuss, no manual Registry editing – it’s all taken care of.
# Set a registry value to configure application behavior Set-RegistryKey -Key 'HKLM\Software\YourApplication' -Name 'SettingName' -Value 'DesiredValue' # Create a new registry key if it doesn't exist Set-RegistryKey -Key 'HKLM\Software\YourApplication\NewKey' # Modify an existing registry value Set-RegistryKey -Key 'HKCU\Software\YourApplication' -Name 'ExistingSetting' -Value 'UpdatedValue'
Conclusion
In essence, the Set-RegistryKey cmdlet in the PowerShell Application Deployment Toolkit is your secret weapon for smooth software deployments. It’s like having a magic wand for the Windows Registry, ensuring your software runs seamlessly on every computer.
Alex Marin
Application Packaging and SCCM Deployments specialist, solutions finder, Technical Writer at Advanced Installer.
Popular Articles
FAQ
How do filters get applied?
This question is not just limited to using the provider.
Why errors seen in Citrix Studio after changes are made in provider?
After creating the policies, why do policies get deleted when viewing policies in the Citrix Studio?
Empty policies are not allowed in the database to ensure efficiency when policies are evaluated by VDAs. Empty policies are policies without settings. The only exception is the Unfiltered policy, which is a built-in policy. It is impossible to create an empty policy in the Citrix Studio. But it is possible to create an empty policy using the provider. Some people might have scripts to create some empty policies temporarily. But if the policies are viewed using Citrix Studio, those policies are deleted and will not be visible in the Citrix Studio. To avoid having your temporary empty policies deleted, do not use the Citrix Studio to view policies while changes are being made.
How to retrieve the policy updates that is done in the Citrix Studio?
If you update a policy in the Citrix Studio and you want to pick it up in your current PowerShell session, you can use the Refresh() command.
PS GP:\User> (Get-PSDrive GP).Refresh()
<!--NeedCopy-->Install the Citrix Group Policy Provider
- For on-premises installations – The provider is installed as part of the Citrix controller installation when installing Citrix Studio. You can install Citrix Studio on a supported Windows machine.
- For Citrix Cloud deployments – The Citrix Remote PowerShell SDK is required. For more information about this SDK, see SDKs and APIs documentation.
Setting policy priorities
One of the properties of the policy object is Priority, which is an integer. The priority of a policy specifies the precedence in calculating the result of applying all the policies in the site. The priority number is automatically assigned when a new policy is created. The larger the priority number, the lower the priority of the policy.
When a new policy is created, the priority of the policy is assigned to the lowest. This setting means that the priority number of the policy is assigned to one larger than the existing lowest priority number. Priority numbers are 1-based and there are no gaps allowed. This setting means that the largest priority number always is the number of policies. For example, if there are three policies defined, the priority of the next policy will be 4.
Modify policy priorities
To update the priority of a policy, you use the Set-ItemProperty command that sets the priority of a policy. For example:
PS GP:\User> Get-ItemProperty Policy123
Name : Policy123
Description :
Enabled : False
Priority : 102
MergedPriority : 0
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User
PSChildName : Policy123
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
PS GP:\User> Set-ItemProperty Policy123 -Name Priority -Value 10
PS GP:\User> Get-ItemProperty Policy123
Name : Policy123
Description :
Enabled : False
Priority : 10
MergedPriority : 0
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User
PSChildName : Policy123
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
<!--NeedCopy-->In this example, the newly created Policy123 is automatically assigned the priority number 102. To move it to priority 10, set the value of Priority to 10.
Assigning the priority of a policy changes the priorities of all the policies behind it. In this example, the policy that was at priority 10 is now at priority 11. The policy that had priority number 11 is now at priority number 12, and so on. The priorities of the policies ahead of the new priority value are not changed. This setting means that the priorities of the policies at 1 through 9 are not changed.
In this provider, policy priorities can only be changed one at a time.
Removing a policy results in the policies with lower priorities to get moved up by one.
Priority number cannot be more than the total number of policies. For example, if we have 102 policies, no policy can be set to priority 103 or larger. If the priority of a policy is assigned a number greater than the number of policies available, the priority of the policy is set to the number of existing policies. This behavior is convenient when you want to move a policy to the lowest priority. For example, if there are only 10 policies and if you set the priority of the Unfiltered policy to 10000, the priority of the Unfiltered policy will be set to 10, which is the lowest priority.
Create, modify, or delete a filter for a policy
Create a filter for a policy
PS GP:\User\Policy123\Filters\ClientName\> New-Item ClientNameFilter1
Synopsis : Allow - ClientNameFilter1
FilterValue : ClientNameFilter1
Name : ClientNameFilter1
FilterType : ClientName
Mode : Allow
Enabled : True
Comment :
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123\Filters\ClientName\ClientNameFilter1
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123\Filters\ClientName
PSChildName : ClientNameFilter1
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
PSIsContainer : False
<!--NeedCopy-->Modify a filter for a policy
PS GP:\User\Policy123\Filters\ClientName\> Set-ItemProperty ClientNameFilter1 -Name FilterValue -Value "Windows11"
PS GP:\User\Policy123\Filters\ClientName\> Get-ItemProperty ClientNameFilter1
Synopsis : Allow - Windows11
FilterValue : Windows11
Name : ClientNameFilter1
FilterType : ClientName
Mode : Allow
Enabled : True
Comment :
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123\Filters\ClientName\ClientNameFilter1
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123\Filters\ClientName
PSChildName : ClientNameFilter1
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
<!--NeedCopy-->Delete a filter for a policy
To remove a filter, use the Remove-Item command. No child objects are present under a filter object, which is a leaf node. As a result, no need to use the -Recurse switch:
PS GP:\User\Policy123\Filters\ClientName\> Remove-Item ClientNameFilter1
PS GP:\User\Policy123\Filters\ClientName\>
<!--NeedCopy-->Navigating the object tree
| Computer policy | User policy |
|---|---|
| Computer policies are policy objects that include only computer settings. | User policies are policy objects that include only user settings. |
| Computer settings are settings that are validated for all user connections in the VDAs. Computer settings are applied only at the time of VDA reboots, restart of the Citrix Broker Agent (Citrix Desktop Service), or at 90 minute intervals. | User settings are settings that are validated at every user sign-in or reconnect. |
The objects in the Settings node of a policy node are settings and are organized using categories. Each category node includes subcategories or individual setting objects, which are the leaves of the tree under the Settings node. Nodes for all the settings are always defined and they cannot be created or removed. You can only configure a Settings node by changing the node’s properties.
The objects under the Filters node of a policy node are filters, that you can create, modify, and delete.
Merge user and computer policies
- No priority inversion is allowed. Priority inversion is a condition where the computer and user portions of two policies are in reverse orders. For example, consider we have the user policies
Policy0andPolicy1with priority numbers 1 and 2 and the computer policiesPolicy0andPolicy1with priority numbers 6 and 3. In this example, the priority inversion occurs betweenPolicy0andPolicy1. The policy numbers do not have to be consecutive and they do not have to be the same numbers. If the computer policiesPolicy0andPolicy1have priorities 3 and 6, there is no priority inversion occurs betweenPolicy0andPolicy1. For the entire set of policies, there must be no priority inversion between any two policies. - Filters must be consistent. The computer and user portions of the same filter type must have filters that are consistent. Consider a scenario where the user policy
Policy0has a filter to allow delivery groupDg0and the computer policyPolicy0has a delivery group filter that deniesDg0. In this example, there is filter inconsistency between the two portions ofPolicy0. - Policies must be of the same state. Both the user and computer value of a policy must be set to the same state. They must be both either enabled or disabled.
The Citrix Studio detects these conditions and refuses to display the policies when such a condition exists.
The
MergedPriorityproperty is used by Citrix Studio to maintain the priority numbers of the merged policies. The provider must not alter theMergedPriorityproperty. It is reset every time policies are opened in the Citrix Studio.
Prerequisites
- Familiarity with Windows providers
Create, modify, or delete a policy
Create a policy
PS GP:\Computer\> New-Item Policy123
Name : Policy123
Description :
Enabled : False
Priority : 7
MergedPriority : 0
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\Computer\Policy123
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\Computer
PSChildName : Policy123
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
PSIsContainer : True
<!--NeedCopy-->After the policy is created, the properties of the policy object are displayed.
Modify a policy
You can only modify the Description, Enabled, and the Priority properties for a policy. Do not set the MergedPriority property because only the Citrix Studio uses this property.
PS GP:\Computer\> Set-ItemProperty -Path Policy123 -Name Description -Value "test policy"
PS GP:\Computer\> Get-ItemProperty Policy123
Name : Policy123
Description : test policy
Enabled : False
Priority : 7
MergedPriority : 0
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\Computer\Policy123
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\Computer
PSChildName : Policy123
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
<!--NeedCopy-->To display the result of the Set-ItemProperty command, use the Get-ItemProperty command.
Delete a policy
PS GP:\Computer\> Remove-Item Policy123
Confirm
The item at GP:\Computer\Policy123 has children and the Recurse parameter was not specified. If you continue, all
children will be removed with the item. Are you sure you want to continue?
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): a
PS GP:\Computer\>
<!--NeedCopy-->The policy objects might have child objects. If you try to delete a policy object that has child objects, the child objects are also removed. As a result, the PowerShell needs a confirmation for the removal of all child objects.
PS GP:\Computer\> Remove-Item Policy123 -Recurse
PS GP:\
Computer\>
<!--NeedCopy-->Select setting for a policy
PS GP:\User\> New-Item Policy123
Name : Policy123
Description :
Enabled : False
Priority : 102
MergedPriority : 0
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User
PSChildName : Policy123
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
PSIsContainer : True
PS GP:\User\> cd Policy123
PS GP:\User\Policy123> dir
Filters
Settings
PS GP:\User\Policy123> cd .\Settings\
PS GP:\User\Policy123\Settings\> dir
ICA
Receiver
UserProfileManager
VirtualDesktopAgent
PS GP:\User\Policy123\Settings\>
<!--NeedCopy-->PS GP:\User\Policy123\Settings\> Set-ItemProperty -Path .\ICA\ReadonlyClipboard\ -Name State -Value Enabled
PS GP:\User\Policy123\Settings\> Get-ItemProperty -Path .\ICA\ReadonlyClipboard\
State : Enabled
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123\Settings\ICA\ReadonlyClipboard
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123\Settings\ICA
PSChildName : ReadonlyClipboard
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
<!--NeedCopy-->To display the result of the Set-ItemProperty command, use the Get-ItemProperty command.
As shown in the example, to select a setting, set the value of the State property of the setting to Enabled. For settings whose value type is bool, for example, ReadonlyClipboard, only the State property needs to be set. For settings whose value type is not bool, the Value property might need to be set. If the Value property is not set, the default value of the setting is used.
You can only use the internal name of the setting. For many settings, the internal names and the displayed English names are different. To find the correct internal names, use the setting definitions reference section.
PowerShell auto-completion can be used in navigating the settings tree, which saves much typing. Some settings are under several layers of categories.
Setting objects can only be selected by setting the value of the State property to Enabled or Allowed. A setting can only be deselected by setting the value of State to Disabled or Prohibited. Set the value of State to UseDefault to reset the setting. Setting objects cannot be created or removed.
Deselect a setting for a policy
PS GP:\User\Policy123\Settings\> Set-ItemProperty -Path .\ICA\ReadonlyClipboard\ -Name State -Value Disabled
PS GP:\User\Policy123\Settings\> Get-ItemProperty -Path .\ICA\ReadonlyClipboard\
State : Disabled
PSPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123\Settings\ICA\ReadonlyClipboard
PSParentPath : Citrix.Common.GroupPolicy\CitrixGroupPolicy::GP:\User\Policy123\Settings\ICA
PSChildName : ReadonlyClipboard
PSDrive : GP
PSProvider : Citrix.Common.GroupPolicy\CitrixGroupPolicy
<!--NeedCopy-->Manage policies using the provider
- Full administrators with default rights to manage policies.
- Custom administrators with the permission to manage and view policies.
To begin managing policies using the provider, you must first load the provider to PowerShell session, which might be a Windows PowerShell console or a script to use the provider. After loading the provider to PowerShell session, you must mount the provider to a drive.
Step 1: Load the provider
Import-Module Citrix.GroupPolicy.Commands
<!--NeedCopy--> Add-PsSnapin Citrix.Common.GroupPolicy
<!--NeedCopy-->If the provider does not load using the
Import-Module Citrix.GroupPolicy.Commandsor theAdd-PsSnapin Citrix.Common.GroupPolicycommand you might not have the provider installed in your system..
Step 2: Mount the provider
- The
-PsProviderparameter specifies the name of the provider. The value must be specified and must beCitrixGroupPolicy. - The
-Nameparameter specifies the name of the drive. - The
-Rootparameter specifies the root of the drive in the hierarchy of the provider’s object tree. Usually the root of the tree is specified. - The
-Controllerparameter specifies the Citrix controller to use.
- On-premises: Use
localhostto connect to a controller running on the same machine. When a remote host is specified, the remote host must be a Citrix controller and the necessary ports must be open for remotely connecting to the controller. The signed in user must be also an administrator of the remote site. If a remote connection is to be used, the fully qualified domain name (FQDN) of the remote controller with an optional port number must be specified. If no port number is specified, by default port 80 is used. To mount a drive for on-premises deployments, run the following command:
New-PsDrive -PsProvider CitrixGroupPolicy -Name GP -Root \ -Controller localhost
<!--NeedCopy-->- Cloud: If the controller is a cloud controller, the connection must be made using the Citrix Remote PowerShell SDK. Run the following command to connect to a cloud environment. Before running this command, ensure that you are authenticated using the
Get-XDAuthenticationcommand or you have set an authentication profile. For example,Set-XdCredentials.
New-PsDrive -PsProvider CitrixGroupPolicy -Name GP -Root \ -Controller $GLOBAL:XDSDKProxy -BearerToken $GLOBAL:XDAuthToken
<!--NeedCopy-->After the New-PsDrive command is successfully run, the complete policy information is created as a file system under the name provided.
Recommendation on efficient use of the provider
Behind the scenes, the provider automatically saves every change whenever a PowerShell command like New-Item or Set-ItemProperty is run. The entire policy data is stored as a binary blob. As a result, every change might result in thousands of bytes written to the controller’s site database.
If you connect to the local computer or if you have few number of policies, settings, and filters configured, you might not notice any delays. But if you edit a large blob that has dozens of policies and many settings and filters, or if the controller is remote, you might notice delays after a change is made.
The unnecessary saves to the database can be turned off. Set the provider’s drive property AutoWriteBack value to $false to clear the unnecessary saves:
PS GP:\User> (Get-PSDrive GP).AutoWriteBack
True
PS GP:\User> (Get-PSDrive GP).AutoWriteBack = $false
PS GP:\User> (Get-PSDrive GP).AutoWriteBack
False
PS GP:\User>
<!--NeedCopy-->After the AutoWriteBack is set to $false, you must save the changes because changes will not be automatically saved. You can save the changes using the drive’s Save() method:
PS GP:\User> (Get-PSDrive GP).Save()
PS GP:\User>
<!--NeedCopy-->Turning off auto save is recommended in scripts. It can significantly improve the execution speed of the scripts.
Setting definitions reference
There are already over 400 settings. Although in the UI, settings can be searched, it’s not easy to find the setting that you want to configure in the provider. When you write a script, you might use the Citrix Studio to find the settings. But when you do not have access to the Citrix Studio, you need a different source to navigate the setting hierarchy.
You can find a complete reference of Citrix policy settings in the Policy documentation.
