< Back
New-DbaCmConnection
Post
NAME New-DbaCmConnection
SYNOPSIS
Generates a connection object for use in remote computer management.
SYNTAX
New-DbaCmConnection [-ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>] [-Credential
<Pscredential>] [-OverrideExplicitCredential <Switch>] [-DisabledConnectionTypes
<Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>] [-DisableBadCredentialCache <Switch>]
[-DisableCimPersistence <Switch>] [-DisableCredentialAutoRegister <Switch>] [-EnableCredentialFailover <Switch>]
[-WindowsCredentialsAreBad <Switch>] [-CimWinRMOptions
<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>] [-CimDCOMOptions
<Microsoft.Management.Infrastructure.Options.DComSessionOptions>] [-EnableException <Switch>] [<CommonParameters>]
New-DbaCmConnection [-ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>]
[-UseWindowsCredentials <Switch>] [-OverrideExplicitCredential <Switch>] [-DisabledConnectionTypes
<Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>] [-DisableBadCredentialCache <Switch>]
[-DisableCimPersistence <Switch>] [-DisableCredentialAutoRegister <Switch>] [-EnableCredentialFailover <Switch>]
[-CimWinRMOptions <Microsoft.Management.Infrastructure.Options.WSManSessionOptions>] [-CimDCOMOptions
<Microsoft.Management.Infrastructure.Options.DComSessionOptions>] [-EnableException <Switch>] [<CommonParameters>]
DESCRIPTION
Generates a connection object for use in remote computer management.
Those objects are used for the purpose of cim/wmi queries, caching which protocol worked, optimizing performance
and minimizing authentication errors.
New-DbaCmConnection will create a NEW object and overwrite any existing ones for the specified computer.
Furthermore, information stored in the input beyond the computername will be discarded in favor of the new
settings.
Unless the connection cache has been disabled, all connections will automatically be registered in the cache, so
no further action is necessary.
The output is primarily for information purposes, however it may be used to pass objects and circumvent the cache
with those.
NOTE: Generally, this function need not be used, as a first connection to a computer using any connecting function
such as "Get-DbaCmObject" will automatically register a new default connection for it.
This function exists to be able to preconfigure connections.
PARAMETERS
-CimDCOMOptions [<Microsoft.Management.Infrastructure.Options.DComSessionOptions>]
Specify a set of options to use when connecting to the target computer using CIM over DCOM.
Use 'New-CimSessionOption' to create such an object.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-CimWinRMOptions [<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>]
Specify a set of options to use when connecting to the target computer using CIM over WinRM.
Use 'New-CimSessionOption' to create such an object.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ComputerName [<Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>]
The computer to build the connection object for.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-Credential [<Pscredential>]
The credential to register.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableBadCredentialCache [<Switch>]
Will prevent the caching of credentials if set to true.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableCimPersistence [<Switch>]
Will prevent Cim-Sessions to be reused.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableCredentialAutoRegister [<Switch>]
Will prevent working credentials from being automatically cached
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisabledConnectionTypes [<Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>]
Explicitly disable connection types.
These types will then not be used for connecting to the computer.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-EnableCredentialFailover [<Switch>]
Will enable automatic failing over to known to work credentials, when using bad credentials.
By default, passing bad credentials will cause the Computer Management functions to interrupt with a warning
(Or exception if in silent mode).
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-EnableException [<Switch>]
By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables
advanced scripting.
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own
try/catch.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-OverrideExplicitCredential [<Switch>]
Setting this will enable the credential override.
The override will cause the system to ignore explicitly specified credentials, so long as known, good
credentials are available.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-UseWindowsCredentials [<Switch>]
Whether using the default windows credentials is legit.
Not setting this will not exclude using windows credentials, but only not pre-confirm them as working.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-WindowsCredentialsAreBad [<Switch>]
Will prevent the windows credentials of the currently logged on user from being used for the remote connection.
Required? false
Position? named
Default value
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
NOTES
Tags: ComputerManagement, CIM
Friedrich Weinmann (@FredWeinmann)
Website: https://dbatools.io
Copyright: (c) 2018 by dbatools, licensed under MIT
License: MIT https://opensource.org/licenses/MIT
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>New-DbaCmConnection -ComputerName sql2014 -UseWindowsCredentials -OverrideExplicitCredential
-DisabledConnectionTypes CimRM
Returns a new configuration object for connecting to the computer sql2014.
- The current user credentials are set as valid
- The connection is configured to ignore explicit credentials (so all connections use the windows credentials)
- The connections will not try using CIM over WinRM
Unless caching is globally disabled, this is automatically stored in the connection cache and will be applied
automatically.
In that (the default) case, the output is for information purposes only and need not be used.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Get-Content computers.txt | New-DbaCmConnection -Credential $cred -CimWinRMOptions $options
-DisableBadCredentialCache -OverrideExplicitCredential
Gathers a list of computers from a text file, then creates and registers connections for each of them, setting
them to ...
- use the credentials stored in $cred
- use the options stored in $options when connecting using CIM over WinRM
- not store credentials that are known to not work
- to ignore explicitly specified credentials
Essentially, this configures all connections to those computers to prefer failure with the specified credentials
over using alternative credentials.
RELATED LINKS
https://dbatools.io/New-DbaCmConnection
SYNOPSIS
Generates a connection object for use in remote computer management.
SYNTAX
New-DbaCmConnection [-ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>] [-Credential
<Pscredential>] [-OverrideExplicitCredential <Switch>] [-DisabledConnectionTypes
<Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>] [-DisableBadCredentialCache <Switch>]
[-DisableCimPersistence <Switch>] [-DisableCredentialAutoRegister <Switch>] [-EnableCredentialFailover <Switch>]
[-WindowsCredentialsAreBad <Switch>] [-CimWinRMOptions
<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>] [-CimDCOMOptions
<Microsoft.Management.Infrastructure.Options.DComSessionOptions>] [-EnableException <Switch>] [<CommonParameters>]
New-DbaCmConnection [-ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>]
[-UseWindowsCredentials <Switch>] [-OverrideExplicitCredential <Switch>] [-DisabledConnectionTypes
<Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>] [-DisableBadCredentialCache <Switch>]
[-DisableCimPersistence <Switch>] [-DisableCredentialAutoRegister <Switch>] [-EnableCredentialFailover <Switch>]
[-CimWinRMOptions <Microsoft.Management.Infrastructure.Options.WSManSessionOptions>] [-CimDCOMOptions
<Microsoft.Management.Infrastructure.Options.DComSessionOptions>] [-EnableException <Switch>] [<CommonParameters>]
DESCRIPTION
Generates a connection object for use in remote computer management.
Those objects are used for the purpose of cim/wmi queries, caching which protocol worked, optimizing performance
and minimizing authentication errors.
New-DbaCmConnection will create a NEW object and overwrite any existing ones for the specified computer.
Furthermore, information stored in the input beyond the computername will be discarded in favor of the new
settings.
Unless the connection cache has been disabled, all connections will automatically be registered in the cache, so
no further action is necessary.
The output is primarily for information purposes, however it may be used to pass objects and circumvent the cache
with those.
NOTE: Generally, this function need not be used, as a first connection to a computer using any connecting function
such as "Get-DbaCmObject" will automatically register a new default connection for it.
This function exists to be able to preconfigure connections.
PARAMETERS
-CimDCOMOptions [<Microsoft.Management.Infrastructure.Options.DComSessionOptions>]
Specify a set of options to use when connecting to the target computer using CIM over DCOM.
Use 'New-CimSessionOption' to create such an object.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-CimWinRMOptions [<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>]
Specify a set of options to use when connecting to the target computer using CIM over WinRM.
Use 'New-CimSessionOption' to create such an object.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ComputerName [<Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>]
The computer to build the connection object for.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-Credential [<Pscredential>]
The credential to register.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableBadCredentialCache [<Switch>]
Will prevent the caching of credentials if set to true.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableCimPersistence [<Switch>]
Will prevent Cim-Sessions to be reused.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableCredentialAutoRegister [<Switch>]
Will prevent working credentials from being automatically cached
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisabledConnectionTypes [<Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>]
Explicitly disable connection types.
These types will then not be used for connecting to the computer.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-EnableCredentialFailover [<Switch>]
Will enable automatic failing over to known to work credentials, when using bad credentials.
By default, passing bad credentials will cause the Computer Management functions to interrupt with a warning
(Or exception if in silent mode).
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-EnableException [<Switch>]
By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables
advanced scripting.
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own
try/catch.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-OverrideExplicitCredential [<Switch>]
Setting this will enable the credential override.
The override will cause the system to ignore explicitly specified credentials, so long as known, good
credentials are available.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-UseWindowsCredentials [<Switch>]
Whether using the default windows credentials is legit.
Not setting this will not exclude using windows credentials, but only not pre-confirm them as working.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-WindowsCredentialsAreBad [<Switch>]
Will prevent the windows credentials of the currently logged on user from being used for the remote connection.
Required? false
Position? named
Default value
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
NOTES
Tags: ComputerManagement, CIM
Friedrich Weinmann (@FredWeinmann)
Website: https://dbatools.io
Copyright: (c) 2018 by dbatools, licensed under MIT
License: MIT https://opensource.org/licenses/MIT
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>New-DbaCmConnection -ComputerName sql2014 -UseWindowsCredentials -OverrideExplicitCredential
-DisabledConnectionTypes CimRM
Returns a new configuration object for connecting to the computer sql2014.
- The current user credentials are set as valid
- The connection is configured to ignore explicit credentials (so all connections use the windows credentials)
- The connections will not try using CIM over WinRM
Unless caching is globally disabled, this is automatically stored in the connection cache and will be applied
automatically.
In that (the default) case, the output is for information purposes only and need not be used.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Get-Content computers.txt | New-DbaCmConnection -Credential $cred -CimWinRMOptions $options
-DisableBadCredentialCache -OverrideExplicitCredential
Gathers a list of computers from a text file, then creates and registers connections for each of them, setting
them to ...
- use the credentials stored in $cred
- use the options stored in $options when connecting using CIM over WinRM
- not store credentials that are known to not work
- to ignore explicitly specified credentials
Essentially, this configures all connections to those computers to prefer failure with the specified credentials
over using alternative credentials.
RELATED LINKS
https://dbatools.io/New-DbaCmConnection