Add new public commands for managing SQL Agent Alerts (#2149)

Author: johlju

.github/instructions/SqlServerDsc-guidelines.instructions.md

@@ -7,6 +7,7 @@ applyTo: "**"
 
 ## Naming
 - Public commands: `{Verb}-SqlDsc{Noun}` format
+- Private function: `{Verb}-{Noun}` format
 
 ## Resources
 - Database Engine resources: inherit `SqlResourceBase`
@@ -24,8 +25,15 @@ applyTo: "**"
 
 ## Test Requirements
 - Unit tests: Add `$env:SqlServerDscCI = $true` in `BeforeAll`, remove in `AfterAll`
-- Integration tests: Use `Disconnect-SqlDscDatabaseEngine` after `Connect-SqlDscDatabaseEngine`
-- Test config: tests/Integration/Commands/README.md and tests/Integration/Resources/README.md
-- Integration test script files must be added to a group
-within the test stage in ./azure-pipelines.yml.
-- Choose the appropriate group number based on the required dependencies
+- Integration tests:
+  - If requiring SQL Server DB, start the Windows service in `BeforeAll`, stop it in `AfterAll`.
+  - Use `Connect-SqlDscDatabaseEngine` for SQL Server DB session, and always with correct CI credentials
+  - Use `Disconnect-SqlDscDatabaseEngine` after `Connect-SqlDscDatabaseEngine`
+  - Test config: tests/Integration/Commands/README.md and tests/Integration/Resources/README.md
+  - Integration test script files must be added to a group within the test stage in ./azure-pipelines.yml.
+    - Choose the appropriate group number based on the required dependencies
+
+## Unit tests
+- When unit test uses SMO types, ensure they are properly stubbed in SMO.cs
+- Load stub types from SMO.cs in unit test files, e.g. `Add-Type -Path "$PSScriptRoot/../Stubs/SMO.cs"`
+- After changing SMO stub types, run tests in a new PowerShell session for changes to take effect.

.github/instructions/dsc-community-style-guidelines-class-resource.instructions.md

@@ -8,60 +8,73 @@ applyTo: "source/[cC]lasses/**/*.ps1"
 **Applies to:** Classes with `[DscResource(...)]` decoration only.
 
 ## Requirements
-- File: `source/Classes/{ResourceName}.ps1`
+- File: `source/Classes/020.{ResourceName}.ps1`
 - Decoration: `[DscResource(RunAsCredential = 'Optional')]` (replace with `'Mandatory'` if required)
 - Inheritance: Must inherit `ResourceBase` (part of module DscResource.Base)
 - `$this.localizedData` hashtable auto-populated by `ResourceBase` from localization file
 
+## Required constructor
+
+```powershell
+MyResourceName () : base ($PSScriptRoot)
+{
+    # Property names where state cannot be enforced, e.g Ensure
+    $this.ExcludeDscProperties = @()
+}
+```
+
 ## Required Method Pattern
 
 ```powershell
 [MyResourceName] Get()
 {
+    # Call base implementation to get current state
     $currentState = ([ResourceBase] $this).Get()
 
-    # If needed, post-processing based on returned current state before returning to user
+    # If needed, post-processing on current state that can not be handled by GetCurrentState()
 
     return $currentState
 }
 
 [System.Boolean] Test()
 {
+    # Call base implementation to test current state
     $inDesiredState = ([ResourceBase] $this).Test()
 
-    # If needed, post-processing based on returned test result before returning to user
+    # If needed, post-processing on test result that can not be handled by base Test()
 
     return $inDesiredState
 }
 
 [void] Set()
 {
+    # Call base implementation to set desired state
     ([ResourceBase] $this).Set()
 
-    # If needed, additional state changes that could not be handled by Modify()
+    # If needed, additional state changes that can not be handled by Modify()
 }
 
 hidden [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties)
 {
-    # Return current state as hashtable
-    # Variable $properties contains the key properties (key-value pairs).
+    # Always return current state as hashtable, $properties contains key properties
 }
 
 hidden [void] Modify([System.Collections.Hashtable] $properties)
 {
-    # Set desired state for non-compliant properties only
-    # Variable $properties contains the properties (key-value pairs) that are not in desired state.
+    # Always set desired state, $properties contain those that must change state
 }
+```
 
+## Optional Method Pattern
+
+```powershell
 hidden [void] AssertProperties([System.Collections.Hashtable] $properties)
 {
-    # Validate user-provided properties
-    # Variable $properties contains properties user assigned values.
+    # Validate user-provided properties, $properties contains user assigned values
 }
 
 hidden [void] NormalizeProperties([System.Collections.Hashtable] $properties)
 {
-    # Normalize user-provided properties
-    # Variable $properties contains properties user assigned values.
+    # Normalize user-provided properties, $properties contains user assigned values
 }
 ```

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

@@ -14,6 +14,7 @@ applyTo: "tests/[iI]ntegration/**/*.[iI]ntegration.[tT]ests.ps1"
 - Avoid `ExpectedMessage` for `Should -Throw` assertions
 - Only run integration tests in CI unless explicitly instructed.
 - Call commands with `-Force` parameter where applicable (avoids prompting).
+- Use `-ErrorAction Stop` on commands so failures surface immediately
 
 ## Required Setup Block
 

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

@@ -14,9 +14,8 @@ applyTo: "source/**/*.ps1"
 - Commands/functions: `source/en-US/SqlServerDsc.strings.psd1`
 - Class resources: `source/en-US/{ResourceClassName}.strings.psd1`
 
-## Key Naming
-- Format: `FunctionName_Description` (underscore separators)
-- Example: `Get_SqlDscDatabase_ConnectingToDatabase`
+## Key Naming Patterns
+- Format: `Verb_FunctionName_Action` (underscore separators), e.g. `Get_SqlDscDatabase_ConnectingToDatabase`
 
 ## String Format
 ```powershell

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

@@ -10,6 +10,7 @@ applyTo: "**/*.md"
 - Use '1.' for all items in ordered lists (1/1/1 numbering style)
 - Disable `MD013` rule by adding a comment for tables/code blocks exceeding 80 characters
 - Empty lines required before/after code blocks and headings (except before line 1)
+- Escape backslashes in file paths only (not in code blocks)
 - Code blocks must specify language identifiers
 
 ## Text Formatting

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

@@ -12,7 +12,7 @@ applyTo: "**/*.[Tt]ests.ps1"
 - One `Describe` block per file matching the tested entity name
 - Test code only inside `Describe` blocks
 - Assertions only in `It` blocks
-- Never test `Write-Verbose`, `Write-Debug`, or parameter binding behavior
+- Never test verbose messages, debug messages or parameter binding behavior
 - Pass all mandatory parameters to avoid prompts
 
 ## Structure & Scope
@@ -25,11 +25,15 @@ applyTo: "**/*.[Tt]ests.ps1"
 
 ## Syntax Rules
 - PascalCase: `Describe`, `Context`, `It`, `Should`, `BeforeAll`, `BeforeEach`, `AfterAll`, `AfterEach`
-- `It` descriptions start with 'Should'
 - `Context` descriptions start with 'When'
+- `It` descriptions start with 'Should', must not contain 'when'
 - Mock variables prefix: 'mock'
 - Prefer `-BeTrue`/`-BeFalse` over `-Be $true`/`-Be $false`
 - No `Should -Not -Throw` - invoke commands directly
+- Never add an empty `-MockWith` block
+- Omit `-MockWith` when returning `$null`
+- Set `$PSDefaultParameterValues` for `Mock:ModuleName`, `Should:ModuleName`, `InModuleScope:ModuleName`
+- Omit `-ModuleName` parameter on Pester commands
 
 ## File Organization
 - Class resources: `tests/Unit/Classes/{Name}.Tests.ps1`
@@ -42,7 +46,7 @@ applyTo: "**/*.[Tt]ests.ps1"
 - Keep scope close to usage context
 
 ## Best Practices
-- Assign unused return objects to `$null`
+- Inside `It` blocks, assign unused return objects to `$null` (unless part of pipeline)
 - Tested entity must be called from within the `It` blocks
 - Keep results and assertions in same `It` block
 - Cover all scenarios and code paths

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

@@ -15,6 +15,10 @@ applyTo: "**/*.ps?(m|d)1"
 - Classes: PascalCase
 - Include scope for script/global/environment variables: `$script:`, `$global:`, `$env:`
 
+## File naming
+
+- Class files: `###.ClassName.ps1` format (e.g. `001.SqlReason.ps1`, `004.StartupParameters.ps1`)
+
 ## Formatting
 
 ### Indentation & Spacing
@@ -71,8 +75,10 @@ applyTo: "**/*.ps?(m|d)1"
 - Avoid `Write-Output` (use `return` instead)
 - Avoid `ConvertTo-SecureString -AsPlainText` in production code
 - Don't redefine reserved parameters (Verbose, Debug, etc.)
-- Include a `Force` parameter for functions that support `$PSCmdlet.ShouldContinue` or that use `$PSCmdlet.ShouldProcess`
+- 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
+  - `$PSCmdlet.ShouldProcess` must use required pattern
 - Use `$PSCmdlet.ThrowTerminatingError()` for terminating errors, use relevant error category
 - Use `Write-Error` for non-terminating errors, use relevant error category
 - Use `Write-Warning` for warnings
@@ -81,6 +87,32 @@ applyTo: "**/*.ps?(m|d)1"
 - Use `Write-Information` for informational messages.
 - Never use backtick as line continuation in production code.
 
+## ShouldProcess Required Pattern
+
+- Ensure `$descriptionMessage` explains what will happen
+- Ensure `$confirmationMessage` succinctly asks for confirmation
+- Keep `$captionMessage` short and descriptive (no trailing `.`)
+
+```powershell
+$descriptionMessage = $script:localizedData.FunctionName_Action_ShouldProcessDescription -f $param1, $param2
+$confirmationMessage = $script:localizedData.FunctionName_Action_ShouldProcessConfirmation -f $param1
+$captionMessage = $script:localizedData.FunctionName_Action_ShouldProcessCaption
+
+if ($PSCmdlet.ShouldProcess($descriptionMessage, $confirmationMessage, $captionMessage))
+{
+    # state changing code
+}
+```
+
+## Force Parameter Pattern
+
+```powershell
+if ($Force.IsPresent -and -not $Confirm)
+{
+    $ConfirmPreference = 'None'
+}
+```
+
 ### Structure
 
 ```powershell
@@ -107,7 +139,7 @@ applyTo: "**/*.ps?(m|d)1"
 function Get-Something
 {
     [CmdletBinding()]
-    [OutputType([String])]
+    [OutputType([System.String])]
     param
     (
         [Parameter(Mandatory = $true)]
@@ -128,7 +160,7 @@ function Get-Something
 - Include `[CmdletBinding()]` on every function
 - Parameter block at top
 - Parameter block: `param ()` if empty, else opening/closing parentheses on own lines
-- `[OutputType()]` for functions with output
+- `[OutputType({return type})]` for functions with output, no output use `[OutputType()]`
 - All parameters use `[Parameter()]` attribute, mandatory parameters use `[Parameter(Mandatory = $true)]`
 - Parameter attributes on separate lines
 - Parameter type on line above parameter name

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

@@ -25,7 +25,7 @@ applyTo: "**"
 ## Requirements
 - Follow guidelines over existing code patterns
 - Always update CHANGELOG.md Unreleased section
-- Localize all strings using string keys
+- Localize all strings using string keys; remove any orphaned string keys
 - Check DscResource.Common before creating private functions
 - Separate reusable logic into private functions
 - Add unit tests for all commands/functions/resources

.vscode/settings.json

@@ -110,7 +110,7 @@
         "/@prkelly/g",
         "/@glennsarti/g",
         "/tempdb/g",
-        "/sqlcmd\\.exe/g"
+        "/\\b[A-Za-z]{2,}\\d{4}\\b/g"
     ],
     "[markdown]": {
         "files.trimTrailingWhitespace": true,

CHANGELOG.md

@@ -34,7 +34,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     Throws a terminating error if the specified principal does not exist as a login.
   - Supports pipeline input and provides detailed error messages with localization.
   - Uses `Test-SqlDscIsLogin` command for login validation following module patterns.
-- Added `Get-SqlDscLogin`, `Get-SqlDscRole`, `New-SqlDscLogin`, `New-SqlDscRole`, `Remove-SqlDscRole`, and `Remove-SqlDscLogin` commands for retrieving and managing SQL Server logins and roles with support for refresh, pipeline input, and ShouldProcess.
+- Added `Get-SqlDscLogin`, `Get-SqlDscRole`, `New-SqlDscLogin`, `New-SqlDscRole`,
+  `Remove-SqlDscRole`, and `Remove-SqlDscLogin` commands for retrieving and managing
+   SQL Server logins and roles with support for refresh, pipeline input, and ShouldProcess.
+- Added `Get-SqlDscAgentAlert`, `New-SqlDscAgentAlert`,
+  `Set-SqlDscAgentAlert`, `Remove-SqlDscAgentAlert`, and `Test-SqlDscAgentAlert`
+  to manage SQL Agent alerts on a Database Engine instance.
 
 ### Changed
 
@@ -77,7 +82,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - DSC community style guidelines
   - Added requirement to follow guidelines over existing code patterns.
 - Improved markdown, pester, powershell, and changelog instructions.
-  - Fixed `Ingore` that seems in edge-cases fail.
+  - Fixed `Ignore` that seems in edge-cases fail.
+  - Improved markdown and changelog instructions.
 
 ## [17.1.0] - 2025-05-22