Skip to content

Commit c28f279

Browse files
dzsquareddzsquared
authored
Incorporate solution file changes (#34557)
1 parent affb820 commit c28f279

File tree

2 files changed

+143
-50
lines changed

2 files changed

+143
-50
lines changed

‎docs/tools/sql-database-projects/howto/convert-original-sql-project.md

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: "Create an SDK-style SQL project from an existing project."
44
author: dzsquared
55
ms.author: drskwier
66
ms.reviewer: maghan, randolphwest
7-
ms.date: 03/11/2025
7+
ms.date: 06/27/2025
88
ms.service: sql
99
ms.subservice: sql-database-projects
1010
ms.topic: how-to
@@ -311,6 +311,30 @@ When schema comparison is run, no results should be displayed. The lack of diffe
311311
> [!NOTE]
312312
> The comparison of `.dacpac` files through schema comparison doesn't validate pre/post-deployment scripts, refactorlog, or other project settings. It only validates the database model. Using the DacpacVerify command-line utility is the recommended way to validate that the two `.dacpac` files are equivalent.
313313
314+
## Step 6: Solution files
315+
316+
Your project file might be referenced in a solution file (`.sln`). If you have a solution file, you should update it to reference the new SDK-style project file.
317+
318+
### Optional: Create a new solution file
319+
320+
For a solution file that only contains the SQL project, it is more straightforward to remove the solution file and create a new solution file with the SDK-style project.
321+
322+
```bash
323+
dotnet new sln --name MySolution
324+
dotnet sln MySolution.sln add MyDatabaseProject\MyDatabaseProject.sqlproj
325+
```
326+
327+
### Optional: Edit the solution file
328+
329+
When a solution file contains multiple projects, you should update the solution file to reference the new SDK-style project file. You can edit the solution file in a text editor and change the project reference to the new SDK-style project file. The project reference in the solution file should look like this:
330+
331+
```xml
332+
Project("{PROJECT_TYPE_GUID}") = "MyDatabaseProject", "MyDatabaseProject\MyDatabaseProject.sqlproj", "{PROJECT_GUID}"
333+
EndProject
334+
```
335+
336+
The `PROJECT_TYPE_GUID` value for a Microsoft.Build.Sql project is `42EA0DBD-9CF1-443E-919E-BE9C484E4577`, and the `PROJECT_GUID` is a unique identifier for the project found in the project file `<ProjectGuid>` element. The `PROJECT_GUID` value is not required to be changed and can remain the same as in the original project file. The `PROJECT_TYPE_GUID` value is required to be changed to the Microsoft.Build.Sql project type GUID.
337+
314338
## Related content
315339

316340
- [What are SQL database projects?](../sql-database-projects.md)

‎docs/tools/sqlpackage/sqlpackage-pipelines.md

Lines changed: 118 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ title: SqlPackage in Development Pipelines
33
description: Learn how to troubleshoot database development pipelines with SqlPackage.
44
author: dzsquared
55
ms.author: drskwier
6-
ms.reviewer: maghan
7-
ms.date: 04/15/2025
6+
ms.reviewer: maghan, randolphwest
7+
ms.date: 06/27/2025
88
ms.service: sql
99
ms.subservice: tools-other
1010
ms.topic: conceptual
@@ -16,35 +16,56 @@ ms.collection:
1616

1717
**SqlPackage** is a command-line utility that automates several database development tasks and can be incorporated into CI/CD pipelines.
1818

19+
> [!NOTE]
20+
> Utilizing a [standalone installation of SqlPackage](sqlpackage-download.md) for pipeline automation is recommended over using the SqlPackage executables bundled with other applications, including SQL Server Management Studio or Visual Studio. The standalone installation of SqlPackage is updated more frequently and isn't tied to the release cadence of other applications.
1921
20-
## Virtual environments
22+
If SqlPackage is installed as a global dotnet tool (recommended), you can invoke it in the pipeline with simply `sqlpackage` from any directory. If SqlPackage is installed as a standalone executable, you must specify the full path to the executable in the pipeline. On Windows, the standalone install of SqlPackage is available on the path `C:\Program Files\Microsoft SQL Server\170\DAC\bin` (DacFx.msi). In both Windows and Linux environments, if you download the self-contained .zip SqlPackage for .NET, you can extract the executable to a location of your choosing.
2123

22-
> [!NOTE]
23-
> Utilizing a standalone installation of SqlPackage for pipeline automation is recommended over using the SqlPackage executables bundled with other applications, including SQL Server Management Studio or Visual Studio. The standalone installation of SqlPackage is updated more frequently and is not tied to the release cadence of other applications.
24+
## Managed virtual environments
2425

25-
On Windows, the standalone install of SqlPackage is available on the path `C:\Program Files\Microsoft SQL Server\170\DAC\bin` (DacFx.msi) or `%USERPROFILE%\.dotnet\tools` (dotnet tool). On Linux, the standalone install of SqlPackage is available on the path `~/.dotnet/tools` (dotnet tool). In both Windows and Linux environments, if you download the self-contained .zip SqlPackage for .NET Core, you can extract the executable to a location of your choosing.
26+
The virtual environments used for GitHub Actions hosted runners and Azure Pipelines virtual machine images are managed in the [runner-images](https://github.com/actions/runner-images) GitHub repository. SqlPackage is included in several environments including `windows-latest` and `ubuntu-22.04` but is no longer included by default in `ubuntu-24.04` and `ubuntu-latest`. Updates to the images in [runner-images](https://github.com/actions/runner-images) are made within a few weeks of each SqlPackage release.
2627

27-
### Managed virtual environments
28+
In a managed virtual environment, you would install SqlPackage at runtime in the pipeline. The installation is performed as a separate step in either Azure Pipelines and GitHub Actions and adds a short delay to each pipeline run while the installation occurs. To install SqlPackage at runtime, add a step to the pipeline that uses the dotnet CLI to install SqlPackage as a global tool. This step should be run before any SqlPackage actions in the pipeline.
2829

29-
The virtual environments used for GitHub Actions hosted runners and Azure Pipelines virtual machine images are managed in the [runner-images](https://github.com/actions/runner-images) GitHub repository. SqlPackage is included in several environments including `windows-latest` and `ubuntu-22.04` but is no longer included by default in `ubuntu-24.04` and `ubuntu-latest`. Updates to the images in [runner-images](https://github.com/actions/runner-images) are made within a few weeks of each SqlPackage release.
30+
```bash
31+
dotnet tool install --global Microsoft.SqlPackage
32+
```
3033

31-
### Self-hosted virtual environments
34+
You might need to perform a .NET setup step in the pipeline before installing SqlPackage, indicated by an error message stating that .NET can't be found. Use an integrated action to configure it such as the [UseDotNet](/azure/devops/pipelines/tasks/reference/use-dotnet-v2) task in Azure Pipelines or the [setup-dotnet](https://github.com/actions/setup-dotnet) action in GitHub Actions.
3235

33-
In a self-hosted virtual environment such as a self-hosted Azure DevOps agent, [update the application](sqlpackage-download.md) regularly to maintain the environment with the latest version.
36+
Optionally, you can specify a version of SqlPackage to install by appending `--version <version>` to the install command or you can use the `--prerelease` flag to install a preview versions.
3437

35-
## Tracking deployments
38+
### Example: Steps to install SqlPackage in Azure DevOps Pipelines
3639

37-
You can capture some files related to SqlPackage to reproduce pipelines and improve deployment tracking. The implementation and use cases depend on your specific architecture and automation environment.
40+
In Azure DevOps Pipelines, you can use the [UseDotNet](/azure/devops/pipelines/tasks/reference/use-dotnet-v2) task to install the .NET SDK and then install SqlPackage as a global tool. If you're using a Windows agent provided by Microsoft, SqlPackage is already installed in `C:\Program Files\Microsoft SQL Server\170\DAC\bin`. If you're using a self-hosted agent, you can also install SqlPackage on the host environment and skip this step in the pipeline.
3841

39-
- **Dacpac file**
40-
- **Diagnostic file output from any action:** Use the `/DiagnosticsFile:` parameter on any SqlPackage action, see [Get SqlPackage diagnostics in a pipeline agent](#get-sqlpackage-diagnostics-in-a-pipeline-agent)
41-
- **Output from script action prior to publish action:** Use the [Script](sqlpackage-script.md) SqlPackage action before invoking a publish action
42+
```yaml
43+
- task: UseDotNet@2
44+
inputs:
45+
packageType: 'sdk'
46+
version: '8.x'
47+
- script: dotnet tool install --global Microsoft.SqlPackage --version <version>
48+
displayName: 'Install specific version of SqlPackage'
49+
```
4250
43-
## Other SqlPackage examples
51+
### Example: Steps to install SqlPackage in GitHub Actions
4452
45-
### Checking the SqlPackage version
53+
In GitHub Actions, you can use the [setup-dotnet](https://github.com/actions/setup-dotnet) action to install the .NET SDK and then install SqlPackage as a global tool. If you're using a Windows runner provided by GitHub, SqlPackage is already installed in `C:\Program Files\Microsoft SQL Server\170\DAC\bin`. If you're using a self-hosted runner, you can also install SqlPackage on the host environment and skip this step in the workflow.
4654

47-
During troubleshooting efforts, it's important to know the SqlPackage version is 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 in this article based on the Microsoft and GitHub managed environments, self-hosted environments may have different installation paths for the working directory.
55+
```yaml
56+
- name: Setup .NET
57+
uses: actions/setup-dotnet@v4
58+
with:
59+
dotnet-version: '8.x'
60+
- name: Install SqlPackage
61+
run: dotnet tool install --global Microsoft.SqlPackage --version <version>
62+
```
63+
64+
<a id="checking-the-sqlpackage-version"></a>
65+
66+
### Check the SqlPackage version
67+
68+
During troubleshooting efforts, it's important to know the SqlPackage version is 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 in this article based on the Azure DevOps and GitHub managed environments, self-hosted environments might have different installation paths for the working directory.
4869

4970
#### Azure Pipelines
5071

@@ -58,7 +79,7 @@ In an Azure Pipeline, the [script](/azure/devops/pipelines/yaml-schema/steps-scr
5879

5980
#### GitHub Actions
6081

61-
In a GitHub Action workflow, the [run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) keyword returns the SqlPackage version number.
82+
In a GitHub Action workflow, the [run](https://docs.github.com/actions/reference/workflow-syntax-for-github-actions) keyword returns the SqlPackage version number.
6283

6384
```yaml
6485
- name: get sqlpackage version
@@ -68,12 +89,78 @@ In a GitHub Action workflow, the [run](https://docs.github.com/en/actions/using-
6889

6990
:::image type="content" source="media/sqlpackage-pipelines-github-action.png" alt-text="GitHub action output displaying build number 15.0.4897.1":::
7091

71-
### Get SqlPackage diagnostics in a pipeline agent
92+
### Update SqlPackage on the pipeline agent
93+
94+
In some scenarios, the current version of SqlPackage installed in the pipeline environment might be insufficient. If the environment can't be directly modified, an extra step can be used to install a newer version of SqlPackage during the pipeline run. It's important to run the install step before running any DacPac or BacPac operations in the pipeline. This task can be combined with a step to [check the version](#checking-the-sqlpackage-version) to ensure that the upgrade completed as expected.
95+
96+
#### Azure Pipelines, Windows-based agent
97+
98+
When the [PowerShell](/azure/devops/pipelines/tasks/utility/powershell) task is used in an Azure Pipeline, a step can be added to an Azure Pipeline that downloads the desired DacFx installer and installs it silently.
99+
100+
```yaml
101+
- task: PowerShell@2
102+
displayName: 'upgrade sqlpackage'
103+
inputs:
104+
targetType: 'inline'
105+
script: |
106+
# use evergreen or specific dacfx msi link below
107+
wget -O DacFramework.msi "https://aka.ms/dacfx-msi"
108+
msiexec.exe /i "DacFramework.msi" /qn
109+
```
110+
111+
#### GitHub Actions, Linux-based runner
112+
113+
In a GitHub Action workflow, you can use the [run](https://docs.github.com/actions/reference/workflow-syntax-for-github-actions) keyword to execute the `dotnet tool` commands to install, uninstall, or update SqlPackage. The following example shows how to update SqlPackage to the latest preview version:
114+
115+
```yaml
116+
- name: Update SqlPackage
117+
run: dotnet tool update --global Microsoft.SqlPackage --prerelease
118+
```
119+
120+
## Self-hosted virtual environments
121+
122+
In a self-hosted virtual environment such as a self-hosted Azure DevOps agent or GitHub Actions runner, you can install SqlPackage on the host environment or install SqlPackage at runtime as described in [managed virtual environments](#managed-virtual-environments). If you install SqlPackage on the host environment, pipelines that run on that host don't need to install SqlPackage at runtime, which can speed up the pipeline runs. When SqlPackage is installed on the host, you should [update SqlPackage](sqlpackage-download.md) regularly to maintain the environment with the latest version.
123+
124+
[Azure Container Apps jobs](/azure/container-apps/tutorial-ci-cd-runners-jobs) can be used to deploy self-hosted runners in a container that is deployed as needed for each workflow invocation. With Container Apps jobs, you control the environment as defined in the Dockerfile and install SqlPackage and other tools as needed. The self-hosted runner can be configured to run on a specific version of SqlPackage by including the installation step in the container image. For example, the [tutorial](https://github.com/Azure-Samples/container-apps-ci-cd-runner-tutorial/tree/main) includes a Dockerfile that installs `curl` and `jq`.
125+
126+
We can modify this example to produce a container image that installs .NET 8.0 and SqlPackage:
127+
128+
```dockerfile
129+
FROM ghcr.io/actions/actions-runner:2.323.0
130+
131+
USER root
132+
133+
# install dotnet sdk and sqlpackage
134+
RUN apt-get update && apt-get install -y dotnet-sdk-8.0 && \
135+
dotnet tool install --tool-path /usr/local/bin/ Microsoft.SqlPackage
136+
137+
COPY entrypoint.sh ./entrypoint.sh
138+
RUN chmod +x ./entrypoint.sh
139+
140+
USER runner
141+
142+
ENTRYPOINT ["./entrypoint.sh"]
143+
```
144+
145+
<a id="tracking-deployments"></a>
146+
147+
## Track deployments
148+
149+
You can capture some files related to SqlPackage to reproduce pipelines and improve deployment tracking. The implementation and use cases depend on your specific architecture and automation environment.
150+
151+
- **Dacpac file**
152+
153+
- **Diagnostic file output from any action:** Use the `/DiagnosticsFile:` parameter on any SqlPackage action. For more information, see [Get SqlPackage diagnostics in a pipeline agent](#get-sqlpackage-diagnostics-in-a-pipeline-agent)
154+
155+
- **Output from script action prior to publish action:** Use the [Script](sqlpackage-script.md) SqlPackage action before invoking a publish action
156+
157+
## Get SqlPackage diagnostics in a pipeline agent
72158

73159
Diagnostic information from SqlPackage is available in the command line through the parameter `/DiagnosticsFile`, which can be used in virtual environments such as Azure Pipelines and GitHub Actions. The diagnostic information is written to a file in the working directory. The file name is dictated by the `/DiagnosticsFile` parameter.
74160

75-
#### Azure Pipelines
76-
Adding the `/DiagnosticsFile` parameter to the "Additional SqlPackage Arguments" field in the Azure Pipeline SqlAzureDacpacDeployment configuration causes the SqlPackage diagnostic information to be written to the file specified. Following the SqlAzureDacpacDeployment task, the diagnostic file can be made available outside of the virtual environment by publishing a pipeline artifact as seen in the following example.
161+
### Azure Pipelines
162+
163+
Adding the `/DiagnosticsFile` parameter to the "Additional SqlPackage Arguments" field in the Azure Pipeline SqlAzureDacpacDeployment configuration causes the SqlPackage diagnostic information to be written to the file specified. Following the SqlAzureDacpacDeployment task, the diagnostic file is available outside of the virtual environment by publishing a pipeline artifact as seen in the following example.
77164

78165
```yaml
79166
- task: SqlAzureDacpacDeployment@1
@@ -97,22 +184,22 @@ Adding the `/DiagnosticsFile` parameter to the "Additional SqlPackage Arguments"
97184
publishLocation: 'pipeline'
98185
```
99186

100-
After the pipeline run, the diagnostic file can be downloaded from the run summary page under "Published Artifacts".
187+
After the pipeline run, the diagnostic file can be downloaded from the run summary page under "Published Artifacts."
101188

102-
#### GitHub Actions
189+
### GitHub Actions
103190

104191
Adding the `/DiagnosticsFile` parameter to the "arguments" field in the GitHub Action sql-action configuration causes the SqlPackage diagnostic information to be written to the file specified. Following the sql-action task, the diagnostic file can be made available outside of the virtual environment by publishing an artifact as seen in the following example.
105192

106193
```yaml
107194
- name: Azure SQL Deploy
108195
uses: Azure/sql-action@v2
109196
with:
110-
# The connection string, including authentication information, for the Azure SQL Server database.
111-
connection-string: ${{ secrets.AZURE_SQL_CONNECTION_STRING }}
112-
# Path to DACPAC file to deploy
197+
# The connection string, including authentication information, for the Azure SQL Server database.
198+
connection-string: ${{ secrets.AZURE_SQL_CONNECTION_STRING }}
199+
# Path to DACPAC file to deploy
113200
path: .\DatabaseProjectAdventureWorksLT\bin\Release\DatabaseProjectAdventureWorksLT.dacpac
114201
action: publish
115-
# additional SqlPackage arguments
202+
# additional SqlPackage arguments
116203
arguments: /DiagnosticsFile:DatabaseProjectAdventureWorksLT/DiagnosticLog.log
117204
118205
- uses: actions/upload-artifact@v2
@@ -121,25 +208,7 @@ Adding the `/DiagnosticsFile` parameter to the "arguments" field in the GitHub A
121208
path: 'DatabaseProjectAdventureWorksLT/DiagnosticLog.log'
122209
```
123210

124-
### Update SqlPackage on the pipeline agent
125-
126-
In some scenarios, the current version of SqlPackage installed in the pipeline environment may be insufficient. If the environment can't be directly modified, an extra step can be used to install a newer version of SqlPackage during the pipeline run. It's important to run the install step before running any DacPac or BacPac operations in the pipeline. This task can be combined with a step to [check the version](#checking-the-sqlpackage-version) to ensure that the upgrade completed as expected.
127-
128-
#### Azure Pipelines
129-
When the [PowerShell](/azure/devops/pipelines/tasks/utility/powershell) task is used in an Azure Pipeline, a step can be added to an Azure Pipeline that downloads the desired DacFx installer and installs it silently.
130-
131-
```yaml
132-
- task: PowerShell@2
133-
displayName: 'upgrade sqlpackage'
134-
inputs:
135-
targetType: 'inline'
136-
script: |
137-
# use evergreen or specific dacfx msi link below
138-
wget -O DacFramework.msi "https://aka.ms/dacfx-msi"
139-
msiexec.exe /i "DacFramework.msi" /qn
140-
```
141-
142-
143-
## Next steps
211+
## Related content
144212

145-
- Learn more about [SqlPackage](sqlpackage.md)
213+
- [SqlPackage](sqlpackage.md)
214+
- [Tutorial: Create and deploy a SQL project](../sql-database-projects/tutorials/create-deploy-sql-project.md)

0 commit comments

Comments
 (0)