Add SQL Agent Operator management commands (#2154)

Author: Copilot

.github/instructions/dsc-community-style-guidelines-pester.instructions.md

@@ -38,7 +38,7 @@ applyTo: "**/*.[Tt]ests.ps1"
 
 ## Syntax Rules
 - PascalCase: `Describe`, `Context`, `It`, `Should`, `BeforeAll`, `BeforeEach`, `AfterAll`, `AfterEach`
-- Prefer `-BeTrue`/`-BeFalse` over `-Be $true`/`-Be $false`
+- Use `-BeTrue`/`-BeFalse` never `-Be $true`/`-Be $false`
 - Never use `Assert-MockCalled`, use `Should -Invoke` instead
 - No `Should -Not -Throw` - invoke commands directly
 - Never add an empty `-MockWith` block

.github/instructions/dsc-community-style-guidelines-powershell.instructions.md

@@ -78,10 +78,11 @@ applyTo: "**/*.ps?(m|d)1"
 - Include a `Force` parameter for functions that uses `$PSCmdlet.ShouldContinue` or `$PSCmdlet.ShouldProcess`
 - For state-changing functions, use `SupportsShouldProcess`
   - Place ShouldProcess check immediately before each state-change
+  - Set `ConfirmImpact` to 'Low', 'Medium', or 'High' depending on risk
   - `$PSCmdlet.ShouldProcess` must use required pattern
   - Inside `$PSCmdlet.ShouldProcess`-block, avoid using `Write-Verbose`
 - Never use backtick as line continuation in production code.
-- Set `$ErrorActionPreference = 'Stop'` before commands using `-ErrorAction 'Stop'`; restore after
+- Set `$ErrorActionPreference = 'Stop'` before commands using `-ErrorAction 'Stop'`; restore previous value after
 
 ## Output streams
 
@@ -90,8 +91,8 @@ applyTo: "**/*.ps?(m|d)1"
 - Use `Write-Verbose` for: High-level execution flow only; User-actionable information
 - Use `Write-Information` for: User-facing status updates; Important operational messages; Non-error state changes
 - Use `Write-Warning` for: Non-fatal issues requiring attention; Deprecated functionality usage; Configuration problems that don't block execution
-- Use `$PSCmdlet.ThrowTerminatingError()` for terminating errors (except for classes), use relevant error category, in try-catch include exception
-- Use `Write-Error` for non-terminating errors, use relevant error category
+- Use `$PSCmdlet.ThrowTerminatingError()` for terminating errors (except for classes), use relevant error category, in try-catch include exception with localized message
+- Use `Write-Error` for non-terminating errors, use relevant error category; always use `return` after `Write-Error` to avoid further processing
 
 ## ShouldProcess Required Pattern
 
@@ -184,6 +185,7 @@ function Get-Something
 - Assign function results to variables rather than inline calls
 - Return a single, consistent object type per function
   - return `$null` for no objects/non-terminating errors
+- Use `::new()` static method instead of `New-Object` for .NET types, e.g `[System.Management.Automation.ErrorRecord]::new()`
 
 ### Security & Safety
 
@@ -207,6 +209,7 @@ function Get-Something
 - End files with only one blank line
 - Use CR+LF line endings
 - Maximum two consecutive newlines
+- No line shall have trailing whitespace
 
 ## File Encoding
 

.github/instructions/dsc-community-style-guidelines-unit-tests.instructions.md

@@ -15,7 +15,6 @@ applyTo: "tests/[u]Unit/**/*.[Tt]ests.ps1"
 Use this exact setup block before `Describe`:
 
 ```powershell
-[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')]
 [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Suppressing this rule because Script Analyzer does not understand Pester syntax.')]
 param ()
 

.gitignore

@@ -2,3 +2,4 @@
 .vs
 output/
 coverage.xml
+testResults.xml

CHANGELOG.md

@@ -38,6 +38,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Set-SqlDscDatabaseDefault`
   - Added new command to set default objects of a database in a SQL Server
     Database Engine instance (issue [#2178](https://github.com/dsccommunity/SqlServerDsc/issues/2178)).
+- `Set-SqlDscConfigurationOption`
+  - Added new command to set SQL Server Database Engine configuration options
+    using SMO with validation, ShouldProcess support, and dynamic tab completion.
+- `Test-SqlDscConfigurationOption`
+  - Added new command to test if SQL Server Database Engine configuration options
+    have the specified value using SMO with dynamic tab completion for both
+    option names and values.
+- `Get-SqlDscConfigurationOption`
+  - Enhanced existing command to return user-friendly metadata objects by default
+    with properties Name, RunValue, ConfigValue, Minimum, Maximum, and IsDynamic.
+  - Added `-Raw` switch to return original SMO ConfigProperty objects for
+    backward compatibility.
+  - Added dynamic tab completion for the `-Name` parameter.
   - The command can set the default filegroup, default FILESTREAM filegroup,
     and default Full-Text catalog using SMO methods SetDefaultFileGroup,
     SetDefaultFileStreamFileGroup, and SetDefaultFullTextCatalog.
@@ -81,6 +94,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `Get-SqlDscAgentAlert`, `New-SqlDscAgentAlert`,
   `Set-SqlDscAgentAlert`, `Remove-SqlDscAgentAlert`, and `Test-SqlDscAgentAlert`
   to manage SQL Agent alerts on a Database Engine instance.
+- Added new public commands for SQL Agent Operator management:
+  - `Get-SqlDscAgentOperator` - Get SQL Agent Operators from a SQL Server
+     Database Engine instance
+  - `New-SqlDscAgentOperator` - Create a new SQL Agent Operator with specified properties
+  - `Set-SqlDscAgentOperator` - Update existing SQL Agent Operator properties
+  - `Remove-SqlDscAgentOperator` - Remove a SQL Agent Operator from the instance
+  - `Enable-SqlDscAgentOperator` - Enable a SQL Agent Operator
+  - `Disable-SqlDscAgentOperator` - Disable a SQL Agent Operator
+  - `Test-SqlDscIsAgentOperator` - Test if a SQL Agent Operator exists
+  - Supports pipeline input for both ServerObject and OperatorObject where applicable
+  - Includes comprehensive unit tests and follows ShouldProcess patterns
 - Added new public commands for database management:
   - `Get-SqlDscDatabase` - Get databases from a SQL Server Database Engine instance
   - `New-SqlDscDatabase` - Create a new database with specified properties
@@ -91,9 +115,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     patterns
   - Database objects can also be used as pipeline input for Set and Remove operations
   - Commands include comprehensive validation, localization, and ShouldProcess support
+- Added private function `Get-CommandParameter` to filter command parameters
+  by excluding specified parameter names and common parameters, providing a
+  reusable way to determine settable properties on objects.
 
 ### Changed
 
+- Improved code quality by ensuring all function invocations in the private
+  and public functions use named parameters instead of positional parameters.
 - SqlServerDsc
   - Updated GitVersion.yml feature branch regex pattern to use anchor `^f(eature(s)?)?[\/-]`
     for more precise branch name matching.

azure-pipelines.yml

@@ -293,6 +293,9 @@ stages:
                   'tests/Integration/Commands/Assert-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/New-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscLogin.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscConfigurationOption.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Set-SqlDscConfigurationOption.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Test-SqlDscConfigurationOption.Integration.Tests.ps1'
                   'tests/Integration/Commands/Disable-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/Enable-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscIsLoginEnabled.Integration.Tests.ps1'
@@ -311,8 +314,16 @@ stages:
                   'tests/Integration/Commands/New-SqlDscAgentAlert.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscAgentAlert.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscAgentAlert.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscAgentOperator.Integration.Tests.ps1'
+                  'tests/Integration/Commands/New-SqlDscAgentOperator.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Set-SqlDscAgentOperator.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Test-SqlDscIsAgentOperator.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Assert-SqlDscAgentOperator.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Enable-SqlDscAgentOperator.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Disable-SqlDscAgentOperator.Integration.Tests.ps1'
                   # Group 8
                   'tests/Integration/Commands/Remove-SqlDscAgentAlert.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Remove-SqlDscAgentOperator.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscRole.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscLogin.Integration.Tests.ps1'

source/Classes/020.SqlRSSetup.ps1

@@ -608,7 +608,7 @@ class SqlRSSetup : ResourceBase
             'InstallFolder'
             'LogPath'
         ) |
-            Where-Object {
+            Where-Object -FilterScript {
                 $properties.ContainsKey($_)
             }
 

source/Examples/Resources/SqlDatabaseMail/1-EnableDatabaseMail.ps1

@@ -47,4 +47,3 @@ Configuration Example
         }
     }
 }
