xSQLServerScript: Changes to the resource and tests

CHANGELOG.md

@@ -18,6 +18,12 @@
   - The resource no longer uses Win32_Product WMI class when evaluating if SQL Server Management Studio is installed. See article [kb974524](https://support.microsoft.com/en-us/kb/974524) for more information.
   - Now it uses CIM cmdlets to get information from WMI classes.
   - Resolved all of the PSScriptAnalyzer warnings that was triggered in the common tests.
+- Changes to xSQLServerScript
+  - All credential parameters now also has the type [System.Management.Automation.Credential()] to better work with PowerShell 4.0.
+  - It is now possible to configure two instances on the same node, with the same script.
+  - Added to the description text for the parameter `Credential` describing how to authenticate using Windows Authentication.
+  - Added examples to show how to authenticate using either SQL or Windows authentication.
+  - A recent issue showed that there is a known problem running this resource using PowerShell 4.0. For more information, see [issue #273](https://github.com/PowerShell/xSQLServer/issues/273)
 
 ## 4.0.0.0
 

DSCResources/MSFT_xSQLServerScript/MSFT_xSQLServerScript.psm1

@@ -1,10 +1,39 @@
-$currentPath = Split-Path -Parent $MyInvocation.MyCommand.Path
-Write-Verbose -Message "CurrentPath: $currentPath"
-
-# Load Common Code
-Import-Module $currentPath\..\..\xSQLServerHelper.psm1 -Verbose:$false -ErrorAction Stop
-
-
+$script:currentPath = Split-Path -Path $MyInvocation.MyCommand.Path -Parent
+Import-Module -Name (Join-Path -Path (Split-Path -Path (Split-Path -Path $script:currentPath -Parent) -Parent) -ChildPath 'xSQLServerHelper.psm1')
+
+<#
+    .SYNOPSIS
+        Returns the current state of the SQL Server features.
+
+    .PARAMETER ServerInstance
+        The name of an instance of the Database Engine. For a default instance, only specify the computer name. For a named instances,
+        use the format ComputerName\InstanceName.
+
+    .PARAMETER SetFilePath
+        Path to the T-SQL file that will perform Set action.
+
+    .PARAMETER GetFilePath
+        Path to the T-SQL file that will perform Get action.
+        Any values returned by the T-SQL queries will also be returned by the cmdlet Get-DscConfiguration through the `GetResult` property.
+
+    .PARAMETER TestFilePath
+        Path to the T-SQL file that will perform Test action.
+        Any script that does not throw an error or returns null is evaluated to true.
+        The cmdlet Invoke-SqlCmd treats T-SQL Print statements as verbose text, and will not cause the test to return false.
+
+    .PARAMETER Credential
+        The credentials to authenticate with, using SQL Authentication. To authenticate using Windows Authentication, assign the credentials
+        to the built-in parameter `PsDscRunAsCredential`. If both parameters `Credential` and `PsDscRunAsCredential` are not assigned,
+        then SYSTEM account will be used to authenticate using Windows Authentication.
+
+    .PARAMETER Variable
+        Specifies, as a string array, a sqlcmd scripting variable for use in the 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).
+
+    .OUTPUTS
+        Hash table containing key 'GetResult' which holds the value of the result from the SQL script that was ran from the parameter 'GetFilePath'.
+#>
 function Get-TargetResource
 {
     [CmdletBinding()]
@@ -28,30 +57,61 @@ function Get-TargetResource
         $TestFilePath,
 
         [System.Management.Automation.PSCredential]
+        [System.Management.Automation.Credential()]
         $Credential,
 
         [System.String[]]
         $Variable
-    )   
+    )
 
     $result = Invoke-SqlScript -ServerInstance $ServerInstance -SqlScriptPath $GetFilePath `
                 -Credential $Credential -Variable $Variable -ErrorAction Stop
 
     $getResult = Out-String -InputObject $result
-        
+
     $returnValue = @{
         ServerInstance = [System.String] $ServerInstance
         SetFilePath = [System.String] $SetFilePath
         GetFilePath = [System.String] $GetFilePath
         TestFilePath = [System.String] $TestFilePath
-        Username = [System.Management.Automation.PSCredential] $Credential
+        Username = [System.Object] $Credential
         Variable = [System.String[]] $Variable
         GetResult = [System.String[]] $getresult
     }
 
     $returnValue
 }
 
+<#
+    .SYNOPSIS
+        Returns the current state of the SQL Server features.
+
+    .PARAMETER ServerInstance
+        The name of an instance of the Database Engine. For a default instance, only specify the computer name. For a named instances,
+        use the format ComputerName\InstanceName.
+
+    .PARAMETER SetFilePath
+        Path to the T-SQL file that will perform Set action.
+
+    .PARAMETER GetFilePath
+        Path to the T-SQL file that will perform Get action.
+        Any values returned by the T-SQL queries will also be returned by the cmdlet Get-DscConfiguration through the `GetResult` property.
+
+    .PARAMETER TestFilePath
+        Path to the T-SQL file that will perform Test action.
+        Any script that does not throw an error or returns null is evaluated to true.
+        The cmdlet Invoke-SqlCmd treats T-SQL Print statements as verbose text, and will not cause the test to return false.
+
+    .PARAMETER Credential
+        The credentials to authenticate with, using SQL Authentication. To authenticate using Windows Authentication, assign the credentials
+        to the built-in parameter `PsDscRunAsCredential`. If both parameters `Credential` and `PsDscRunAsCredential` are not assigned,
+        then SYSTEM account will be used to authenticate using Windows Authentication.
+
+    .PARAMETER Variable
+        Specifies, as a string array, a sqlcmd scripting variable for use in the 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).
+#>
 function Set-TargetResource
 {
     [CmdletBinding()]
@@ -74,6 +134,7 @@ function Set-TargetResource
         $TestFilePath,
 
         [System.Management.Automation.PSCredential]
+        [System.Management.Automation.Credential()]
         $Credential,
 
         [System.String[]]
@@ -84,7 +145,37 @@ function Set-TargetResource
                 -Credential $Credential -Variable $Variable -ErrorAction Stop
 }
 
+<#
+    .SYNOPSIS
+        Returns the current state of the SQL Server features.
+
+    .PARAMETER ServerInstance
+        The name of an instance of the Database Engine. For a default instance, only specify the computer name. For a named instances,
+        use the format ComputerName\InstanceName.
 
+    .PARAMETER SetFilePath
+        Path to the T-SQL file that will perform Set action.
+
+    .PARAMETER GetFilePath
+        Path to the T-SQL file that will perform Get action.
+        Any values returned by the T-SQL queries will also be returned by the cmdlet Get-DscConfiguration through the `GetResult` property.
+
+    .PARAMETER TestFilePath
+        Path to the T-SQL file that will perform Test action.
+        Any script that does not throw an error or returns null is evaluated to true.
+        The cmdlet Invoke-SqlCmd treats T-SQL Print statements as verbose text, and will not cause the test to return false.
+
+    .PARAMETER Credential
+        The credentials to authenticate with, using SQL Authentication. To authenticate using Windows Authentication, assign the credentials
+        to the built-in parameter `PsDscRunAsCredential`. If both parameters `Credential` and `PsDscRunAsCredential` are not assigned,
+        then SYSTEM account will be used to authenticate using Windows Authentication.
+
+    .PARAMETER Variable
+        Specifies, as a string array, a sqlcmd scripting variable for use in the 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).
+
+#>
 function Test-TargetResource
 {
     [CmdletBinding()]
@@ -108,18 +199,19 @@ function Test-TargetResource
         $TestFilePath,
 
         [System.Management.Automation.PSCredential]
+        [System.Management.Automation.Credential()]
         $Credential,
 
         [System.String[]]
         $Variable
     )
 
     try
-    {   
+    {
         $result = Invoke-SqlScript -ServerInstance $ServerInstance -SqlScriptPath $TestFilePath `
                 -Credential $Credential -Variable $Variable -ErrorAction Stop
 
