Add New-SqlDscDatabaseSnapshot command for SMO-based snapshot creation

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

@@ -28,7 +28,7 @@ applyTo: "**/*.[Tt]ests.ps1"
 - Mock variables prefix: 'mock'
 
 ## Structure & Scope
-- Public commands: Never use `InModuleScope` (unless retrieving localized strings)
+- Public commands: Never use `InModuleScope` (unless retrieving localized strings or creating an object using an internal class)
 - Private functions/class resources: Always use `InModuleScope`
 - Each class method = separate `Context` block
 - Each scenario = separate `Context` block
@@ -46,6 +46,7 @@ applyTo: "**/*.[Tt]ests.ps1"
 - Set `$PSDefaultParameterValues` for `Mock:ModuleName`, `Should:ModuleName`, `InModuleScope:ModuleName`
 - Omit `-ModuleName` parameter on Pester commands
 - Never use `Mock` inside `InModuleScope`-block
+- Never use `param()` inside `-MockWith` scriptblocks, parameters are auto-bound
 
 ## File Organization
 - Class resources: `tests/Unit/Classes/{Name}.Tests.ps1`

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

@@ -19,6 +19,8 @@ applyTo: "**"
 ## File Organization
 - Public commands: `source/Public/{CommandName}.ps1`
 - Private functions: `source/Private/{FunctionName}.ps1`
+- Classes: `source/Classes/{DependencyGroupNumber}.{ClassName}.ps1`
+- Enums: `source/Enum/{DependencyGroupNumber}.{EnumName}.ps1`
 - Unit tests: `tests/Unit/{Classes|Public|Private}/{Name}.Tests.ps1`
 - Integration tests: `tests/Integration/Commands/{CommandName}.Integration.Tests.ps1`
 

.vscode/settings.json

@@ -173,5 +173,26 @@
             "path": "bash",
             "args": []
         }
+    },
+    "chat.tools.terminal.terminalProfile.osx": {
+        "path": "pwsh",
+        "args": [],
+        "env": {
+            "COPILOT": "1"
+        }
+    },
+    "chat.tools.terminal.terminalProfile.linux": {
+        "path": "pwsh",
+        "args": [],
+        "env": {
+            "COPILOT": "1"
+        }
+    },
+    "chat.tools.terminal.terminalProfile.windows": {
+        "path": "pwsh.exe",
+        "args": [],
+        "env": {
+            "COPILOT": "1"
+        }
     }
 }

CHANGELOG.md

