From 7af66ef539811929c6b26fbe3655953ad012bde0 Mon Sep 17 00:00:00 2001 From: Mark Ghanayem <22989000+markingmyname@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:15:23 -0600 Subject: [PATCH] [sqlpackage] Update download sqlpackage article (UUF) --- docs/tools/sqlpackage/sqlpackage-download.md | 106 ++++++++++++------- 1 file changed, 67 insertions(+), 39 deletions(-) diff --git a/docs/tools/sqlpackage/sqlpackage-download.md b/docs/tools/sqlpackage/sqlpackage-download.md index d27c7c72733..e665ce335d2 100644 --- a/docs/tools/sqlpackage/sqlpackage-download.md +++ b/docs/tools/sqlpackage/sqlpackage-download.md @@ -1,14 +1,17 @@ --- -title: Download and install SqlPackage +title: Download and Install SqlPackage description: "Download and Install SqlPackage for Windows, macOS, or Linux" author: "dzsquared" ms.author: "drskwier" -ms.reviewer: "maghan" -ms.date: 11/21/2024 +ms.reviewer: maghan +ms.date: 12/23/2024 ms.service: sql ms.subservice: tools-other ms.topic: conceptual -ms.custom: tools|sos, intro-installation, linux-related-content +ms.custom: + - tools|sos + - intro-installation + - linux-related-content --- # Download and install SqlPackage @@ -21,12 +24,12 @@ SqlPackage runs on Windows, macOS, and Linux, and is available to install throug SqlPackage is developed and released for both .NET 8 and .NET Framework. Installing the .NET 8 SqlPackage version is recommended via the [convenient `dotnet tool` method](#installation-cross-platform), which is cross-platform and easy to update, or via the [portable self-contained .zip download](#installation-file-download-alternative). The .NET 8 SqlPackage releases benefit from the continual advances to the performance and scalability of .NET as part of the [focus on for modern applications](/dotnet/core/introduction#net-ecosystem), which contrasts to the maintenance support of .NET Framework for Windows. The .NET Framework version is only available as a [.msi Windows installer](#windows-net-framework). -> [!NOTE] +> [!NOTE] > Previously, SqlPackage had a distinct version number (19) and build number (160.x). Beginning with version 161, the version number of SqlPackage matches the DacFx version number it is associated with (eg 162.0.52). ## Installation, cross-platform -Installing SqlPackage as a [dotnet tool](/dotnet/core/tools/global-tools) requires the [.NET SDK](https://dotnet.microsoft.com/download/dotnet/8.0) to be installed on your machine. Installing SqlPackage as a global tool makes it available on your path as `sqlpackage` and is the recommended method to install SqlPackage for Windows, macOS, and Linux. SqlPackage is available as a dotnet tool for .NET 6 and .NET 8. +Installing SqlPackage as a [dotnet tool](/dotnet/core/tools/global-tools) requires the [.NET SDK](https://dotnet.microsoft.com/download/dotnet/8.0) to be installed on your machine. Installing SqlPackage as a global tool makes it available on your path as `sqlpackage` and is the recommended method to install SqlPackage for Windows, macOS, and Linux. SqlPackage is available as a dotnet tool for .NET 8 and later. To install SqlPackage as a global .NET tool, run the following command: @@ -36,20 +39,48 @@ To install SqlPackage as a global .NET tool, run the following command: More information on the options available with the `dotnet tool install` command can be found in the [dotnet tool install documentation](/dotnet/core/tools/dotnet-tool-install). - To update SqlPackage to the latest version, run the following command: ```bash dotnet tool update -g microsoft.sqlpackage ``` - To uninstall SqlPackage, run the following command: ```bash dotnet tool uninstall -g microsoft.sqlpackage ``` +### Troubleshoot installation + +If you encounter issues during installation, follow these steps: + +1. **Ensure .NET SDK is installed**: Verify that the .NET SDK is installed on your machine by running the following command: + + ```bash + dotnet --list-sdks + ``` + + If the .NET SDK isn't listed, download and install it from the [.NET SDK download page](https://dotnet.microsoft.com/download/dotnet/8.0). + +2. **Verify NuGet source configuration**: Ensure that `nuget.org` is a configured NuGet source for dotnet. List the configured NuGet sources by running: + + ```bash + dotnet nuget list source + ``` + + If `nuget.org` isn't listed, add it as a NuGet source using the following command: + + ```bash + dotnet nuget add source https://api.nuget.org/v3/index.json + ``` + +3. **Retry installation**: After verifying the .NET SDK installation and NuGet source configuration, retry installing SqlPackage using the appropriate command: + + ```bash + dotnet tool install -g microsoft.sqlpackage + ``` + ### Preview releases Preview releases of SqlPackage are available with the dotnet tool feed. To access preview releases, use the `--prerelease` option with the `dotnet tool` command. For example, to install the latest preview release, run the following command: @@ -66,37 +97,34 @@ To update SqlPackage to the latest preview version, run the following command: A list of preview releases is available on the [dotnet tool feed for SqlPackage](https://www.nuget.org/packages/microsoft.sqlpackage/). - ## Installation, file download (alternative) SqlPackage is also prepared as a self-contained download for Windows, macOS, and Linux. No .NET install is required, however, the dependencies included in this .zip download are updated more frequently in the [dotnet tool option for SqlPackage](#installation-cross-platform). The following links are for the latest version of SqlPackage: -|Platform|Download| -|:---|:---| -|Windows .NET 8 |[.zip file](https://go.microsoft.com/fwlink/?linkid=2297835)| -|Windows|[.msi file](https://go.microsoft.com/fwlink/?linkid=2297931)| -|macOS .NET 8 |[.zip file](https://go.microsoft.com/fwlink/?linkid=2297647)| -|Linux .NET 8 |[.zip file](https://go.microsoft.com/fwlink/?linkid=2297646)| - - +| Platform | Download | +| :--- | :--- | +| Windows .NET 8 | [.zip file](https://go.microsoft.com/fwlink/?linkid=2297835) | +| Windows | [.msi file](https://go.microsoft.com/fwlink/?linkid=2297931) | +| macOS .NET 8 | [.zip file](https://go.microsoft.com/fwlink/?linkid=2297647) | +| Linux .NET 8 | [.zip file](https://go.microsoft.com/fwlink/?linkid=2297646) | ### Linux 1. Download [SqlPackage for Linux](https://aka.ms/sqlpackage-linux) -2. Extract the file and launch SqlPackage, open a new Terminal window and type the following commands: +1. Extract the file and launch SqlPackage, open a new Terminal window and type the following commands: ```bash cd ~ mkdir sqlpackage - unzip ~/Downloads/sqlpackage-linux-.zip -d ~/sqlpackage + unzip ~/Downloads/sqlpackage-linux-.zip -d ~/sqlpackage echo "export PATH=\"\$PATH:$HOME/sqlpackage\"" >> ~/.bashrc chmod a+x ~/sqlpackage/sqlpackage source ~/.bashrc sqlpackage ``` - > [!NOTE] - > You may have missing dependencies. Use the following commands to install these dependencies depending on your version of Linux: + > [!NOTE] + > You might have missing dependencies. Use the following commands to install these dependencies depending on your version of Linux: **Debian:** @@ -120,7 +148,7 @@ SqlPackage is also prepared as a self-contained download for Windows, macOS, and ### macOS 1. Download [SqlPackage for macOS](https://aka.ms/sqlpackage-macos) -2. Extract the file and launch SqlPackage, open a new Terminal window and type the following commands: +1. Extract the file and launch SqlPackage, open a new Terminal window and type the following commands: ```bash mkdir sqlpackage @@ -131,15 +159,17 @@ SqlPackage is also prepared as a self-contained download for Windows, macOS, and sqlpackage ``` - > [!NOTE] - > Security settings may require modification to run SqlPackage on macOS. Use the following commands to interact with Gatekeeper from the command line. + > [!NOTE] + > Security settings might require modification to run SqlPackage on macOS. Use the following commands to interact with Gatekeeper from the command line. **Before executing SqlPackage:** + ```bash sudo spctl --master-disable ``` **After executing SqlPackage:** + ```bash sudo spctl --master-enable ``` @@ -147,8 +177,8 @@ SqlPackage is also prepared as a self-contained download for Windows, macOS, and ### Windows (.NET 8) 1. Download [SqlPackage for Windows](https://aka.ms/sqlpackage-windows) -2. Extract the file by right-clicking on the file in Windows Explorer, and selecting 'Extract All...', and select the target directory -3. Open a new Terminal window and cd to the location where SqlPackage was extracted: +1. Extract the file by right-clicking on the file in Windows Explorer, and selecting 'Extract All...', and select the target directory +1. Open a new Terminal window and cd to the location where SqlPackage was extracted: ```cmd > sqlpackage @@ -156,10 +186,10 @@ SqlPackage is also prepared as a self-contained download for Windows, macOS, and ### Windows (.NET Framework) -This release of SqlPackage includes a standard Windows installer experience, and a .zip: +This release of SqlPackage includes a standard Windows installer experience, and a .zip: 1. Download and run the [DacFramework.msi installer for Windows](https://aka.ms/dacfx-msi) -2. Open a new Command Prompt window, and run SqlPackage +1. Open a new Command Prompt window, and run SqlPackage - SqlPackage is installed to the ```C:\Program Files\Microsoft SQL Server\160\DAC\bin``` folder ### Uninstall SqlPackage @@ -171,6 +201,7 @@ If you installed SqlPackage with a .zip or other archive, then delete the files. ### Automated environments Evergreen links are available for downloading the latest Sqlpackage versions: + - Linux ([https://aka.ms/sqlpackage-linux](https://aka.ms/sqlpackage-linux)) - macOS ([https://aka.ms/sqlpackage-macos](https://aka.ms/sqlpackage-macos)) - Windows ([https://aka.ms/sqlpackage-windows](https://aka.ms/sqlpackage-windows)) @@ -186,10 +217,9 @@ Adding the NuGet package to a .NET project is accomplished via the .NET CLI with dotnet add package Microsoft.SqlServer.DacFx ``` -> [!NOTE] +> [!NOTE] > Additional NuGet packages were published under the DacFx name, "Microsoft.SqlServer.DacFx.x64" and "Microsoft.SqlServer.DacFx.x86". Support for both platforms is covered under the "Microsoft.SqlServer.DacFx" package. New references should be made to this package, not the x64 or x86 variants. - ## Supported Operating Systems SqlPackage runs on Windows, macOS, and Linux and is built using .NET 8. The [.NET 8 OS requirements](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md) are minimum requirements for SqlPackage, which has extra requirements due to its dependencies. @@ -228,13 +258,11 @@ SqlPackage .NET 8 macOS: SqlPackage .NET 8 Linux: [Chinese (Simplified)](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x804) | [Chinese (Traditional)](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x404) | [English (United States)](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x409) | [French](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x40c) | [German](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x407) | [Italian](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x410) | [Japanese](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x411) | [Korean](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x412) | [Portuguese (Brazil)](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x416) | [Russian](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x419) | [Spanish](https://go.microsoft.com/fwlink/?linkid=2297646&clcid=0x40a) +## Related content -## Next Steps - -- Learn more about [SqlPackage](sqlpackage.md) -- Learn more about [SqlPackage in CI/CD pipelines](sqlpackage-pipelines.md) -- Learn more about [troubleshooting issues with SqlPackage](troubleshooting-issues-and-performance-with-sqlpackage.md) -- Learn more about [SQL projects](../sql-database-projects/sql-database-projects.md) -- Share feedback on SqlPackage in the [DacFx GitHub repository](https://github.com/microsoft/DacFx) - -[Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839) +- [SqlPackage](sqlpackage.md) +- [SqlPackage in CI/CD pipelines](sqlpackage-pipelines.md) +- [troubleshooting issues with SqlPackage](troubleshooting-issues-and-performance-with-sqlpackage.md) +- [SQL projects](../sql-database-projects/sql-database-projects.md) +- [DacFx GitHub repository](https://github.com/microsoft/DacFx) +- [Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839)