In the Rider settings dialog (Ctrl+Alt+S), you can look at page icons to see which setting-management mechanism is used for specific pages:
Pages that are not marked with any icon host environment settings, which are saved in your user profile.
Rider's back-end features are inherited from ReSharper. Therefore, preferences for these features are made compatible with ReSharper and managed using the mechanism of layered settings.
Default settings and setting layers
Out of the box, JetBrains Rider comes with the default set of preferences, which are based on conventions and best practices in the .NET world. These default settings are hard-coded in the product and you can always reset to the defaults if necessary. If you change any layer-based settings, your change is saved in a settings layer and JetBrains Rider applies it overriding the corresponding default setting. Initially, JetBrains Rider suggests three layers, in which you can save your preferences: This computer, Solution team-shared, and Solution personal.
'This computer' layer
This settings layer is designated for your personal global settings and applies for all solutions on your local machine.
The corresponding settings file is saved as:
- Windows: %USERPROFILE%\.RiderXXX\config\resharper-host\GlobalSettingsStorage.DotSettings
- macOS: ~/Library/Preferences/RiderXXX/config/resharper-host/GlobalSettingsStorage.DotSettings
- Linux: ~/.RiderXXX/config/resharper-host/GlobalSettingsStorage.DotSettings
'Solution team-shared' layer
This layer is designated for common settings that enforce your team preferences for the current solution, e.g. naming style, formatting rules, etc. Settings in this layer override settings in This computer layer.
The corresponding settings file <SolutionName>.sln.DotSettings is saved in the solution folder.
As soon as this file is added to your VCS and the team members get it, they will have settings from this file applied automatically without reloading the solution.
'Solution personal' layer
This layer allows you to override team-shared settings without changing them. You may find this helpful if you need to have some settings applied only in this solution and independently of your team.
The corresponding settings file <SolutionName>.sln.DotSettings.user is saved in the solution folder. You should not add it to your VCS.
Consider the illustration below. You can see that initially all setting layers are empty and therefore JetBrains Rider can 'see through them' and apply the default settings:
In fact, initially the settings-layer files do not exist, they are first created whey you modify and save some layer-based setting. But if a setting file exists, it is still 'transparent' for all layer-based setting that are not defined in it.
Saving and overriding layer-based settings
Each time you change some layer-based setting in Rider settings (Ctrl+Alt+S), you can choose where to save your changes.
Save (Smart Save)
This applies the 'smart save' logic.
Use it to save your modifications and keep team-shared and/or custom layers (if any) intact. In other words, use Save if you just want to save your changes without bothering about setting layers.
Save will save your changes to 'This computer' setting layer, then — if there are other values for the modified settings in the 'Solution team-shared' and/or custom layers — the changes will also be saved to the 'Solution personal' layer to override values in other layers.
Consider the example in the illustration below. Suppose you changed three layer-based settings and had 'green' instead of ‘blue’ values; these changes were saved in 'This computer' layer. Then, your team has decided to have settings A and C ‘yellow’ within your team-shared solution, so these values were saved by a team-lead in the 'Solution team-shared' layer, JetBrains Rider applied them as soon as you pulled changes from your VCS. Finally, you realized that you felt more comfortable with the ‘green’ value for setting A, and you changed and saved it again, this time it was also saved in the 'Solution personal' layer, which allowed you to have the desired value applied without changing the team-shared layer:
Save To (Save to Specific Layer)
You will need to use these commands to save modified settings to the 'Solution team-shared' layer or to a custom layer. You can also save the modifications to any other layer if you need it for some purpose.
The only catch with saving a layer-based setting to a specific layer is that it may NOT be applied if the same setting is defined with another value anywhere in other layers above in the stack of layers. The illustration below shows how we tried to change setting C to ‘red' in 'This computer' layer and why the resulting setting failed to be changed.
Managing setting layers
By default, you can share JetBrains Rider settings per solution using the 'Solution team shared' layer — the only thing you need to do is to put the *.dotSettings file under version control.
If you want to share settings in other ways, you would need to learn how to create new setting layers, import and export them. For these purposes, JetBrains Rider provides the Settings Layers dialog, available in the Settings dialog (by clicking the Manage Layers button).
Custom setting layers are added under existing default layers. E.g., if you want the settings from the custom layer to be applied for all solutions, add it under 'This computer' layer; otherwise add it under one of the solution-specific layers depending on whether you want it to override the team-shared settings or not.
As soon as a custom setting layer is added, it appears in the Save selector in the Settings dialog, using which you can save modified settings to the custom layer. You can also modify settings in this layer by editing this layer.
To add a custom setting layer
- In the Settings Layers dialog, select one of the default layers, under which you would like to add a layer.
- Do one of the following:
- Click Add Layer , then click Create Settings File to create a new empty setting layer or Open Settings File /Add from URI to include an existing setting layer either from your filesystem or from any URI.
- Right-click and choose one of the corresponding commands in the Add Layer selector.
- Depending on the selected command, either specify a name and location for the new setting layer file, or select an existing setting layer file with .DotSettings extension.
- Settings from the added layer are applied according to its position in the stack of layers, which you can see in the Settings Layers dialog, i.e. if some setting is defined in the upper layer, the value from the upper layer is used in the resulting settings. If necessary, you can rearrange custom setting layers within the group with the Move up and Move down buttons that become available when you select the layer.
As an alternative to saving modified settings to a specific layer using the Save selector in the Settings dialog, you can open a specific setting layer for editing.
To edit a specific setting layer
- In the Settings Layers dialog, select a setting layer that you want to edit.
- Do one of the following:
- Click Edit Layer .
- Right-click and select Edit in the context menu.
- Double-click the desired layer.
- The Settings dialog opens, where the name of the layer and its location are displayed at the top of the dialog: Note that the values of the settings that you see in this mode are either taken from the default values or from values defined in the edited layer. If a setting is not defined in the edited layer, the value from the default settings is shown (e.g. the value for 'Setting B' in the illustration below). Note also that when you are editing a settings layer, you will not see directory-based settings.
- Edit the settings in the layer as necessary and click Save to save the changes.
You can export a specific subset of settings from any setting layer to a new settings file. This file can be then used on another instance of JetBrains Rider to apply these settings.
To export layer-based settings from a setting layer to file
- In the Settings Layers dialog, select a setting layer from which settings should be exported.
- Do one of the following:
- On the toolbar, click Import/Export From , then click Export to File.
- Right-click the layer and choose Export to File in the context menu.
- In the Export to File dialog that opens, specify group(s) of settings to be exported and click OK, then specify the name and location for the setting layer file.
As an alternative to adding a custom setting layer, you can copy a subset of settings from this custom layer to one of the existing default or custom layers.
To import layer-based settings from a setting layer file to a setting layer
- In the Settings Layers dialog, select a setting layer where you want to import settings.
- Do one of the following:
- On the toolbar, click Import/Export Settings . Depending on the location of the file to be imported, click Import from File or Import from URL.
- Right-click the layer. Click Import from in the context menu, then click Import from File or Import from URL.
- Specify location of the file to be imported. Pay attention, that if you have chosen to import from URL, the path to the file should be specified in the UNC format.
- In the Import from File dialog that opens, specify group(s) of settings to be imported and click OK.
JetBrains Rider also allows you to copy a subset of settings from one mounted setting layer to another.
To copy layer-based settings from one layer to another
- In the Settings Layers dialog, select a setting layer from which you want to copy settings.
- Do one of the following:
- On the toolbar, click Copy Settings To , then select the target setting layer.
- Right-click the layer, select Copy Settings To in the context menu, and then select the target setting layer.
- In the Copy To dialog that opens, specify group(s) of settings to be copied and click OK.
If necessary, you can clear all settings saved in a specific layer. To do so, right-click the layer and click Reset in the context menu.
Moreover, you can reset all settings in all predefined layers and unmount all custom setting layers, thus returning all settings to their default values. To do that, click Reset All Settings on the toolbar.
You can also disable custom setting layers temporarily by clearing check boxes next to them or unmount a specific custom setting layer by right-clicking on it and selecting Remove in the context menu.
Upgrading layer-based settings to newer versions
Sometimes a newer version of JetBrains Rider may introduce modifications to the storage format of layer-based settings. In such cases, the affected settings files are upgraded automatically on the first start of the new version — JetBrains Rider just adds settings with modified format to the settings file. It also adds an entry, which says what was upgraded to prevent further upgrades. For example:
However, even if a layer-based settings file was upgraded, it can still be used with older JetBrains Rider versions (for example, if you share this file with your teammates who didn't upgrade), because the deprecated settings are neither changed nor removed. Among other things, this means that you can safely commit changes in the automatically upgraded .dotSettings files to your VCS.
It is important to note here that when you go back to an older version after an update, then change some settings using this older version, and then return to the newer version — JetBrains Rider will not upgrade the settings for the second time. Therefore some settings that you changed might be saved in older format and not read by the newer version.
So if you (or your team) are using two different versions of JetBrains Rider simultaneously, you may want to check whether the preferences modified in one version are read correctly in another version, and if not, just make the same modification once again in the other version.