Merge pull request #60 from webmd-health-services/feature/PFORM-3233

Export-Migration will now include extended properties on schemas, views, and view columns.

Author: KhoiKy

CHANGELOG.md

@@ -1,4 +1,9 @@
 
+# 0.18.0
+
+* `Export-Migration` will now include extended properties on schemas, views, and view columns.
+
+
 # 0.17.0
 
 ## Changes 

Rivet/Functions/Export-Migration.ps1

@@ -1163,12 +1163,18 @@ where
 -- SCHEMAS
 select 
     sys.schemas.name, 
-    sys.sysusers.name as owner 
+    sys.sysusers.name as owner,
+    sys.extended_properties.value as description
 from 
     sys.schemas 
         join 
     sys.sysusers 
-        on sys.schemas.principal_id = sys.sysusers.uid'
+            on sys.schemas.principal_id = sys.sysusers.uid
+        left join
+    sys.extended_properties
+            on sys.extended_properties.class = 3
+            and sys.extended_properties.major_id = sys.schemas.schema_id
+            and sys.extended_properties.name = ''MS_Description'''
     function Export-Schema
     {
         param(
@@ -1187,9 +1193,14 @@ from
         {
             return
         }
+        $description = $schema.description
+        if( $description )
+        {
+            $description = ' -Description ''{0}''' -f ($description -replace '''','''''')
+        }
 
         Write-ExportingMessage -Schema $Object.schema_name -Type Schema
-        '    Add-Schema -Name ''{0}'' -Owner ''{1}''' -f $schema.name,$schema.owner
+        '    Add-Schema -Name ''{0}'' -Owner ''{1}''{2}' -f $schema.name,$schema.owner, $description
         $exportedSchemas[$schema.name] = $true
         Push-PopOperation ('Remove-Schema -Name ''{0}''' -f $schema.name)
     }
