SqlScript, SqlScriptQuery: Add support for disable variables parameter

CHANGELOG.md

@@ -54,6 +54,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     resource README.md, and some was added to the schema MOF parameter
     descriptions ([issue #1580](https://github.com/dsccommunity/SqlServerDsc/issues/1580)).
 
+### Added
+
+- SqlScript
+  - Added the DisableVariables parameter ([issue #1422](https://github.com/dsccommunity/SqlServerDsc/issues/1422)).
+- SqlScriptQuery
+  - Added the DisableVariables parameter ([issue #1422](https://github.com/dsccommunity/SqlServerDsc/issues/1422)).
+
 ## [14.0.0] - 2020-06-12
 
 ### Remove

source/DSCResources/DSC_SqlScript/DSC_SqlScript.psm1

@@ -40,6 +40,10 @@ $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
         Use a Windows PowerShell array to specify multiple variables and their values. For more information how to use this,
         please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx).
 
+    .PARAMETER DisableVariables
+        Specifies, as a boolean, whether or not PowerShell will ignore sqlcmd scripting variables that share a format such as $(variable_name).
+        For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx)")]
+
     .PARAMETER QueryTimeout
         Specifies, as an integer, the number of seconds after which the T-SQL script execution will time out.
         In some SQL Server versions there is a bug in Invoke-Sqlcmd where the normal default value 0 (no timeout) is not respected and the default value is incorrectly set to 30 seconds.
@@ -85,19 +89,24 @@ function Get-TargetResource
 
         [Parameter()]
         [System.String[]]
-        $Variable
+        $Variable,
+
+        [Parameter()]
+        [System.Boolean]
+        $DisableVariables
     )
 
     $serverInstance = ConvertTo-ServerInstanceName -InstanceName $InstanceName -ServerName $ServerName
 
     $invokeParameters = @{
-        ServerInstance = $serverInstance
-        InputFile      = $GetFilePath
-        Credential     = $Credential
-        Variable       = $Variable
-        QueryTimeout   = $QueryTimeout
-        Verbose        = $VerbosePreference
-        ErrorAction    = 'Stop'
+        ServerInstance   = $serverInstance
+        InputFile        = $GetFilePath
+        Credential       = $Credential
+        Variable         = $Variable
+        DisableVariables = $DisableVariables
+        QueryTimeout     = $QueryTimeout
+        Verbose          = $VerbosePreference
+        ErrorAction      = 'Stop'
     }
 
     Write-Verbose -Message (
@@ -109,15 +118,16 @@ function Get-TargetResource
     $getResult = Out-String -InputObject $result
 
     $returnValue = @{
-        ServerName   = [System.String] $ServerName
-        InstanceName = [System.String] $InstanceName
-        SetFilePath  = [System.String] $SetFilePath
-        GetFilePath  = [System.String] $GetFilePath
-        TestFilePath = [System.String] $TestFilePath
-        Credential   = [System.Object] $Credential
-        QueryTimeout = [System.UInt32] $QueryTimeout
-        Variable     = [System.String[]] $Variable
-        GetResult    = [System.String[]] $getResult
+        ServerName       = [System.String] $ServerName
+        InstanceName     = [System.String] $InstanceName
+        SetFilePath      = [System.String] $SetFilePath
+        GetFilePath      = [System.String] $GetFilePath
+        TestFilePath     = [System.String] $TestFilePath
+        Credential       = [System.Object] $Credential
+        QueryTimeout     = [System.UInt32] $QueryTimeout
+        Variable         = [System.String[]] $Variable
+        DisableVariables = [System.Boolean] $DisableVariables
+        GetResult        = [System.String[]] $getResult
     }
 
     return $returnValue
@@ -164,6 +174,10 @@ function Get-TargetResource
         Specifies, as a string array, a Invoke-Sqlcmd scripting variable for use in the Invoke-Sqlcmd script, and sets a value for the variable.
         Use a Windows PowerShell array to specify multiple variables and their values. For more information how to use this,
         please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx).
+
+    .PARAMETER DisableVariables
+        Specifies, as a boolean, whether or not PowerShell will ignore sqlcmd scripting variables that share a format such as $(variable_name).
+        For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx)")]
 #>
 function Set-TargetResource
 {
@@ -202,7 +216,11 @@ function Set-TargetResource
 
         [Parameter()]
         [System.String[]]
-        $Variable
+        $Variable,
+
+        [Parameter()]
+        [System.Boolean]
+        $DisableVariables
     )
 
     $serverInstance = ConvertTo-ServerInstanceName -InstanceName $InstanceName -ServerName $ServerName
@@ -212,13 +230,14 @@ function Set-TargetResource
     )
 
     $invokeParameters = @{
-        ServerInstance = $serverInstance
-        InputFile      = $SetFilePath
-        Credential     = $Credential
-        Variable       = $Variable
-        QueryTimeout   = $QueryTimeout
-        Verbose        = $VerbosePreference
-        ErrorAction    = 'Stop'
+        ServerInstance   = $serverInstance
+        InputFile        = $SetFilePath
+        Credential       = $Credential
+        Variable         = $Variable
+        DisableVariables = $DisableVariables
+        QueryTimeout     = $QueryTimeout
+        Verbose          = $VerbosePreference
+        ErrorAction      = 'Stop'
     }
 
     Invoke-SqlScript @invokeParameters
@@ -266,6 +285,9 @@ function Set-TargetResource
         Use a Windows PowerShell array to specify multiple variables and their values. For more information how to use this,
         please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx).
 
