SqlAgentAlert: Refactor to class-bases resource (#2150)

Author: johlju

.github/copilot-instructions.md

@@ -1,7 +1,12 @@
-# AI Instructions for SqlServerDsc
+# AI Instructions
 
-This file provides AI agent guidance for the SqlServerDsc project. Each
-instruction file below targets specific file glob patterns and use cases.
+This file provides AI agent guidance for the project. Each instruction file below
+targets specific file glob patterns and use cases.
+
+## Build & Test Workflow
+- Run in PowerShell, from repository root
+- Build before running tests: `.\build.ps1 -Tasks build`
+- Always run tests in new PowerShell session: `Invoke-Pester -Path @({test paths}) -Output Detailed`
 
 ## Instructions Overview
 

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

@@ -11,7 +11,9 @@ applyTo: "**"
 
 ## Resources
 - Database Engine resources: inherit `SqlResourceBase`
-- `SqlResourceBase` provides: `InstanceName`, `ServerName`, `Credential`, `Reasons`, `GetServerObject()`
+  - Add `InstanceName`, `ServerName`, and `Credential` to `$this.ExcludeDscProperties`
+  - `SqlResourceBase` provides: `InstanceName`, `ServerName`, `Credential`, `Reasons`, `GetServerObject()`
+  - Constructor: `MyResourceName() : base () { }` (no $PSScriptRoot parameter)
 
 ## SQL Server Interaction
 - Always prefer SMO over T-SQL
@@ -34,6 +36,7 @@ applyTo: "**"
     - 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.
+- When unit test tests classes or commands that contain SMO types, e.g. `[Microsoft.SqlServer.Management.Smo.*]`
+  - Ensure they are properly stubbed in SMO.cs
+  - Load SMO 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-changelog.instructions.md

@@ -8,6 +8,6 @@ applyTo: "CHANGELOG.md"
 - Always update the Unreleased section in CHANGELOG.md
 - Use Keep a Changelog format
 - Describe notable changes briefly, ≤2 items per change type
-- Reference issues using format [#<issue_number>](https://github.com/<owner>/<repo>/issues/<issue_number>)
+- Reference issues using format [issue #<issue_number>](https://github.com/<owner>/<repo>/issues/<issue_number>)
 - No empty lines between list items in same section
 - Do not add item if there are already an existing item for the same change

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

@@ -12,13 +12,14 @@ applyTo: "source/[cC]lasses/**/*.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
+- value-type properties: Use `[Nullable[{FullTypeName}]]` (e.g., `[Nullable[System.Int32]]`)
 
 ## Required constructor
 
 ```powershell
 MyResourceName () : base ($PSScriptRoot)
 {
-    # Property names where state cannot be enforced, e.g Ensure
+    # Property names where state cannot be enforced, e.g. IsSingleInstance, Force
     $this.ExcludeDscProperties = @()
 }
 ```
@@ -78,3 +79,19 @@ hidden [void] NormalizeProperties([System.Collections.Hashtable] $properties)
     # Normalize user-provided properties, $properties contains user assigned values
 }
 ```
+
+## Required comment-based help
+
+Add to .DESCRIPTION section:
+- `## Requirements`: List minimum requirements
+- `## Known issues`: Critical issues + pattern: `All issues are not listed here, see [all open issues](https://github.com/{owner}/{repo}/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+{ResourceName}).`
+
+## Error Handling
+- Use `try/catch` blocks to handle exceptions
+- Do not use `throw` for terminating errors, use `New-*Exception` commands:
+  - [`New‑InvalidDataException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91InvalidDataException)
+  - [`New-ArgumentException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91ArgumentException)
+  - [`New-InvalidOperationException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91InvalidOperationException)
+  - [`New-ObjectNotFoundException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91ObjectNotFoundException)
+  - [`New-InvalidResultException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91InvalidResultException)
+  - [`New-NotImplementedException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91NotImplementedException)

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

@@ -45,8 +45,8 @@ BeforeDiscovery {
 }
 
 BeforeAll {
-    $script:dscModuleName = 'SqlServerDsc'
+    $script:moduleName = '{MyModuleName}'
 
-    Import-Module -Name $script:dscModuleName -Force -ErrorAction 'Stop'
+    Import-Module -Name $script:moduleName -Force -ErrorAction 'Stop'
 }
 ```

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

@@ -11,11 +11,11 @@ applyTo: "source/**/*.ps1"
 - Assume `$script:localizedData` is available
 
 ## String Files
-- Commands/functions: `source/en-US/SqlServerDsc.strings.psd1`
+- Commands/functions: `source/en-US/{MyModuleName}.strings.psd1`
 - Class resources: `source/en-US/{ResourceClassName}.strings.psd1`
 
 ## Key Naming Patterns
-- Format: `Verb_FunctionName_Action` (underscore separators), e.g. `Get_SqlDscDatabase_ConnectingToDatabase`
+- Format: `Verb_FunctionName_Action` (underscore separators), e.g. `Get_Database_ConnectingToDatabase`
 
 ## String Format
 ```powershell

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

@@ -9,31 +9,36 @@ applyTo: "**/*.[Tt]ests.ps1"
 - All public commands, private functions and classes must have unit tests
 - All public commands and class-based resources must have integration tests
 - Use Pester v5 syntax only
-- One `Describe` block per file matching the tested entity name
 - Test code only inside `Describe` blocks
 - Assertions only in `It` blocks
 - Never test verbose messages, debug messages or parameter binding behavior
 - Pass all mandatory parameters to avoid prompts
 
+## Naming
+- One `Describe` block per file matching the tested entity name
+- `Context` descriptions start with 'When'
+- `It` descriptions start with 'Should', must not contain 'when'
+- Mock variables prefix: 'mock'
+
 ## Structure & Scope
 - Public commands: Never use `InModuleScope` (unless retrieving localized strings)
 - Private functions/class resources: Always use `InModuleScope`
+- Each class method = separate `Context` block
 - Each scenario = separate `Context` block
 - Use nested `Context` blocks for complex scenarios
 - Mocking in `BeforeAll` (`BeforeEach` only when required)
 - Setup/teardown in `BeforeAll`,`BeforeEach`/`AfterAll`,`AfterEach` close to usage
 
 ## Syntax Rules
 - PascalCase: `Describe`, `Context`, `It`, `Should`, `BeforeAll`, `BeforeEach`, `AfterAll`, `AfterEach`
-- `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`
+- Never use `Assert-MockCalled`, use `Should -Invoke` instead
 - 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
+- Never use `Mock` inside `InModuleScope`-block
 
 ## File Organization
 - Class resources: `tests/Unit/Classes/{Name}.Tests.ps1`

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

@@ -49,7 +49,7 @@ applyTo: "**/*.ps?(m|d)1"
 ### Hashtables
 
 - Empty: `@{}`
-- Multi-line: each property on separate line with proper indentation
+- Each property on separate line with proper indentation
 - Properties: Use PascalCase
 
 ### Comments
@@ -79,14 +79,18 @@ applyTo: "**/*.ps?(m|d)1"
 - 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
-- Use `Write-Debug` for debugging information
-- Use `Write-Verbose` for actionable information
-- Use `Write-Information` for informational messages.
 - Never use backtick as line continuation in production code.
 
+## Output streams
+
+- Never output sensitive data/secrets
+- Use `Write-Debug` for: Internal diagnostics; Variable values/traces; Developer-focused details
+- 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
+- Use `Write-Error` for non-terminating errors, use relevant error category
+
 ## ShouldProcess Required Pattern
 
 - Ensure `$descriptionMessage` explains what will happen

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

@@ -42,13 +42,13 @@ BeforeDiscovery {
 }
 
 BeforeAll {
-    $script:dscModuleName = 'SqlServerDsc'
+    $script:moduleName = '{MyModuleName}'
 
-    Import-Module -Name $script:dscModuleName -Force -ErrorAction 'Stop'
+    Import-Module -Name $script:moduleName -Force -ErrorAction 'Stop'
 
-    $PSDefaultParameterValues['InModuleScope:ModuleName'] = $script:dscModuleName
-    $PSDefaultParameterValues['Mock:ModuleName'] = $script:dscModuleName
-    $PSDefaultParameterValues['Should:ModuleName'] = $script:dscModuleName
+    $PSDefaultParameterValues['InModuleScope:ModuleName'] = $script:moduleName
+    $PSDefaultParameterValues['Mock:ModuleName'] = $script:moduleName
+    $PSDefaultParameterValues['Should:ModuleName'] = $script:moduleName
 }
 
 AfterAll {
@@ -57,7 +57,7 @@ AfterAll {
     $PSDefaultParameterValues.Remove('Should:ModuleName')
 
     # Unload the module being tested so that it doesn't impact any other tests.
-    Get-Module -Name $script:dscModuleName -All | Remove-Module -Force
+    Get-Module -Name $script:moduleName -All | Remove-Module -Force
 }
 ```
 

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

@@ -11,10 +11,9 @@ applyTo: "**"
 - **Resource**: DSC class-based resource
 
 ## Build & Test Workflow
-- Run project scripts in PowerShell from repository root
-- Build after source changes: `.\build.ps1 -Tasks build`
-- Test workflow: Build → `Invoke-Pester -Path @('<test paths>') -Output Detailed`
-- New session required after class changes
+- Run in PowerShell, from repository root
+- Build before running tests: `.\build.ps1 -Tasks build`
+- Always run tests in new PowerShell session: `Invoke-Pester -Path @({test paths}) -Output Detailed`
 
 ## File Organization
 - Public commands: `source/Public/{CommandName}.ps1`