-        if($result -eq $null)
+        if($null -eq $result)
         {
             return $true
         }
@@ -135,6 +227,25 @@ function Test-TargetResource
     }
 }
 
+<#
+    .SYNOPSIS
+        Execute an SQL script located in a file on disk.
+
+    .PARAMETER ServerInstance
+        The name of an instance of the Database Engine.
+        For default instances, only specify the computer name. For named instances, use the format ComputerName\InstanceName.
+
+    .PARAMETER SqlScriptPath
+        Path to SQL script file that will be executed.
+
+    .PARAMETER Credential
+        The credentials to use to authenticate using SQL Authentication. To authenticate using Windows Authentication, assing the credentials
+        to the built-in parameter 'PsDscRunAsCredential'. If both parameters 'Credential' and 'PsDscRunAsCredential' are not assigned, then
+        the SYSTEM account will be used to authenticate using Windows Authentication.
+
+    .PARAMETER Variable
+        Creates a sqlcmd scripting variable for use in the sqlcmd script, and sets a value for the variable.
+#>
 function Invoke-SqlScript
 {
     param
@@ -148,6 +259,7 @@ function Invoke-SqlScript
         $SqlScriptPath,
 
         [System.Management.Automation.PSCredential]
+        [System.Management.Automation.Credential()]
         $Credential,
 
         [System.String[]]
@@ -159,7 +271,7 @@ function Invoke-SqlScript
     if($null -ne $Credential)
     {
         $null = $PSBoundParameters.Add("Username", $Credential.UserName)
-        $null = $PSBoundParameters.Add("Password", $Credential.GetNetworkCredential().password)   
+        $null = $PSBoundParameters.Add("Password", $Credential.GetNetworkCredential().password)
     }
 
     $null = $PSBoundParameters.Remove("Credential")
@@ -169,4 +281,3 @@ function Invoke-SqlScript
 }
 
 Export-ModuleMember -Function *-TargetResource
