Documentation in the DevOps processes

dbForge Documenter for SQL Server can be directly involved in the Continuous Integration (CI) process via the PowerShell cmdlets that can help automate the documentation generation and make the workflow faster, more secure, and time-saving.

The guide covers the following topics:

• Installing dbForge DevOps Automation PowerShell for SQL Server
• Generating documentation on the fly based on the database connection
• Generating documentation from the existing .ddoc project file
• Including generated documentation in the NuGet * .nupkg file

To start using Documenter in the DevOps process, make sure that:

• dbForge DevOps Automation for SQL Server is installed on your computer.
• PowerShell version is 3.0 or higher.

Note

By default, PowerShell is installed on Windows 8, 8.1, and 10. For other versions, download PowerShell from the Microsoft official download center page.

To check the current version of PowerShell, open WindowsPowerShell ISE and execute the $PSVersionTable.PSVersion command. In the Major column, you can see the version currently installed on your computer.

After that, you can generate documentation in the following ways:

• On the fly based on the database connection
• From the existing .ddoc project file

As soon as the documentation has been generated, you can include it in the NuGet package along with database scripts.

Installing dbForge DevOps Automation PowerShell for SQL Server

dbForge DevOps Automation for SQL Server is supplied as part of dbForge SQL Tools (Professional version) and includes dbForge DevOps Automation PowerShell for SQL Server.

To install dbForge DevOps Automation PowerShell for SQL Server

1. Download the product from the Devart website.

2. Run the installer and follow the instructions in the Setup wizard.

After the installation was completed, the Devart.DbForge.DevOpsAutomation.SqlServer module with a set of cmdlets appears in Windows PowerShell ISE.

You can check the full list of requirements to run dbForge DevOps Automation on the Requirements and Compatibility page.

Generating documentation on the fly based on the database connection

When generating connection-based documentation on the fly, information about database objects is generated by default.

To generate documentation via PowerShell cmdlets

1. Run Windows PowerShell ISE on your computer.

2. In Windows PowerShell ISE, execute the PowerShell script to create the database documentation and specify the path to store the file with the generated documentation.

Note

To document your database, use the New-DevartDatabaseDocumentation PowerShell cmdlet.

# Variables
$serverName = "SQLEXPRESS15"
$databaseName = "AdventureWorks2019"

# Create database connection
Write-Host "Creating database connection..."
$connection = New-DevartSqlDatabaseConnection -Server $serverName
-Database $databaseName -WindowsAuthentication $true

# A file path to an output file
$outputFileName = "C:\GeneratedDocumentation\OutputFile\AdventureWorks2019_doc.pdf"

New-DevartDatabaseDocumentation -Connection $connection -Format Pdf -Output
$outputFileName

Parameters used in the script

Generating documentation from the existing .ddoc project file

Prior to generating the documentation with PowerShell cmdlets, you need to create a .ddoc project file. You can include or exclude individual database objects or groups of objects in/from the documentation, and set up documentation options. For more information about the documentation generation in the Documenter GUI, see Setting up the documentation.

To generate documentation via PowerShell cmdlets

1. Run Windows PowerShell ISE on your computer.

2. In Windows PowerShell ISE, execute the PowerShell script to generate the database documentation.

# A file path to a project file
$projectFile = "C:\GeneratedDocumentation\SourceFile\ProjectFile.ddoc"

# A file path to an output file
$outputFileName = "C:\GeneratedDocumentation\OutputFile\AdventureWorks2019_doc.pdf"

New-DevartDatabaseDocumentation -ProjectFile $projectFile -Format Pdf -Output
$outputFileName

Parameters used in the script

Including generated documentation in the NuGet * .nupkg file

You can include the generated documentation in the NuGet * .nupkg file or Zip package. To create the documentation, you need to use the New-DevartDatabaseDocumentation PowerShell cmdlets. To include the project file with the generated documentation in the NuGet * .nupkg file or Zip package, you need to use the Export-DevartDatabaseProject PowerShell cmdlets.

To include the generated documentation in the NuGet * .nupkg file, execute the following PowerShell script:

# A database connection string
$projectFile = "C:\GeneratedDocumentation\SourceFile\ProjectFile.ddoc"

# A file path to an output doc file
$outputFileName = "C:\GeneratedDocumentation\OutputFile\AdventureWorks2019_doc.pdf"

# A path to an output nuget file
$publishOutputFolder = "C:\NuGet\OutputFile\"

$migrationScriptsFolder = "C:\Migration\Scripts"

# Create a .ddoc file
New-DevartDatabaseDocumentation -ProjectFile $projectFile -Format Pdf -Output $outputFileName

# Create a nuget package which contains both a database script and a .ddoc file.
$project= New-DevartDatabaseProject -SourceScriptsFolder $migrationScriptsFolder
Set-DevartPackageInfo -Project $project -Id "Test.DevOpsAutomation.Database"
-Version 3.0.0 -Documentation $outputFileName
Export-DevartDatabaseProject -Project $project -Format NuGet -OutputDirectory
$publishOutputFolder -Overwrite

For more information about the Export-DevartDatabaseProject syntax and parameters, see Export-DevartDatabaseProject.

Download dbForge SQL documentation generator and try it absolutely free for 30 days!

Video tutorial

Watch the video tutorial to learn how to use dbForge Documenter in DevOps process:

• Previous
• Next