sqmSQLTool › Commands › Invoke-sqmMonitoringKey

Invoke-sqmMonitoringKey Configuration

Reads or writes monitoring registry values (SQL level, SQLFreeSpaceVersion, TSM) under HKLM:\System\dtcSoftware\sqmSQLTool on one or more computers. Remote access via WinRM; pipeline-capable.

Execution Flow

START Build regPath: HKLM:\$RegistryBase\dtcSoftware\sqmSQLTool foreach $computer in $ComputerName [pipeline-capable] if $Operation='Set' && $AutoDetectSQLFreeSpaceVersion Get-DbaAvailabilityGroup → Cluster / Standard Operation = 'Set'? if Operation='Set' Any values supplied? WARNING NO ShouldProcess None Ensure key exists (local: Test-Path / remote: Invoke-Command) Set-ItemProperty SQL(DWORD) / SQLFreeSpaceVersion / TSM Always: read current values Local: Get-ItemProperty HKLM:\… Remote: Invoke-Command (ScriptBlock) Build result: SQL / SQL_Description / SQLFreeSpaceVersion TSM / TSM_Description / Status / Message catch: add Failed result; if EnableException → throw; if !ContinueOnError → throw Return $allResults[] DONE

Synopsis

Reads or writes the sqmSQLTool monitoring registry key HKLM:\System\dtcSoftware\sqmSQLTool on one or more computers. Controls SQL monitoring level (None/Standard/Full), free-space monitoring variant (Standard/Cluster for AlwaysOn), and TSM backup monitoring (0/1). With -AutoDetectSQLFreeSpaceVersion, the function automatically checks for AlwaysOn AGs via dbatools and sets the value accordingly. Remote computers are accessed via Invoke-Command (WinRM).

The registry key is created automatically if it does not exist during a Set operation. Read operations never create the key.

Syntax

Invoke-sqmMonitoringKey
    [-ComputerName <String[]>]        # pipeline-capable
    [-Operation <Get|Set>]
    [-SQL <None|Standard|Full>]
    [-SQLFreeSpaceVersion <Standard|Cluster>]
    [-TSM <0|1>]
    [-RegistryBase <String>]
    [-AutoDetectSQLFreeSpaceVersion]
    [-Credential <PSCredential>]
    [-ContinueOnError]
    [-EnableException]

Parameters

ParameterTypeDefaultDescription
-ComputerNameString[]$env:COMPUTERNAMEOne or more target computers. Accepts pipeline input.
-OperationStringGetGet: read current values. Set: write the supplied values.
-SQLString—SQL monitoring level: None (DWORD 0), Standard (1), Full (2).
-SQLFreeSpaceVersionString—Standard (standalone instance) or Cluster (AlwaysOn AG).
-TSMInt—TSM backup monitoring: 0 = inactive, 1 = active.
-RegistryBaseStringSystemRegistry hive path base under HKLM (e.g. System, Software).
-AutoDetectSQLFreeSpaceVersionSwitchfalseWhen set with -Operation Set, auto-detect via Get-DbaAvailabilityGroup and set Cluster or Standard.
-CredentialPSCredential—Windows credential for WinRM access to remote computers.
-ContinueOnErrorSwitchfalseContinue with the next computer on error instead of stopping.
-EnableExceptionSwitchfalseThrow terminating exceptions (overrides ContinueOnError).

Return Value

Array of [PSCustomObject] — one entry per computer:

PropertyDescription
ComputerNameTarget computer name.
RegistryPathFull registry path that was read/written.
SQLRaw DWORD value (0/1/2) or null if not set.
SQL_DescriptionDecoded: NoMonitoring / ServiceMonitoring / FullMonitoring.
SQLFreeSpaceVersionString value: Standard or Cluster.
TSMRaw value 0/1 or null if not set.
TSM_DescriptionInactive or Active.
StatusOK / Updated / Created / KeyNotFound / WhatIfSkipped / Failed.
MessageHuman-readable status message.

Examples

# Read monitoring key on local computer
Invoke-sqmMonitoringKey

# Set Standard SQL monitoring with TSM active, auto-detect AG topology
Invoke-sqmMonitoringKey -Operation Set -SQL Standard -TSM 1 -AutoDetectSQLFreeSpaceVersion

# Set Full monitoring on multiple servers via pipeline
"SQL01","SQL02","SQL03" | Invoke-sqmMonitoringKey -Operation Set -SQL Full -TSM 1

# Read from a remote server with explicit credential
Invoke-sqmMonitoringKey -ComputerName "REMOTEDB" -Credential (Get-Credential)

Registry Value Mapping

Value NameTypeValuesDecoded As
SQLDWORD0 / 1 / 2NoMonitoring / ServiceMonitoring / FullMonitoring
SQLFreeSpaceVersionStringStandard / ClusterStandalone instance / AlwaysOn AG
TSMDWORD0 / 1Inactive / Active