< Back
Set-DbatoolsConfig
Post
NAME Set-DbatoolsConfig
SYNOPSIS
Sets configuration entries.
SYNTAX
Set-DbatoolsConfig -FullName <String> [-Value <Object>] [-Description <String>] [-Validation <String>] [-Handler
<ScriptBlock>] [-Hidden] [-Default] [-Initialize] [-DisableValidation] [-DisableHandler] [-EnableException]
[-SimpleExport] [-ModuleExport] [-PassThru] [-AllowDelete] [<CommonParameters>]
Set-DbatoolsConfig -FullName <String> [-Description <String>] [-Validation <String>] [-Handler <ScriptBlock>]
[-Hidden] [-Default] [-Initialize] [-DisableValidation] [-DisableHandler] [-EnableException] -PersistedValue
<String> [-PersistedType <ConfigurationValueType>] [-SimpleExport] [-ModuleExport] [-PassThru] [-AllowDelete]
[<CommonParameters>]
Set-DbatoolsConfig -Name <String> [-Module <String>] [-Value <Object>] [-Description <String>] [-Validation
<String>] [-Handler <ScriptBlock>] [-Hidden] [-Default] [-Initialize] [-DisableValidation] [-DisableHandler]
[-EnableException] [-SimpleExport] [-ModuleExport] [-PassThru] [-AllowDelete] [<CommonParameters>]
DESCRIPTION
This function creates or changes configuration values. These can be used to provide dynamic configuration
information outside the PowerShell variable system.
PARAMETERS
-FullName <String>
The full name of a configuration element. Must be namespaced <dbatools>.<Name>. The name can have any number
of sub-segments, in order to better group configurations thematically.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Name <String>
Name of the configuration entry. If an entry of exactly this non-casesensitive name already exists, its value
will be overwritten. Duplicate names across different modules are possible and will be treated separately. If
a name contains namespace notation and no module is set, the first namespace element will be used as module
instead of name. Example: -Name "Nordwind.Server" Is Equivalent to -Name "Server" -Module "Nordwind"
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Module <String>
This allows grouping configuration elements into groups based on the module/component they serve. If this
parameter is not set, the configuration element must have a module name in the name parameter (the first
segment will be taken, irrespective of whether that makes sense).
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Value <Object>
The value to assign to the named configuration element.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Description <String>
Using this, the configuration setting is given a description, making it easier for a user to comprehend, what
a specific setting is for.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Validation <String>
The name of the validation script used for input validation. These can be used to validate make sure that
input is of the proper data type. New validation scripts can be registered using
Register-DbatoolsConfigValidation
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Handler <ScriptBlock>
A scriptblock that is executed when a value is being set. Is only executed if the validation was successful
(assuming there was a validation, of course)
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Hidden [<SwitchParameter>]
Setting this parameter hides the configuration from casual discovery. Configurations with this set will only
be returned by Get-Config, if the parameter "-Force" is used. This should be set for all system settings a
user should have no business changing (e.g. for Infrastructure related settings such as mail server).
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-Default [<SwitchParameter>]
Setting this parameter causes the system to treat this configuration as a default setting. If the
configuration already exists, no changes will be performed. Useful in scenarios where for some reason it is
not practical to automatically set defaults before loading userprofiles.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-Initialize [<SwitchParameter>]
Use this when setting configurations as part of module import. When initializing a configuration, it will only
do a thing if the configuration hasn't already been initialized (So if you load the module multiple times or
in multiple runspaces, it won't make a difference) Also, if there already was a non-initialized setting set
for a given configuration, it will then try to set the old value again. This value will be processed by
handlers, if any are set.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-DisableValidation [<SwitchParameter>]
This parameters disables the input validation - if any - when processing a setting. Normally this shouldn't be
circumvented, but just in case, it can be disabled.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-DisableHandler [<SwitchParameter>]
This parameter disables the configuration handlers. Configuration handlers are designed to automatically
process input set to a config value, in addition to writing the value. In many cases, this is used to improve
performance, by forking the value location also to a static C#-field, which is then used, rather than
searching a Hashtable. Normally these shouldn't be circumvented, but just in case, it can be disabled.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-EnableException [<SwitchParameter>]
Replaces user friendly yellow warnings with bloody red exceptions of doom! Use this if you want the function
to throw terminating errors you want to catch.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-PersistedValue <String>
In most circumstances an internal parameter. Applies the serialized value to a setting. Used for restoring
data from configuration files that should only be deserialized when the module consuming it is already
imported.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-PersistedType <ConfigurationValueType>
In most circumstances an internal parameter. Paired with PersistedValue, used to specify the data type of the
serialized object set in its serialized state.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-SimpleExport [<SwitchParameter>]
Enabling this will cause the module to use friendly json notation on export to file. This may result in loss
of data precision, but makes it easier to edit settings in file.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-ModuleExport [<SwitchParameter>]
Using 'Export-DbatoolsConfig -ModuleName <dbatools>' settings flagged with this switch will be exported to a
default path if they have been changed from the initial default value.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-PassThru [<SwitchParameter>]
Return the changed configuration setting object.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-AllowDelete [<SwitchParameter>]
By default, settings that have been once defined are considered unremovable. Some workflows however require
being able to fully dump configuration settings. Enable this switch to make a configuration setting deletable.
Note:
- Settings that are initialized, can only be declared deletable during initialization. Later attempts to
change this, as well as previous settings will be ignored.
- Settings that are defined and enforced by policy cannot be deleted no matter what.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
Sqlcollaborative.Dbatools.Configuration.Config
NOTES
---------------------- Example 1: Simple ----------------------
C:\\PS> Set-DbatoolsConfig -FullName Path.DbatoolsData -Value E:\\temp\\dbatools
Updates the configuration entry for Path.DbatoolsData to E:\\temp\\dbatools
RELATED LINKS
Online Documentation https://dbatools.io/Set-DbatoolsConfig
SYNOPSIS
Sets configuration entries.
SYNTAX
Set-DbatoolsConfig -FullName <String> [-Value <Object>] [-Description <String>] [-Validation <String>] [-Handler
<ScriptBlock>] [-Hidden] [-Default] [-Initialize] [-DisableValidation] [-DisableHandler] [-EnableException]
[-SimpleExport] [-ModuleExport] [-PassThru] [-AllowDelete] [<CommonParameters>]
Set-DbatoolsConfig -FullName <String> [-Description <String>] [-Validation <String>] [-Handler <ScriptBlock>]
[-Hidden] [-Default] [-Initialize] [-DisableValidation] [-DisableHandler] [-EnableException] -PersistedValue
<String> [-PersistedType <ConfigurationValueType>] [-SimpleExport] [-ModuleExport] [-PassThru] [-AllowDelete]
[<CommonParameters>]
Set-DbatoolsConfig -Name <String> [-Module <String>] [-Value <Object>] [-Description <String>] [-Validation
<String>] [-Handler <ScriptBlock>] [-Hidden] [-Default] [-Initialize] [-DisableValidation] [-DisableHandler]
[-EnableException] [-SimpleExport] [-ModuleExport] [-PassThru] [-AllowDelete] [<CommonParameters>]
DESCRIPTION
This function creates or changes configuration values. These can be used to provide dynamic configuration
information outside the PowerShell variable system.
PARAMETERS
-FullName <String>
The full name of a configuration element. Must be namespaced <dbatools>.<Name>. The name can have any number
of sub-segments, in order to better group configurations thematically.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Name <String>
Name of the configuration entry. If an entry of exactly this non-casesensitive name already exists, its value
will be overwritten. Duplicate names across different modules are possible and will be treated separately. If
a name contains namespace notation and no module is set, the first namespace element will be used as module
instead of name. Example: -Name "Nordwind.Server" Is Equivalent to -Name "Server" -Module "Nordwind"
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Module <String>
This allows grouping configuration elements into groups based on the module/component they serve. If this
parameter is not set, the configuration element must have a module name in the name parameter (the first
segment will be taken, irrespective of whether that makes sense).
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Value <Object>
The value to assign to the named configuration element.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Description <String>
Using this, the configuration setting is given a description, making it easier for a user to comprehend, what
a specific setting is for.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Validation <String>
The name of the validation script used for input validation. These can be used to validate make sure that
input is of the proper data type. New validation scripts can be registered using
Register-DbatoolsConfigValidation
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Handler <ScriptBlock>
A scriptblock that is executed when a value is being set. Is only executed if the validation was successful
(assuming there was a validation, of course)
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Hidden [<SwitchParameter>]
Setting this parameter hides the configuration from casual discovery. Configurations with this set will only
be returned by Get-Config, if the parameter "-Force" is used. This should be set for all system settings a
user should have no business changing (e.g. for Infrastructure related settings such as mail server).
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-Default [<SwitchParameter>]
Setting this parameter causes the system to treat this configuration as a default setting. If the
configuration already exists, no changes will be performed. Useful in scenarios where for some reason it is
not practical to automatically set defaults before loading userprofiles.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-Initialize [<SwitchParameter>]
Use this when setting configurations as part of module import. When initializing a configuration, it will only
do a thing if the configuration hasn't already been initialized (So if you load the module multiple times or
in multiple runspaces, it won't make a difference) Also, if there already was a non-initialized setting set
for a given configuration, it will then try to set the old value again. This value will be processed by
handlers, if any are set.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-DisableValidation [<SwitchParameter>]
This parameters disables the input validation - if any - when processing a setting. Normally this shouldn't be
circumvented, but just in case, it can be disabled.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-DisableHandler [<SwitchParameter>]
This parameter disables the configuration handlers. Configuration handlers are designed to automatically
process input set to a config value, in addition to writing the value. In many cases, this is used to improve
performance, by forking the value location also to a static C#-field, which is then used, rather than
searching a Hashtable. Normally these shouldn't be circumvented, but just in case, it can be disabled.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-EnableException [<SwitchParameter>]
Replaces user friendly yellow warnings with bloody red exceptions of doom! Use this if you want the function
to throw terminating errors you want to catch.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-PersistedValue <String>
In most circumstances an internal parameter. Applies the serialized value to a setting. Used for restoring
data from configuration files that should only be deserialized when the module consuming it is already
imported.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-PersistedType <ConfigurationValueType>
In most circumstances an internal parameter. Paired with PersistedValue, used to specify the data type of the
serialized object set in its serialized state.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-SimpleExport [<SwitchParameter>]
Enabling this will cause the module to use friendly json notation on export to file. This may result in loss
of data precision, but makes it easier to edit settings in file.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-ModuleExport [<SwitchParameter>]
Using 'Export-DbatoolsConfig -ModuleName <dbatools>' settings flagged with this switch will be exported to a
default path if they have been changed from the initial default value.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-PassThru [<SwitchParameter>]
Return the changed configuration setting object.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-AllowDelete [<SwitchParameter>]
By default, settings that have been once defined are considered unremovable. Some workflows however require
being able to fully dump configuration settings. Enable this switch to make a configuration setting deletable.
Note:
- Settings that are initialized, can only be declared deletable during initialization. Later attempts to
change this, as well as previous settings will be ignored.
- Settings that are defined and enforced by policy cannot be deleted no matter what.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
Sqlcollaborative.Dbatools.Configuration.Config
NOTES
---------------------- Example 1: Simple ----------------------
C:\\PS> Set-DbatoolsConfig -FullName Path.DbatoolsData -Value E:\\temp\\dbatools
Updates the configuration entry for Path.DbatoolsData to E:\\temp\\dbatools
RELATED LINKS
Online Documentation https://dbatools.io/Set-DbatoolsConfig