adding info on troubleshooting pipelines for sqlpackage

dzsquared · dzsquared · commit f8bc2dcd019f · 2020-11-04T19:05:22.000-08:00
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -9740,6 +9740,8 @@
       href: tools/release-notes-sqlpackage.md
     - name: sqlpackage ref
       href: tools/sqlpackage.md
+    - name: SqlPackage in development pipelines
+      href: tools/sqlpackage.md
   - name: SQL Server Profiler
     href: tools/sql-server-profiler/sql-server-profiler.md
     items:
diff --git a/docs/tools/media/sqlpackage-pipelines-githubaction.png b/docs/tools/media/sqlpackage-pipelines-githubaction.png
diff --git a/docs/tools/sqlpackage-download.md b/docs/tools/sqlpackage-download.md
@@ -6,9 +6,9 @@ ms.prod: sql
 ms.prod_service: sql-tools
 ms.technology: tools-other
 ms.topic: conceptual
-author: "pensivebrian"
-ms.author: "broneill"
-ms.reviewer: "drskwier; sstein"
+author: "dzsquared"
+ms.author: "drskwier"
+ms.reviewer: "maghan; sstein"
 ms.date: 10/02/2020
 ---
 
diff --git a/docs/tools/sqlpackage-pipelines.md b/docs/tools/sqlpackage-pipelines.md
@@ -0,0 +1,53 @@
+---
+title: SqlPackage in development pipelines
+description: Learn how to troubleshoot database development pipelines with SqlPackage.exe by checking the installed build number.
+ms.prod: sql
+ms.prod_service: sql-tools
+ms.technology: tools-other
+ms.topic: conceptual
+ms.assetid: 198198e2-7cf4-4a21-bda4-51b36cb4284b
+author: "dzsquared"
+ms.author: "drskwier"
+ms.reviewer: "maghan; sstein"
+ms.date: 11/4/2020
+---
+
+# SqlPackage in Development Pipelines
+
+**SqlPackage.exe** is a command-line utility that automates several database development tasks and can be incorporated into CI/CD pipelines.
+
+## Managed virtual environments for Azure Pipelines and GitHub Actions
+
+The virtual environments used for GitHub Actions hosted runners and Azure Pipelines VM images are managed in the [virtual-environments](https://github.com/actions/virtual-environments) GitHub repository.  SqlPackage is included in the `windows-latest` environment and updates to the images are made within a few weeks of each SqlPackage release.
+
+## Checking the SqlPackage version in a virtual environment
+
+During troubleshooting efforts, it is important to know the SqlPackage version in use.  Capturing this information can be done by adding a step to the pipeline to run SqlPackage with the `/version` parameter.  Examples are given below based on the Microsoft and GitHub managed environments, self-hosted environments may have different installation paths for the working directory.
+
+### Azure Pipelines
+
+By leveraging the [script](https://docs.microsoft.com/azure/devops/pipelines/yaml-schema#script) keyword in an Azure Pipeline, a step can be added to an Azure Pipeline that outputs the SqlPackage version number.
+
+```yaml
+- script: sqlpackage.exe /version
+  workingDirectory: C:\Program Files\Microsoft SQL Server\150\DAC\bin\
+  displayName: 'get sqlpackage version'
+```
+
+### GitHub Actions
+
+By leveraging the [run](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions) keyword in a GitHub Action workflow, a step can be added to a GitHub Action that outputs the SqlPackage version number.
+
+```yaml
+- name: get sqlpackage version
+  working-directory: C:\Program Files\Microsoft SQL Server\150\DAC\bin\
+  run: ./sqlpackage.exe /version
+```
+
+:::image type="content" source="media/sqlpackage-pipelines-githubaction.png" alt-text="GitHub action output displaying build number 15.0.4897.1":::
+
+## Next Steps
+
+- Learn more about [sqlpackage](sqlpackage.md)
+
+[Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839)
diff --git a/docs/tools/sqlpackage.md b/docs/tools/sqlpackage.md
@@ -6,16 +6,18 @@ ms.prod_service: sql-tools
 ms.technology: tools-other
 ms.topic: conceptual
 ms.assetid: 198198e2-7cf4-4a21-bda4-51b36cb4284b
-author: "pensivebrian"
-ms.author: "broneill"
-ms.reviewer: "drswkier; sstein"
-ms.date: 09/29/2020
+author: "dzsquared"
+ms.author: "drskwier"
+ms.reviewer: "maghan; sstein"
+ms.date: 11/4/2020
 ---
 
 # SqlPackage.exe
 
 **SqlPackage.exe** is a command-line utility that automates the following database development tasks:  
   
+- [Version](#version): Returns the build number of the SqlPackage application.  Added in version 18.6.
+
 - [Extract](#extract-parameters-and-properties): Creates a database snapshot (.dacpac) file from a live SQL Server or Azure SQL Database.  
   
 - [Publish](#publish-parameters-properties-and-sqlcmd-variables): Incrementally updates a database schema to match the schema of a source .dacpac file. If the database does not exist on the server, the publish operation creates it. Otherwise, an existing database is updated.  
@@ -64,7 +66,10 @@ Create a SQL script that generates the differences of two .dacpac files:
 sqlpackage.exe /Action:Script /SourceFile:"C:\sqlpackageoutput\output_current_version.dacpac" /TargetFile:"C:\sqlpackageoutput\output_target.dacpac" /TargetDatabaseName:"Contoso.Database" /OutputPath:"C:\sqlpackageoutput\output.sql"
  ```
 
-Displays the sqlpackage version:
+
+## Version
+
+Displays the sqlpackage version as a build number.  Can be used in interactive prompts as well as in [automated pipelines](sqlpackage-pipelines.md).
 
 ```
 sqlpackage.exe /Version