@@ -1534,8 +1545,22 @@ where
         Write-ExportingMessage -Schema $Object.schema_name -Name $Object.name -Type View
         if( $view -match $createPreambleRegex )
         {
+            $description = $Object.description
+            if( $description )
+            {
+                $description = ' -Description ''{0}''' -f ($description -replace '''','''''')
+            }
+    
             $view = $view -replace $createPreambleRegex,''
-            '    Add-View{0} -Name ''{1}'' -Definition @''{2}{3}{2}''@' -f $schema,$Object.name,[Environment]::NewLine,$view
+            '    Add-View{0} -Name ''{1}''{2} -Definition @''{3}{4}{3}''@' -f $schema,$Object.name,$description,[Environment]::NewLine,$view
+
+            # Get view's columns that have extended properties
+            $viewColumns = Invoke-Query -Query $columnsQuery | Where-Object { $_.object_id -eq $Object.object_id -and $_.description }
+            foreach( $column in $viewColumns )
+            {
+                $colDescription = ' -Description ''{0}''' -f ($column.description -replace '''','''''')
+                '    Add-ExtendedProperty -SchemaName ''{0}'' -ViewName ''{1}'' -ColumnName ''{2}'' -Value {3}' -f $Object.schema_name,$Object.object_name,$column.column_name,$colDescription
+            }
         }
         else
         {

Rivet/Functions/Operations/Add-Description.ps1

@@ -3,7 +3,7 @@ function Add-Description
 {
     <#
     .SYNOPSIS
-    Adds the `MS_Description` extended property to a table or column.
+    Adds the `MS_Description` extended property to schemas, tables, columns, views, and view columns.
 
     .DESCRIPTION
     The `sys.sp_addextendedproperty` stored procedure is used to set a table/column's description (i.e. the `MS_Description` extended property), but the syntax is weird.  This function hides that weirdness from you.  You're welcome.
@@ -22,33 +22,62 @@ function Add-Description
     Add-Description -Description 'Whoseit's whatsits table.' -TableName WhoseitsWhatsits -ForTable
     
     PowerShell v2.0 doesn't parse the parameters correctly when setting a table name, so you have to explicitly tell it what to do.  Upgrade to PowerShell 3!
+
+    .EXAMPLE
+    Add-Description -Description 'This is an extended property on a schema' -SchemaName 'test'
+
+    Adds a description (i.e. the `MS_Description` extended property) on the `test` schema.
+
+    .EXAMPLE
+    Add-Description -Description 'This is an extended property on a view' -SchemaName 'test' -ViewName 'testVw'
+
+    Adds a description (i.e. the `MS_Description` extended property) on the `testVw` view.
+    
+    .EXAMPLE
+    Add-Description -Description 'This is an extended property on a view column' -SchemaName 'test' -ViewName 'testVw' -ColumnName 'ID'
+
+    Adds a description (i.e. the `MS_Description` extended property) on the `ID` column in the 'testVw' view.
     #>
     [CmdletBinding()]
     param(
-        [Parameter(Mandatory=$true,Position=0)]
-        [string]
         # The value for the MS_Description extended property.
-        $Description,
+        [Parameter(Mandatory, Position=0)]
+        [String] $Description,
 
-        [Alias('Schema')]
-        [string]
         # The schema.  Defaults to `dbo`.
-        $SchemaName = 'dbo',
+        [Parameter(ParameterSetName='ForSchema')]
+        [Parameter(ParameterSetName='ForTable')]
+        [Parameter(ParameterSetName='ForView')]
+        [Parameter(ParameterSetName='ForColumn')]
+        [Alias('Schema')]
+        [String] $SchemaName = 'dbo',
 
-        [Parameter(Mandatory=$true)]
-        [Alias('Table')]
-        [string]
         # The name of the table where the extended property is getting set.
-        $TableName,
+        [Parameter(Mandatory, ParameterSetName='ForTable')]
+        [Parameter(Mandatory, ParameterSetName='ForColumn')]
+        [Alias('Table')]
+        [String] $TableName,
+
+        # The name of the view where the extended property is getting set.
+        [Parameter(Mandatory, ParameterSetName='ForView')]
+        [Alias('View')]
+        [String] $ViewName,
 
-        [Parameter(ParameterSetName='ForColumn')]
-        [Alias('Column')]
-        [string]
         # The name of the column where the extended property is getting set.
-        $ColumnName
+        [Parameter(Mandatory, ParameterSetName='ForColumn')]
+        [Alias('Column')]
+        [String] $ColumnName
     )
 
     $optionalArgs = @{ }
+    if( $TableName )
+    {
+        $optionalArgs.TableName = $TableName
+    }
+    if( $ViewName )
+    {
+        $optionalArgs.ViewName = $ViewName
+    }
     if( $ColumnName )
     {
         $optionalArgs.ColumnName = $ColumnName
@@ -57,6 +86,5 @@ function Add-Description
     Add-ExtendedProperty -Name ([Rivet.Operations.ExtendedPropertyOperation]::DescriptionPropertyName) `
                          -Value $Description `
                          -SchemaName $SchemaName `
-                         -TableName $TableName `
                          @optionalArgs
 }

Rivet/Functions/Operations/Add-Schema.ps1

@@ -6,28 +6,45 @@ function Add-Schema
     Creates a new schema.
 
     .DESCRIPTION
-    The `Add-Schema` operation creates a new schema in a database. It does so in an idempotent way, i.e. it only creates the schema if it doesn't exist. 
+    The `Add-Schema` operation creates a new schema in a database. It does so in an idempotent way, i.e. it only
+    creates the schema if it doesn't exist. If -Description is provided an extended property named 'MS_Description'
+    will be added to the schema with the description as the value.
 
     .EXAMPLE
     Add-Schema -Name 'rivetexample'
 
     Creates the `rivetexample` schema.
+
+    .EXAMPLE
+    Add-Schema -Name 'rivetTest' -Description 'This is an extended property'
+
+    Creates the `rivetTest` schema with the `MS_Description` extended property.
     #>
     [CmdletBinding()]
     param(
-        [Parameter(Mandatory=$true)]
-        [Alias('SchemaName')]
-        [string]
         # The name of the schema.
-        $Name,
+        [Parameter(Mandatory)]
+        [Alias('SchemaName')]
+        [String] $Name,
 
-        [Alias('Authorization')]
-        [string]
         # The owner of the schema.
-        $Owner
+        [Alias('Authorization')]
+        [String] $Owner,
+
+        # A description of the schema.
+        [String] $Description
     )
 
     Set-StrictMode -Version 'Latest'
+    
+    $schemaOp = New-Object 'Rivet.Operations.AddSchemaOperation' $Name, $Owner
+
+    if( $Description )
+    {
+        $schemaDescriptionOp = Add-Description -SchemaName $Name -Description $Description 
+        $schemaOp.ChildOperations.Add($schemaDescriptionOp)
+    }
 
-    New-Object 'Rivet.Operations.AddSchemaOperation' $Name, $Owner
+    $schemaOp | Write-Output
+    $schemaOp.ChildOperations | Write-Output
 }

Rivet/Functions/Operations/Add-View.ps1

@@ -5,32 +5,47 @@
     Creates a new view.
 
     .DESCRIPTION
-    Creates a new view.
+    Creates a new view. If -Description is provided an extended property named 'MS_Description' will be added to the
+    schema with the description as the value.
 
     .EXAMPLE
     Add-View -SchemaName 'rivet' 'ReadMigrations' 'AS select * from rivet.Migrations'
 
     Creates a view to read all the migrations from Rivet's Migrations table.  Don't do this in real life.
+
+    .EXAMPLE
+    Add-View -Name 'rivetVw' -Description 'This is an extended property'
+
+    Creates the `rivetVw` view with the `MS_Description` extended property.
     #>
     [CmdletBinding()]
     param(
-        [Parameter(Mandatory=$true,Position=0)]
-        [string]
         # The name of the view.
-        $Name,
+        [Parameter(Mandatory, Position=0)]
+        [String] $Name,
 
-        [Parameter()]
-        [string]
         # The schema name of the view.  Defaults to `dbo`.
-        $SchemaName = 'dbo',
+        [Parameter()]
+        [String] $SchemaName = 'dbo',
 
-        [Parameter(Mandatory=$true,Position=1)]
-        [string]
         # The definition of the view. Everything after the `create view [schema].[name]` clause.
-        $Definition
+        [Parameter(Mandatory, Position=1)]
+        [String] $Definition,
+
+        # A description of the view.
+        [String] $Description
     )
 
     Set-StrictMode -Version 'Latest'
 
-    New-Object 'Rivet.Operations.AddViewOperation' $SchemaName,$Name,$Definition
+    $viewOp = New-Object 'Rivet.Operations.AddViewOperation' $SchemaName,$Name,$Definition
+
+    if( $Description )
+    {
+        $viewDescriptionOp = Add-Description -SchemaName $SchemaName -ViewName $Name -Description $Description 
+        $viewOp.ChildOperations.Add($viewDescriptionOp)
+    }
+
+    $viewOp | Write-Output
+    $viewOp.ChildOperations | Write-Output
 }

Rivet/Rivet.psd1

@@ -11,7 +11,7 @@
     RootModule = 'Rivet.psm1'
 
     # Version number of this module.
-    ModuleVersion = '0.17.0'
+    ModuleVersion = '0.18.0'
 
     # ID used to uniquely identify this module
     GUID = '8af34b47-259b-4630-a945-75d38c33b94d'

Test/Export-Migration.Tests.ps1

@@ -1236,3 +1236,77 @@ function Pop-Migration
     ThenMigration -HasContent 'Add-Index -TableName ''Table1'' -ColumnName ''AnotherID'''
 }
 
+Describe 'Export-Migration.when schema has an extended property' {
+    Init
+    GivenMigrationContent @'
+    function Push-Migration
+    {
+        Add-Schema 'snap'
+        Add-ExtendedProperty -Name 'MS_Description' -Value 'This is the MS Description for the schema snap' -SchemaName 'snap'
+        Add-Table -Schema 'snap' -Name 'SnapTable' -Column {
+            int 'ID' -NotNull
+        }
+    }
+    
+    function Pop-Migration
+    {
+        Remove-Table -Schema 'snap' -Name 'SnapTable'
+        Remove-Schema -Name 'snap'
+    }
+'@
+    
+    WhenExporting
+    ThenMigration -HasContent 'Add-Schema -Name ''snap'' -Owner ''dbo'' -Description ''This is the MS Description for the schema snap'''
+    ThenMigration -HasContent 'Add-Table -SchemaName ''snap'' -Name ''SnapTable'''
+}
+
+Describe 'Export-Migration.when view has an extended property' {
+    Init
+    GivenMigrationContent @'
+    function Push-Migration
+    {
+        Add-Schema 'crackle'
+        Add-View -SchemaName 'crackle' -Name 'CrackleView' -Definition 'as select 1 as one'
+        Add-ExtendedProperty -Name 'MS_Description' -SchemaName 'crackle' -ViewName 'CrackleView' -Value 'This is the MS Description for the view CrackleView'
+    }
+    
+    function Pop-Migration
+    {
+        Remove-View -SchemaName 'crackle' -Name 'CrackleView'
+        Remove-Schema 'crackle'
+    }
+'@
+    
+    WhenExporting
+    ThenMigration -HasContent 'Add-Schema -Name ''crackle'''
+    ThenMigration -HasContent 'Add-View -SchemaName ''crackle'' -Name ''CrackleView'''
+    ThenMigration -HasContent 'Add-View -SchemaName ''crackle'' -Name ''CrackleView'' -Description ''This is the MS Description for the view CrackleView'''
+}
+
+Describe 'Export-Migration.when view column has an extended property' {
+    Init
+    GivenMigrationContent @'
+    function Push-Migration
+    {
+        Add-Schema 'pop'
+        Add-Table -Schema 'pop' -Name 'PopTable' -Column {
+            int 'ID' -NotNull
+        }
+        Add-View -Name 'PopView' -SchemaName 'pop' -Definition 'as select * from PopTable'
+        Add-ExtendedProperty -Name 'MS_Description' -SchemaName 'pop' -ViewName 'PopView' -ColumnName 'ID' -Value 'This is the MS Description for column ID in the view PopView'
+    }
+    
+    function Pop-Migration
+    {
+        Remove-Table -SchemaName 'pop' -Name 'PopTable'
+        Remove-View -SchemaName 'pop' -Name 'PopView'
+        Remove-Schema 'pop'
+    }
+'@
+    
+    WhenExporting
+    ThenMigration -HasContent 'Add-Schema -Name ''pop'''
+    ThenMigration -HasContent 'Add-Table -SchemaName ''pop'' -Name ''PopTable'''
+    ThenMigration -HasContent 'Add-View -SchemaName ''pop'' -Name ''PopView'''
+    ThenMigration -HasContent 'Add-ExtendedProperty -SchemaName ''pop'' -ViewName ''PopView'' -ColumnName ''ID'' -Value  -Description ''This is the MS Description for column ID in the view PopView'''
+}