-

source/Private/ConvertTo-FormattedParameterDescription.ps1

@@ -0,0 +1,82 @@
+<#
+    .SYNOPSIS
+        Converts a hashtable of bound parameters into a formatted string for ShouldProcess descriptions.
+
+    .DESCRIPTION
+        This function takes a hashtable of bound parameters and formats them into a readable string
+        for use in ShouldProcess verbose descriptions. It excludes non-settable parameters and
+        formats each parameter as 'ParameterName: Value'.
+
+    .PARAMETER BoundParameters
+        Hashtable of bound parameters (typically $PSBoundParameters).
+
+    .PARAMETER Exclude
+        Array of parameter names to exclude from the formatted output.
+
+    .OUTPUTS
+        System.String
+
+        Returns a formatted string with parameters and their values.
+
+    .EXAMPLE
+        $formattedText = ConvertTo-FormattedParameterDescription -BoundParameters $PSBoundParameters -Exclude @('ServerObject', 'Name', 'Force')
+
+        Returns a formatted string like:
+        "
+            EmailAddress: 'admin@company.com'
+            CategoryName: 'Notifications'
+        "
+#>
+function ConvertTo-FormattedParameterDescription
+{
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.Collections.Hashtable]
+        $BoundParameters,
+
+        [Parameter()]
+        [System.String[]]
+        $Exclude = @()
+    )
+
+    $parameterDescriptions = @()
+
+    foreach ($parameter in ($BoundParameters.Keys | Sort-Object))
+    {
+        if ($parameter -notin $Exclude)
+        {
+            $raw = $BoundParameters[$parameter]
+
+            $value = if ($raw -is [System.Security.SecureString])
+            {
+                '***'
+            }
+            elseif ($raw -is [System.Management.Automation.PSCredential])
+            {
+                $raw.UserName
+            }
+            elseif ($raw -is [System.Array])
+            {
+                ($raw -join ', ')
+            }
+            else
+            {
+                $raw
+            }
+
+            $parameterDescriptions += "$parameter`: '$value'"
+        }
+    }
+
+    if ($parameterDescriptions.Count -gt 0)
+    {
+        return "`r`n    " + ($parameterDescriptions -join "`r`n    ")
+    }
+    else
+    {
+        return " $($script:localizedData.ConvertTo_FormattedParameterDescription_NoParametersToUpdate)"
+    }
+}