-

DSCResources/MSFT_xSQLServerScript/MSFT_xSQLServerScript.schema.mof

@@ -1,13 +1,11 @@
-
 [ClassVersion("1.0.0.0"), FriendlyName("xSQLServerScript")]
 class MSFT_xSQLServerScript : OMI_BaseResource
 {
-    [Required, Description("The name of an instance of the Database Engine. For default instances, only specify the computer name. For named instances, use the format ComputerName\\InstanceName")] String ServerInstance;
-    [Key, Description("Path to SQL file that will perform Set action.")] String SetFilePath;
-    [Key, Description("Path to SQL file that will perform Get action.")] String GetFilePath;
-    [Key, Description("Path to SQL file that will perform Test action.")] String TestFilePath;
-    [Write, EmbeddedInstance("MSFT_Credential"), Description("Credential to be used to run SQL scripts.")] String Credential;
-    [Write, Description("Creates a sqlcmd scripting variable for use in the sqlcmd script, and sets a value for the variable.")] String Variable[];
-    [Read, Description("Result of Get action.")] String GetResult[];
+    [Key, Description("The name of an instance of the Database Engine. For a default instance, only specify the computer name. For a named instance, use the format ComputerName\\InstanceName")] String ServerInstance;
+    [Key, Description("Path to the T-SQL file that will perform Set action.")] String SetFilePath;
+    [Key, Description("Path to the T-SQL file that will perform Get action. Any values returned by the T-SQL queries will also be returned by the cmdlet Get-DscConfiguration through the 'GetResult' property.")] String GetFilePath;
+    [Key, Description("Path to the T-SQL file that will perform Test action. Any script that does not throw an error or returns null is evaluated to true. The cmdlet Invoke-SqlCmd treats T-SQL Print statements as verbose text, and will not cause the test to return false.")] String TestFilePath;
+    [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 both parameters 'Credential' and 'PsDscRunAsCredential' are not assigned, then SYSTEM account will be used to authenticate using Windows Authentication.")] String Credential;
+    [Write, Description("Specifies, as a string array, a sqlcmd scripting variable for use in the 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.")] String Variable[];
+    [Read, Description("Contains the values returned from the T-SQL script provided in the parameter 'GetFilePath' when cmdlet Get-DscConfiguration is run.")] String GetResult[];
 };
-

Examples/Resources/xSQLServerScript/1-RunScriptUsingSQLAuthentication.ps1

@@ -0,0 +1,41 @@
+<#
+.EXAMPLE
+    This example shows how to run SQL script using SQL Authentication.
+#>
+
+Configuration Example 
+{
+    param(
+        [Parameter(Mandatory = $true)]
+        [PSCredential]
+        $SqlCredential
+    )
+
+    Import-DscResource -ModuleName xSQLServer
+
+    Node localhost
+    {
+        xSQLServerScript 'RunSQLScript'
+        {
+            ServerInstance = 'localhost\SQL2016'
+            Credential = $SqlCredential
+
+            SetFilePath = 'C:\DSCTemp\SQLScripts\Set-RunSQLScript.sql'
+            TestFilePath = 'C:\DSCTemp\SQLScripts\Test-RunSQLScript.sql'
+            GetFilePath = 'C:\DSCTemp\SQLScripts\Get-RunSQLScript.sql'
+            Variable = @("FilePath=C:\temp\log\AuditFiles")
+        }
+    }
+}
+
+$configurationData = @{ 
+    AllNodes = @(
+        @{
+            NodeName = 'localhost'
+        }
+    )
+}
+
+Example -SqlCredential (Get-Credential) -ConfigurationData $configurationData -OutputPath 'C:\DSCTemp\Configuration'
+
+Start-DscConfiguration -Path 'C:\DSCTemp\Configuration' -Wait -Verbose -Force

Examples/Resources/xSQLServerScript/2-RunScriptUsingWindowsAuthentication.ps1

@@ -0,0 +1,53 @@
+<#
+.EXAMPLE
+    These two example shows how to run SQL script using Windows Authentication.
+    First example shows how the resource is run as account SYSTEM. And the second example shows how the resource is run with a user account.
+#>
+
+Configuration Example 
+{
+    param(
+        [Parameter(Mandatory = $true)]
+        [PSCredential]
+        $WindowsCredential
+    )
+
+    Import-DscResource -ModuleName xSQLServer
+
+    Node localhost
+    {
+        xSQLServerScript 'RunSQLScript-AsSYSTEM'
+        {
+            ServerInstance = 'localhost\SQL2016'
+
+            SetFilePath = 'C:\DSCTemp\SQLScripts\Set-RunSQLScript-AsSYSTEM.sql'
+            TestFilePath = 'C:\DSCTemp\SQLScripts\Test-RunSQLScript-AsSYSTEM.sql'
+            GetFilePath = 'C:\DSCTemp\SQLScripts\Get-RunSQLScript-AsSYSTEM.sql'
+            Variable = @("FilePath=C:\temp\log\AuditFiles")
+        }
+
+        xSQLServerScript 'RunSQLScript-AsUSER'
+        {
+            ServerInstance = 'localhost\SQL2016'
+
+            SetFilePath = 'C:\DSCTemp\SQLScripts\Set-RunSQLScript-AsUSER.sql'
+            TestFilePath = 'C:\DSCTemp\SQLScripts\Test-RunSQLScript-AsUSER.sql'
+            GetFilePath = 'C:\DSCTemp\SQLScripts\Get-RunSQLScript-AsUSER.sql'
+            Variable = @("FilePath=C:\temp\log\AuditFiles")
+
+            PsDscRunAsCredential = $WindowsCredential
+        }
+    }
+}
+
+$configurationData = @{
+    AllNodes = @(
+        @{
+            NodeName = 'localhost'
+        }
+    )
+}
+
+Example -SqlCredential (Get-Credential) -ConfigurationData $configurationData -OutputPath 'C:\DSCTemp\Configuration'
+
+Start-DscConfiguration -Path 'C:\DSCTemp\Configuration' -Wait -Verbose -Force