+    .PARAMETER DisableVariables
+        Specifies, as a boolean, whether or not PowerShell will ignore sqlcmd scripting variables that share a format such as $(variable_name).
+        For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx).
 #>
 function Test-TargetResource
 {
@@ -305,7 +327,11 @@ function Test-TargetResource
 
         [Parameter()]
         [System.String[]]
-        $Variable
+        $Variable,
+
+        [Parameter()]
+        [System.Boolean]
+        $DisableVariables
     )
 
     Write-Verbose -Message (
@@ -315,13 +341,14 @@ function Test-TargetResource
     $serverInstance = ConvertTo-ServerInstanceName -InstanceName $InstanceName -ServerName $ServerName
 
     $invokeParameters = @{
-        ServerInstance = $serverInstance
-        InputFile      = $TestFilePath
-        Credential     = $Credential
-        Variable       = $Variable
-        QueryTimeout   = $QueryTimeout
-        Verbose        = $VerbosePreference
-        ErrorAction    = 'Stop'
+        ServerInstance   = $serverInstance
+        InputFile        = $TestFilePath
+        Credential       = $Credential
+        Variable         = $Variable
+        DisableVariables = $DisableVariables
+        QueryTimeout     = $QueryTimeout
+        Verbose          = $VerbosePreference
+        ErrorAction      = 'Stop'
     }
 
     $result = $null

source/DSCResources/DSC_SqlScript/DSC_SqlScript.schema.mof

@@ -8,6 +8,7 @@ class DSC_SqlScript : OMI_BaseResource
     [Write, Description("Specifies the host name of the SQL Server to be configured. Default value is $env:COMPUTERNAME.")] String ServerName;
     [Write, EmbeddedInstance("MSFT_Credential"), Description("The credentials to authenticate with, using SQL Authentication. To authenticate using Windows Authentication assign the credentials to the built-in parameter 'PsDscRunAsCredential'. If neither of the parameters 'Credential' and 'PsDscRunAsCredential' are assigned, then the SYSTEM account will be used to authenticate using Windows Authentication.")] String Credential;
     [Write, Description("Specifies, as a string array, a scripting variable for use in the sql script, and sets a value for the variable. Use an array to specify multiple variables and their values. For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx)")] String Variable[];
+    [Write, Description("Specifies, as a boolean, whether or not PowerShell will ignore sqlcmd scripting variables that share a format such as $(variable_name).  For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx)")] Boolean DisableVariables;
     [Write, Description("Specifies, as an integer, the number of seconds after which the T-SQL script execution will time out.  In some SQL Server versions there is a bug in Invoke-Sqlcmd where the normal default value 0 (no timeout) is not respected and the default value is incorrectly set to 30 seconds.")] UInt32 QueryTimeout;
     [Read, Description("Returns the result from the T-SQL script provided in the parameter 'GetFilePath' when cmdlet Get-DscConfiguration is run.")] String GetResult[];
 };

source/DSCResources/DSC_SqlScriptQuery/DSC_SqlScriptQuery.psm1

@@ -40,6 +40,10 @@ $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
         Use a Windows PowerShell array to specify multiple variables and their values. For more information how to use this,
         please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx).
 
