Changes to add export functions for Roles (#5954)

* Changes to add export functions for Roles

* Fixing Issues with Offline databases , adding Try Catch

* uncaught exception

* Revert "uncaught exception"

This reverts commit dba2f85.

* Changes to exclude unsupported versions and AzureSqlDb

* Formatting

* Adding exclusion for databases in CompatibilityLevel 80 or lower

functions/Export-DbaServerRole.ps1

@@ -0,0 +1,356 @@
+function Export-DbaServerRole {
+    <#
+    .SYNOPSIS
+        Exports server roles to a T-SQL file. Export includes Role creation, object permissions and Schema ownership.
+
+    .DESCRIPTION
+        Exports Server roles to a T-SQL file. Export includes Role creation, object permissions and Role Members
+
+        Applies mostly to SQL Server 2012 or Higher when user defined Server roles were added but can be used on earlier versions to get role members.
+        This command is an extension of John Eisbrener's post "Fully Script out a MSSQL Database Role"
+        Reference:  https://dbaeyes.wordpress.com/2013/04/19/fully-script-out-a-mssql-database-role/
+
+    .PARAMETER SqlInstance
+        The target SQL Server instance or instances. SQL Server 2000 and above supported.
+
+    .PARAMETER SqlCredential
+        Login to the target instance using alternative credentials. Windows and SQL Authentication supported. Accepts credential objects (Get-Credential)
+
+    .PARAMETER InputObject
+        Enables piping from Get-DbaServerRole
+
+     .PARAMETER ScriptingOptionsObject
+        An SMO Scripting Object that can be used to customize the output - see New-DbaScriptingOption
+
+    .PARAMETER ServerRole
+        Server-Level role(s) to filter results to that role only.
+
+    .PARAMETER ExcludeServerRole
+        Server-Level role(s) to exclude from results.
+
+    .PARAMETER ExcludeFixedRole
+        Filter the fixed server-level roles. As only SQL Server 2012 or higher supports creation of server-level roles will eliminate all output for earlier versions.
+
+    .PARAMETER IncludeRoleMember
+        Include scripting of role members in script
+
+    .PARAMETER Path
+        Specifies the directory where the file or files will be exported.
+        Will default to Path.DbatoolsExport Configuration entry
+
+    .PARAMETER FilePath
+        Specifies the full file path of the output file. If left blank then filename based on Instance name, Database name and date is created.
+        If more than one database or instance is input then this parameter should normally be blank.
+
+    .PARAMETER Passthru
+        Output script to console only
+
+    .PARAMETER BatchSeparator
+        Batch separator for scripting output. Uses the value from configuration Formatting.BatchSeparator by default. This is normally "GO"
+
+    .PARAMETER NoClobber
+        If this switch is enabled, a file already existing at the path specified by Path will not be overwritten. This takes precedence over Append switch
+
+    .PARAMETER Append
+        If this switch is enabled, content will be appended to a file already existing at the path specified by FilePath. If the file does not exist, it will be created.
+
+    .PARAMETER NoPrefix
+        Do not include a Prefix
+
+    .PARAMETER Encoding
+        Specifies the file encoding. The default is UTF8.
+
+        Valid values are:
+        -- ASCII: Uses the encoding for the ASCII (7-bit) character set.
+        -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order.
+        -- Byte: Encodes a set of characters into a sequence of bytes.
+        -- String: Uses the encoding type for a string.
+        -- Unicode: Encodes in UTF-16 format using the little-endian byte order.
+        -- UTF7: Encodes in UTF-7 format.
+        -- UTF8: Encodes in UTF-8 format.
+        -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary.
+
+
+    .PARAMETER EnableException
+        By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
+        This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
+        Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
+
+    .NOTES
+        Tags: Export, Role
+        Author: Patrick Flynn (@sqllensman)
+
+        Website: https://dbatools.io
+        Copyright: (c) 2018 by dbatools, licensed under MIT
+        License: MIT https://opensource.org/licenses/MIT
+
+    .LINK
+        https://dbatools.io/Export-DbaServerRole
+
+    .EXAMPLE
+        PS C:\> Export-DbaServerRole -SqlInstance sql2005
+
+        Exports the Server Roles for SQL Server "sql2005" and writes them to the path defined in the ConfigValue 'Path.DbatoolsExport' using a a default name pattern of ServerName-YYYYMMDDhhmmss-serverrole. Uses BatchSeparator defined by Config 'Formatting.BatchSeparator'
+
+    .EXAMPLE
+        PS C:\> Export-DbaServerRole -SqlInstance sql2005 -Path C:\temp
+
+        Exports the Server Roles for SQL Server "sql2005" and writes them to the path "C:\temp" using a a default name pattern of ServerName-YYYYMMDDhhmmss-serverrole. Uses BatchSeparator defined by Config 'Formatting.BatchSeparator'
+
+    .EXAMPLE
+        PS C:\> Export-DbaServerRole -SqlInstance sqlserver2014a -FilePath C:\temp\ServerRoles.sql
+
+        Exports the Server Roles for SQL Server sqlserver2014a to the file  C:\temp\ServerRoles.sql. Overwrites file if exists
+
+    .EXAMPLE
+        PS C:\> Export-DbaServerRole -SqlInstance sqlserver2014a -ServerRole SchemaReader -Passthru
+
+        Exports ONLY ServerRole SchemaReader FROM sqlserver2014a and writes script to console
+
+    .EXAMPLE
+        PS C:\> Export-DbaServerRole -SqlInstance sqlserver2008 -ExcludeFixedRole -ExcludeServerRole Public -IncludeRoleMember -FilePath C:\temp\ServerRoles.sql -Append -BatchSeparator ''
+
+        Exports server roles from sqlserver2008, exludes all roles marked as as FixedRole and Public role. Includes RoleMembers and writes to file C:\temp\ServerRoles.sql, appending to file if it exits. Does not include a BatchSeparator
+
+    .EXAMPLE
+        PS C:\> Get-DbaServerRole -SqlInstance sqlserver2012, sqlserver2014  | Export-DbaServerRole
+
+        Exports server roles from sqlserver2012, sqlserver2014 and writes them to the path defined in the ConfigValue 'Path.DbatoolsExport' using a a default name pattern of ServerName-YYYYMMDDhhmmss-serverrole
+
+    .EXAMPLE
+        PS C:\> Get-DbaServerRole -SqlInstance sqlserver2016 -ExcludeFixedRole -ExcludeServerRole Public | Export-DbaServerRole -IncludeRoleMember
+
+        Exports server roles from sqlserver2016, exludes all roles marked as as FixedRole and Public role. Includes RoleMembers
+
+    #>
+    [CmdletBinding()]
+    param (
+        [parameter()]
+        [DbaInstanceParameter[]]$SqlInstance,
+        [PSCredential]$SqlCredential,
+        [Parameter(ValueFromPipeline)]
+        [object[]]$InputObject,
+        [Microsoft.SqlServer.Management.Smo.ScriptingOptions]$ScriptingOptionsObject,
+        [string[]]$ServerRole,
+        [string[]]$ExcludeServerRole,
+        [switch]$ExcludeFixedRole,
+        [switch]$IncludeRoleMember,
+        [string]$Path = (Get-DbatoolsConfigValue -FullName 'Path.DbatoolsExport'),
+        [Alias("OutFile", "FileName")]
+        [string]$FilePath,
+        [switch]$Passthru,
+        [string]$BatchSeparator = (Get-DbatoolsConfigValue -FullName 'Formatting.BatchSeparator'),
+        [switch]$NoClobber,
+        [switch]$Append,
+        [switch]$NoPrefix,
+        [ValidateSet('ASCII', 'BigEndianUnicode', 'Byte', 'String', 'Unicode', 'UTF7', 'UTF8', 'Unknown')]
+        [string]$Encoding = 'UTF8',
+        [switch]$EnableException
+    )
+    begin {
+        $null = Test-ExportDirectory -Path $Path
+        $outsql = @()
+        $outputFileArray = @()
+        $roleCollection = New-Object System.Collections.ArrayList
+        $executingUser = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+        $commandName = $MyInvocation.MyCommand.Name
+
+        $roleSQL = "SELECT
+                    CASE SPerm.state
+                        WHEN 'D' THEN 'DENY'
+                        WHEN 'G' THEN 'GRANT'
+                        WHEN 'R' THEN 'REVOKE'
+                        WHEN 'W' THEN 'GRANT'
+                    END as GrantState,
+                    sPerm.permission_name as Permission,
+                    Case
+                        WHEN SPerm.class = 100 THEN ''
+                        WHEN SPerm.class = 101 AND sp2.type = 'S' THEN 'ON LOGIN::' + QuoteName(sp2.name)
+                        WHEN SPerm.class = 101 AND sp2.type = 'R' THEN 'ON SERVER ROLE::' + QuoteName(sp2.name)
+                        WHEN SPerm.class = 101 AND sp2.type = 'U' THEN 'ON LOGIN::' + QuoteName(sp2.name)
+                        WHEN SPerm.class = 105 THEN 'ON ENDPOINT::' + QuoteName(ep.name)
+                        WHEN SPerm.class = 108 THEN 'ON AVAILABILITY GROUP::' + QUOTENAME(ag.name)
+                        ELSE ''
+                    END as OnClause,
+                    QuoteName(SP.name) as RoleName,
+                    Case
+                        WHEN SPerm.state = 'W' THEN 'WITH GRANT OPTION AS ' + QUOTENAME(gsp.Name)
+                        ELSE ''
+                    END as GrantOption
+                FROM sys.server_permissions SPerm
+                INNER JOIN sys.server_principals SP
+                    ON SP.principal_id = SPerm.grantee_principal_id
+                INNER JOIN sys.server_principals gsp
+                    ON gsp.principal_id = SPerm.grantor_principal_id
+                LEFT JOIN sys.endpoints ep
+                    ON ep.endpoint_id = SPerm.major_id
+                    AND SPerm.class = 105
+                LEFT JOIN sys.server_principals sp2
+                    ON sp2.principal_id = SPerm.major_id
+                    AND SPerm.class = 101
+                LEFT JOIN
+                (
+                    Select
+                        ar.replica_metadata_id,
+                        ag.name
+                    from sys.availability_groups ag
+                    INNER JOIN sys.availability_replicas ar
+                        ON ag.group_id = ar.group_id
+                ) ag
+                    ON ag.replica_metadata_id = SPerm.major_id
+                    AND SPerm.class = 108
+                where sp.type='R'
+                and sp.name=N'<#RoleName#>'"
+
+        if (Test-Bound -Not -ParameterName ScriptingOptionsObject) {
+            $ScriptingOptionsObject = New-DbaScriptingOption
+            $ScriptingOptionsObject.AllowSystemObjects = $false
+            $ScriptingOptionsObject.ContinueScriptingOnError = $false
+            $ScriptingOptionsObject.IncludeDatabaseContext = $true
+            $ScriptingOptionsObject.IncludeIfNotExists = $true
+            $ScriptingOptionsObject.ScriptOwner = $true
+        }
+
+        if ($ScriptingOptionsObject.NoCommandTerminator) {
+            $commandTerminator = ''
+        } else {
+            $commandTerminator = ';'
+        }
+        $outsql = @()
+    }
+    process {
+        if (Test-FunctionInterrupt) {
+            return
+        }
+
+        if (-not $InputObject -and -not $SqlInstance) {
+            Stop-Function -Message "You must pipe in a ServerRole or server or specify a SqlInstance"
+            return
+        }
+
+        if ($SqlInstance) {
+            $InputObject = $SqlInstance
+        }
+
+        foreach ($input in $InputObject) {
+            $inputType = $input.GetType().FullName
+            switch ($inputType) {
+                'Sqlcollaborative.Dbatools.Parameter.DbaInstanceParameter' {
+                    Write-Message -Level Verbose -Message "Processing DbaInstanceParameter through InputObject"
+                    $serverRoles = Get-DbaServerRole -SqlInstance $input -SqlCredential $sqlcredential  -ServerRole $ServerRole -ExcludeServerRole $ExcludeServerRole -ExcludeFixedRole:$ExcludeFixedRole
+                }
+                'Microsoft.SqlServer.Management.Smo.Server' {
+                    Write-Message -Level Verbose -Message "Processing Server through InputObject"
+                    $serverRoles = Get-DbaServerRole -SqlInstance $input -SqlCredential $sqlcredential -ServerRole $ServerRole -ExcludeServerRole $ExcludeServerRole -ExcludeFixedRole:$ExcludeFixedRole
+                }
+                'Microsoft.SqlServer.Management.Smo.ServerRole' {
+                    Write-Message -Level Verbose -Message "Processing ServerRole through InputObject"
+                    $serverRoles = $input
+                }
+                default {
+                    Stop-Function -Message "InputObject is not a server or serverrole."
+                    return
+                }
+            }
+
+            foreach ($role in $serverRoles) {
+                $server = $role.Parent
+
+                if ($server.ServerType -eq 'SqlAzureDatabase') {
+                    Stop-Function -Message "The SqlAzureDatabase - $server is not supported." -Continue
+                }
+
+                try {
+                    # Get user defined Server roles
+                    if ($server.VersionMajor -ge 11) {
+                        $outsql += $role.Script($ScriptingOptionsObject)
+
+                        $query = $roleSQL.Replace('<#RoleName#>', "$($role.Name)")
+                        $rolePermissions = $server.Query($query)
+
+                        foreach ($rolePermission in $rolePermissions) {
+                            $script = $rolePermission.GrantState + " " + $rolePermission.Permission
+                            if ($rolePermission.OnClause) {
+                                $script += " " + $rolePermission.OnClause
+                            }
+                            if ($rolePermission.RoleName) {
+                                $script += " TO " + $rolePermission.RoleName
+                            }
+                            if ($rolePermission.GrantOption) {
+                                $script += " " + $rolePermission.GrantOption + $commandTerminator
+                            } else {
+                                $script += $commandTerminator
+                            }
+                            $outsql += "$script"
+                        }
+                    }
+
+                    if ($IncludeRoleMember) {
+                        foreach ($roleUser in $role.Login) {
+                            $script = 'ALTER SERVER ROLE [' + $role.Role + "] ADD MEMBER [" + $roleUser + "]" + $commandTerminator
+                            $outsql += "$script"
+                        }
+                    }
+                    if ($outsql) {
+                        $roleObject = [PSCustomObject]@{
+                            Name     = $role.Name
+                            Instance = $role.SqlInstance
+                            Sql      = $outsql
+                        }
+                    }
+                    $roleCollection.Add($roleObject) | Out-Null
+                    $outsql = @()
+                } catch {
+                    $outsql = @()
+                    Stop-Function -Message "Error occurred processing role $Role" -Category ConnectionError -ErrorRecord $_ -Target $role.SqlInstance -Continue
+                }
+            }
+        }
+    }
+    end {
+        if (Test-FunctionInterrupt) { return }
+
+        $timeNow = $(Get-Date -Format (Get-DbatoolsConfigValue -FullName 'Formatting.DateTime'))
+        foreach ($role in $roleCollection) {
+            $instanceName = $role.Instance
+
+            if ($NoPrefix) {
+                $prefix = $null
+            } else {
+                $prefix = "/*`n`tCreated by $executingUser using dbatools $commandName for objects on $instanceName.$databaseName at $timeNow`n`tSee https://dbatools.io/$commandName for more information`n*/"
+            }
+
+            if ($BatchSeparator) {
+                $sql = $role.SQL -join "`r`n$BatchSeparator`r`n"
+                #add the final GO
+                $sql += "`r`n$BatchSeparator"
+            } else {
+                $sql = $role.SQL
+            }
+
+            if ($Passthru) {
+                if ($null -ne $prefix) {
+                    $sql = "$prefix`r`n$sql"
+                }
+                $sql
+            } elseif ($Path -Or $FilePath) {
+                $outputFileName = $instanceName.Replace('\', '$')
+                if ($outputFileArray -notcontains $outputFileName) {
+                    Write-Message -Level Verbose -Message "New File $outputFileName "
+                    if ($null -ne $prefix) {
+                        $sql = "$prefix`r`n$sql"
+                    }
+                    $scriptPath = Get-ExportFilePath -Path $PSBoundParameters.Path -FilePath $PSBoundParameters.FilePath -Type sql -ServerName $outputFileName
+                    $sql | Out-File -Encoding $Encoding -LiteralPath $scriptPath -Append:$Append -NoClobber:$NoClobber
+                    $outputFileArray += $outputFileName
+                    Get-ChildItem $scriptPath
+                } else {
+                    Write-Message -Level Verbose -Message "Adding to $outputFileName "
+                    $sql | Out-File -Encoding $Encoding -LiteralPath $scriptPath -Append
+                }
+            } else {
+                $sql
+            }
+        }
+    }
+}

functions/Get-DbaDbRole.ps1

@@ -104,6 +104,9 @@ function Get-DbaDbRole {
         }
 
         foreach ($db in $InputObject) {
+            if ($db.IsAccessible -eq $false) {
+                continue
+            }
             $server = $db.Parent
             Write-Message -Level 'Verbose' -Message "Getting Database Roles for $db on $server"
 

functions/Get-DbaServerRole.ps1

@@ -65,6 +65,9 @@ function Get-DbaServerRole {
                 Stop-Function -Message "Error occurred while establishing connection to $instance" -Category ConnectionError -ErrorRecord $_ -Target $instance -Continue
             }
 
+            if ($server.ServerType -eq 'SqlAzureDatabase') {
+                Stop-Function -Message "The SqlAzureDatabase - $server is not supported." -Continue
+            }
             $serverroles = $server.Roles
 
             if ($ServerRole) {