source/Private/Get-AgentOperatorObject.ps1

@@ -0,0 +1,77 @@
+<#
+    .SYNOPSIS
+        Retrieves a SQL Server Agent Operator object.
+
+    .DESCRIPTION
+        This private function retrieves a SQL Server Agent Operator object using the provided
+        parameters. If the operator is not found, it throws a non-terminating error. Callers
+        can use -ErrorAction to control error behavior.
+
+    .PARAMETER ServerObject
+        Specifies the server object on which to retrieve the operator.
+
+    .PARAMETER Name
+        Specifies the name of the operator to retrieve.
+
+    .PARAMETER Refresh
+        Specifies whether to refresh the operators collection before retrieving the operator.
+        When specified, the function calls Refresh() on the JobServer.Operators collection.
+
+    .INPUTS
+        None.
+
+    .OUTPUTS
+        Microsoft.SqlServer.Management.Smo.Agent.Operator
+
+        Returns the operator object if found.
+
+    .EXAMPLE
+        $operatorObject = Get-AgentOperatorObject -ServerObject $serverObject -Name 'TestOperator'
+
+        Returns the SQL Agent Operator object for 'TestOperator', throws error if not found.
+
+    .EXAMPLE
+        $operatorObject = Get-AgentOperatorObject -ServerObject $serverObject -Name 'TestOperator' -Refresh
+
+        Returns the SQL Agent Operator object for 'TestOperator' after refreshing the operators collection.
+#>
+function Get-AgentOperatorObject
+{
+    [CmdletBinding()]
+    [OutputType([Microsoft.SqlServer.Management.Smo.Agent.Operator])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $Refresh
+    )
+
+    Write-Verbose -Message ($script:localizedData.Get_AgentOperatorObject_GettingOperator -f $Name)
+
+    if ($Refresh)
+    {
+        Write-Verbose -Message $script:localizedData.Get_AgentOperatorObject_RefreshingOperators
+        $ServerObject.JobServer.Operators.Refresh()
+    }
+
+    $operatorObject = $ServerObject.JobServer.Operators[$Name]
+
+    if ($null -eq $operatorObject)
+    {
+        $errorMessage = $script:localizedData.AgentOperator_NotFound -f $Name
+
+        Write-Error -Message $errorMessage -Category 'ObjectNotFound' -ErrorId 'GAOO0001' -TargetObject $Name
+
+        return $null
+    }
+
+    return $operatorObject
+}