+    .PARAMETER DisableVariables
+        Specifies, as a boolean, whether or not PowerShell will ignore sqlcmd scripting variables that share a format such as $(variable_name).
+        For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx).
+
     .PARAMETER QueryTimeout
         Specifies, as an integer, the number of seconds after which the T-SQL script execution will time out.
         In some SQL Server versions there is a bug in Invoke-Sqlcmd where the normal default value 0 (no timeout) is not respected and the default value is incorrectly set to 30 seconds.
@@ -85,7 +89,11 @@ function Get-TargetResource
 
         [Parameter()]
         [System.String[]]
-        $Variable
+        $Variable,
+
+        [Parameter()]
+        [System.Boolean]
+        $DisableVariables
     )
 
     Write-Verbose -Message (
@@ -95,29 +103,31 @@ function Get-TargetResource
     $serverInstance = ConvertTo-ServerInstanceName -InstanceName $InstanceName -ServerName $ServerName
 
     $invokeParameters = @{
-        Query          = $GetQuery
-        ServerInstance = $serverInstance
-        Credential     = $Credential
-        Variable       = $Variable
-        QueryTimeout   = $QueryTimeout
-        Verbose        = $VerbosePreference
-        ErrorAction    = 'Stop'
+        Query            = $GetQuery
+        ServerInstance   = $serverInstance
+        Credential       = $Credential
+        Variable         = $Variable
+        DisableVariables = $DisableVariables
+        QueryTimeout     = $QueryTimeout
+        Verbose          = $VerbosePreference
+        ErrorAction      = 'Stop'
     }
 
     $result = Invoke-SqlScript @invokeParameters
 
     $getResult = Out-String -InputObject $result
 
     $returnValue = @{
-        ServerName   = [System.String] $ServerName
-        InstanceName = [System.String] $InstanceName
-        GetQuery     = [System.String] $GetQuery
-        TestQuery    = [System.String] $TestQuery
-        SetQuery     = [System.String] $SetQuery
-        Credential   = [System.Object] $Credential
-        QueryTimeout = [System.UInt32] $QueryTimeout
-        Variable     = [System.String[]] $Variable
-        GetResult    = [System.String[]] $getResult
+        ServerName       = [System.String] $ServerName
+        InstanceName     = [System.String] $InstanceName
+        GetQuery         = [System.String] $GetQuery
+        TestQuery        = [System.String] $TestQuery
+        SetQuery         = [System.String] $SetQuery
+        Credential       = [System.Object] $Credential
+        QueryTimeout     = [System.UInt32] $QueryTimeout
+        Variable         = [System.String[]] $Variable
+        DisableVariables = [System.Boolean] $DisableVariables
+        GetResult        = [System.String[]] $getResult
     }
 
     return $returnValue
@@ -164,6 +174,10 @@ function Get-TargetResource
         Specifies, as a string array, a Invoke-Sqlcmd scripting variable for use in the Invoke-Sqlcmd script, and sets a value for the variable.
         Use a Windows PowerShell array to specify multiple variables and their values. For more information how to use this,
         please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx).
+
+    .PARAMETER DisableVariables
+        Specifies, as a boolean, whether or not PowerShell will ignore sqlcmd scripting variables that share a format such as $(variable_name).
+        For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx)")]
 #>
 function Set-TargetResource
 {
@@ -202,7 +216,11 @@ function Set-TargetResource
 
         [Parameter()]
         [System.String[]]
-        $Variable
+        $Variable,
+
+        [Parameter()]
+        [System.Boolean]
+        $DisableVariables
     )
 
     Write-Verbose -Message (
@@ -212,13 +230,14 @@ function Set-TargetResource
     $serverInstance = ConvertTo-ServerInstanceName -InstanceName $InstanceName -ServerName $ServerName
 
     $invokeParameters = @{
-        Query          = $SetQuery
-        ServerInstance = $serverInstance
-        Credential     = $Credential
-        Variable       = $Variable
-        QueryTimeout   = $QueryTimeout
-        Verbose        = $VerbosePreference
-        ErrorAction    = 'Stop'
+        Query            = $SetQuery
+        ServerInstance   = $serverInstance
+        Credential       = $Credential
+        Variable         = $Variable
+        DisableVariables = $DisableVariables
+        QueryTimeout     = $QueryTimeout
+        Verbose          = $VerbosePreference
+        ErrorAction      = 'Stop'
     }
 
     Invoke-SqlScript @invokeParameters
@@ -266,6 +285,10 @@ function Set-TargetResource
         Use a Windows PowerShell array to specify multiple variables and their values. For more information how to use this,
         please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx).
 