@@ -25,6 +25,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added public command `New-SqlDscDatabaseSnapshot` to create database snapshots
+  in a SQL Server Database Engine instance using SMO. This command provides an
+  automated and DSC-friendly approach to snapshot management by leveraging
+  `New-SqlDscDatabase` for the actual creation. The command now supports `FileGroup`
+  and `DataFile` parameters to allow control over snapshot file placement and
+  structure ([issue #2341](https://github.com/dsccommunity/SqlServerDsc/issues/2341)).
+- Added public command `New-SqlDscFileGroup` to create FileGroup objects for SQL
+  Server databases. This command simplifies creating FileGroup objects that can be
+  used with `New-SqlDscDatabase` and other database-related commands. The `Database`
+  parameter is optional, allowing FileGroup objects to be created standalone and
+  added to a Database later using `Add-SqlDscFileGroup`.
+- Added public command `New-SqlDscDataFile` to create DataFile objects for SQL
+  Server FileGroups. This command simplifies creating DataFile objects with
+  specified physical file paths, supporting both regular database files (.mdf, .ndf)
+  and sparse files for database snapshots (.ss). The `FileGroup` parameter is
+  mandatory, requiring DataFile objects to be created with an associated FileGroup.
+- Added public command `Add-SqlDscFileGroup` to add one or more FileGroup objects
+  to a Database. This command provides a clean way to associate FileGroup objects
+  with a Database after they have been created.
+- Added public command `ConvertTo-SqlDscDataFile` to convert `DatabaseFileSpec`
+  objects to SMO DataFile objects.
+- Added public command `ConvertTo-SqlDscFileGroup` to convert `DatabaseFileGroupSpec`
+  objects to SMO FileGroup objects.
+- Added class `DatabaseFileSpec` to define data file specifications without requiring
+  a database or SMO context.
+- Added class `DatabaseFileGroupSpec` to define file group specifications with
+  associated data files without requiring a database or SMO context.
+- `New-SqlDscDatabase`
+  - Added `FileGroup` and `DataFile` parameters to allow specifying custom file
+    locations and structure. These parameters apply to both regular databases and
+    database snapshots, enabling control over file placement for snapshots (sparse
+    files) and custom filegroup/datafile configuration for regular databases
+    ([issue #2341](https://github.com/dsccommunity/SqlServerDsc/issues/2341)).
 - Added public command `Set-SqlDscDatabaseOwner` to change the owner of a SQL Server
   database [issue #2177](https://github.com/dsccommunity/SqlServerDsc/issues/2177).
   This command uses the SMO `SetOwner()` method and supports both `ServerObject`

azure-pipelines.yml

@@ -293,6 +293,11 @@ stages:
                   # Group 2
                   'tests/Integration/Commands/PostInstallationConfiguration.Integration.Tests.ps1'
                   # Group 3
+                  'tests/Integration/Commands/New-SqlDscFileGroup.Integration.Tests.ps1'
+                  'tests/Integration/Commands/New-SqlDscDataFile.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Add-SqlDscFileGroup.Integration.Tests.ps1'
+                  'tests/Integration/Commands/ConvertTo-SqlDscFileGroup.Integration.Tests.ps1'
+                  'tests/Integration/Commands/ConvertTo-SqlDscDataFile.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscSetupLog.Integration.Tests.ps1'
                   'tests/Integration/Commands/Connect-SqlDscDatabaseEngine.Integration.Tests.ps1'
                   'tests/Integration/Commands/Disconnect-SqlDscDatabaseEngine.Integration.Tests.ps1'
@@ -335,6 +340,7 @@ stages:
                   'tests/Integration/Commands/Get-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/ConvertFrom-SqlDscDatabasePermission.Integration.Tests.ps1'
                   'tests/Integration/Commands/New-SqlDscDatabase.Integration.Tests.ps1'
+                  'tests/Integration/Commands/New-SqlDscDatabaseSnapshot.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscCompatibilityLevel.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscDatabaseProperty.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscDatabaseOwner.Integration.Tests.ps1'

source/Classes/002.DatabaseFileSpec.ps1

@@ -0,0 +1,97 @@
+<#
+    .SYNOPSIS
+        Defines a data file specification for a database file group.
+
+    .DESCRIPTION
+        This class represents a data file specification that can be used when
+        creating a new database. It contains the properties needed to define
+        a data file without requiring an existing database or file group SMO object.
+
+    .PARAMETER Name
+        The logical name of the data file.
+
+    .PARAMETER FileName
+        The physical file path for the data file. This must be a valid path
+        on the SQL Server instance.
+
+    .PARAMETER Size
+        The initial size of the data file in kilobytes. If not specified,
+        SQL Server will use its default initial size.
+
+    .PARAMETER MaxSize
+        The maximum size to which the data file can grow in kilobytes.
+        If not specified, the file can grow without limit (or up to disk space).
+
+    .PARAMETER Growth
+        The amount by which the data file grows when it needs more space.
+        The value is in kilobytes if GrowthType is KB, or a percentage if
+        GrowthType is Percent. If not specified, SQL Server will use its
+        default growth setting.
+
+    .PARAMETER GrowthType
+        Specifies whether the Growth value is in kilobytes (KB) or percent (Percent).
+        If not specified, defaults to KB.
+
+    .PARAMETER IsPrimaryFile
+        Specifies that this file is the primary file in the PRIMARY file group.
+        Only one file in the PRIMARY file group should be marked as the primary file.
+        This property is typically used for the first file in the PRIMARY file group.
+
+    .NOTES
+        This class is used to specify data file configurations when creating a new
+        database via New-SqlDscDatabase. Unlike SMO DataFile objects, these
+        specification objects can be created without an existing database context.
+
+    .EXAMPLE
+        $fileSpec = [DatabaseFileSpec]::new()
+        $fileSpec.Name = 'MyDatabase_Data'
+        $fileSpec.FileName = 'C:\SQLData\MyDatabase.mdf'
+        $fileSpec.Size = 102400  # 100 MB in KB
+        $fileSpec.Growth = 10240  # 10 MB in KB
+        $fileSpec.GrowthType = 'KB'
+
+        Creates a new data file specification with a specific size and growth settings.
+
+    .EXAMPLE
+        [DatabaseFileSpec] @{
+            Name = 'MyDatabase_Data'
+            FileName = 'C:\SQLData\MyDatabase.mdf'
+            IsPrimaryFile = $true
+        }
+
+        Creates a new primary data file specification using hashtable syntax.
+#>
+class DatabaseFileSpec
+{
+    [System.String]
+    $Name
+
+    [System.String]
+    $FileName
+
+    [System.Nullable[System.Double]]
+    $Size
+
+    [System.Nullable[System.Double]]
+    $MaxSize
+
+    [System.Nullable[System.Double]]
+    $Growth
+
+    [ValidateSet('KB', 'MB', 'Percent')]
+    [System.String]
+    $GrowthType
+
+    [System.Boolean]
+    $IsPrimaryFile = $false
+
+    DatabaseFileSpec()
+    {
+    }
+
+    DatabaseFileSpec([System.String] $name, [System.String] $fileName)
+    {
+        $this.Name = $name
+        $this.FileName = $fileName
+    }
+}

source/Classes/004.DatabaseFileGroupSpec.ps1

@@ -0,0 +1,110 @@
+<#
+    .SYNOPSIS
+        Defines a file group specification for a database.
+
+    .DESCRIPTION
+        This class represents a file group specification that can be used when
+        creating a new database. It contains the properties needed to define
+        a file group and its associated data files without requiring an existing
+        database SMO object.
+
+    .PARAMETER Name
+        The name of the file group. For the primary file group, this should be 'PRIMARY'.
+
+    .PARAMETER Files
+        An array of DatabaseFileSpec objects that define the data files belonging
+        to this file group. At least one file must be specified for each file group.
+
+    .PARAMETER ReadOnly
+        Specifies whether the file group is read-only. If not specified, defaults
+        to $false (read-write).
+
+    .PARAMETER IsDefault
+        Specifies whether this file group should be the default file group for
+        new objects. If not specified, defaults to $false. Typically, only the
+        PRIMARY file group or one custom file group should be marked as default.
+
+    .NOTES
+        This class is used to specify file group configurations when creating a new
+        database via New-SqlDscDatabase. Unlike SMO FileGroup objects, these
+        specification objects can be created without an existing database context.
+
+        When creating a database, you typically need at least one file group named
+        'PRIMARY' which contains the primary data file. Additional file groups can
+        be added for organizing data files.
+
+    .EXAMPLE
+        $primaryFile = [DatabaseFileSpec] @{
+            Name = 'MyDatabase_Primary'
+            FileName = 'C:\SQLData\MyDatabase.mdf'
+            IsPrimaryFile = $true
+        }
+
+        $primaryFileGroup = [DatabaseFileGroupSpec]::new()
+        $primaryFileGroup.Name = 'PRIMARY'
+        $primaryFileGroup.Files = @($primaryFile)
+
+        Creates a PRIMARY file group specification with one primary data file.
+
+    .EXAMPLE
+        $dataFile1 = [DatabaseFileSpec] @{
+            Name = 'MyDatabase_Data1'
+            FileName = 'D:\SQLData\MyDatabase_Data1.ndf'
+            Size = 204800  # 200 MB
+        }
+
+        $dataFile2 = [DatabaseFileSpec] @{
+            Name = 'MyDatabase_Data2'
+            FileName = 'D:\SQLData\MyDatabase_Data2.ndf'
+            Size = 204800  # 200 MB
+        }
+
+        $secondaryFileGroup = [DatabaseFileGroupSpec] @{
+            Name = 'SECONDARY'
+            Files = @($dataFile1, $dataFile2)
+        }
+
+        Creates a SECONDARY file group specification with two data files.
+
+    .EXAMPLE
+        [DatabaseFileGroupSpec] @{
+            Name = 'PRIMARY'
+            Files = @(
+                [DatabaseFileSpec] @{
+                    Name = 'MyDB_Primary'
+                    FileName = 'C:\SQLData\MyDB.mdf'
+                }
+            )
+        }
+
+        Creates a PRIMARY file group using hashtable syntax with an embedded file spec.
+#>
+class DatabaseFileGroupSpec
+{
+    [System.String]
+    $Name
+
+    [DatabaseFileSpec[]]
+    $Files
+
+    [System.Boolean]
+    $ReadOnly = $false
+
+    [System.Boolean]
+    $IsDefault = $false
+
+    DatabaseFileGroupSpec()
+    {
+    }
+
+    DatabaseFileGroupSpec([System.String] $name)
+    {
+        $this.Name = $name
+    }
+
+    DatabaseFileGroupSpec([System.String] $name, [DatabaseFileSpec[]] $files)
+    {
+        $this.Name = $name
+        $this.Files = $files
+    }
+}