+    .PARAMETER DisableVariables
+        Specifies, as a boolean, whether or not PowerShell will ignore sqlcmd scripting variables that share a format such as $(variable_name).
+        For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx)")]
+
 #>
 function Test-TargetResource
 {
@@ -305,7 +328,11 @@ function Test-TargetResource
 
         [Parameter()]
         [System.String[]]
-        $Variable
+        $Variable,
+
+        [Parameter()]
+        [System.Boolean]
+        $DisableVariables
     )
 
     Write-Verbose -Message (
@@ -315,13 +342,14 @@ function Test-TargetResource
     $serverInstance = ConvertTo-ServerInstanceName -InstanceName $InstanceName -ServerName $ServerName
 
     $invokeParameters = @{
-        Query          = $TestQuery
-        ServerInstance = $serverInstance
-        Credential     = $Credential
-        Variable       = $Variable
-        QueryTimeout   = $QueryTimeout
-        Verbose        = $VerbosePreference
-        ErrorAction    = 'Stop'
+        Query            = $TestQuery
+        ServerInstance   = $serverInstance
+        Credential       = $Credential
+        Variable         = $Variable
+        DisableVariables = $DisableVariables
+        QueryTimeout     = $QueryTimeout
+        Verbose          = $VerbosePreference
+        ErrorAction      = 'Stop'
     }
 
     $result = $null

source/DSCResources/DSC_SqlScriptQuery/DSC_SqlScriptQuery.schema.mof

@@ -8,6 +8,7 @@ class DSC_SqlScriptQuery : OMI_BaseResource
     [Write, Description("Specifies the host name of the SQL Server to be configured. Default value is $env:COMPUTERNAME.")] String ServerName;
     [Write, EmbeddedInstance("MSFT_Credential"), Description("The credentials to authenticate with, using SQL Authentication. To authenticate using Windows Authentication, assign the credentials to the built-in parameter 'PsDscRunAsCredential'. If neither of the parameters 'Credential' and 'PsDscRunAsCredential' are assigned then the SYSTEM account will be used to authenticate using Windows Authentication.")] String Credential;
     [Write, Description("Specifies, as a string array, a scripting variable for use in the sql script, and sets a value for the variable. Use a Windows PowerShell array to specify multiple variables and their values. For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx)")] String Variable[];
+    [Write, Description("Specifies, as a boolean, whether or not PowerShell will ignore sqlcmd scripting variables that share a format such as $(variable_name).  For more information how to use this, please go to the help documentation for [Invoke-Sqlcmd](https://technet.microsoft.com/en-us/library/mt683370.aspx)")] Boolean DisableVariables;
     [Write, Description("Specifies, as an integer, the number of seconds after which the T-SQL script execution will time out. In some SQL Server versions there is a bug in Invoke-Sqlcmd where the normal default value 0 (no timeout) is not respected and the default value is incorrectly set to 30 seconds.")] UInt32 QueryTimeout;
     [Read, Description("Returns the result from the T-SQL script provided in the parameter 'GetQuery' when cmdlet Get-DscConfiguration is run.")] String GetResult[];
 };

source/Examples/Resources/SqlScript/4-RunScriptUsingDisabledVariables.ps1

@@ -0,0 +1,31 @@
+<#
+    .DESCRIPTION
+        This example shows how to run SQL script with disabled variables.
+#>
+
+Configuration Example
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.Management.Automation.PSCredential]
+        $SqlCredential
+    )
+
+    Import-DscResource -ModuleName 'SqlServerDsc'
+
+    Node localhost
+    {
+        SqlScript 'RunWithDisabledVariables'
+        {
+            ServerName       = 'localhost'
+            InstanceName     = 'SQL2016'
+            Credential       = $SqlCredential
+
+            SetFilePath      = 'C:\DSCTemp\SQLScripts\Set-RunSQLScript.sql'
+            TestFilePath     = 'C:\DSCTemp\SQLScripts\Test-RunSQLScript.sql'
+            GetFilePath      = 'C:\DSCTemp\SQLScripts\Get-RunSQLScript.sql'
+            DisableVariables = $true
+        }
+    }
+}