Merge pull request #19265 from dzsquared/sqlpackage-exampleIE

adding IE troubleshooting article

Author: v-albemi

docs/toc.yml

@@ -9804,6 +9804,8 @@ items:
       href: tools/sqlpackage/sqlpackage-pipelines.md
     - name: SqlPackage for Azure Synapse Analytics
       href: tools/sqlpackage/sqlpackage-for-azure-synapse-analytics.md
+    - name: Troubleshooting Import/Export
+      href: tools/sqlpackage/troubleshooting-import-export-sqlpackage.md
   - name: SQL Server Profiler
     href: tools/sql-server-profiler/sql-server-profiler.md
     items:

docs/tools/sqlpackage/sqlpackage-import.md

@@ -55,15 +55,14 @@ SqlPackage {parameters}{properties}{SQLCMD Variables}
 |**/p:**|DatabaseLockTimeout=(INT32 '60')| Specifies the database lock timeout in seconds when executing queries against SQLServer. Use -1 to wait indefinitely.|
 |**/p:**|DatabaseMaximumSize=(INT32)|Defines the maximum size in GB of an Azure SQL Database.|
 |**/p:**|DatabaseServiceObjective=(STRING)|Defines the performance level of an Azure SQL Database such as"P0" or "S1".|
-|**/p:**|DisableIndexesForDataPhase=(BOOLEAN TRUE)|Disable indexes before importing data into SQL Server.|
+|**/p:**|DisableIndexesForDataPhase=(BOOLEAN TRUE)|When true (default), disables indexes before importing data into SQL Server. When false, indexes are not rebuilt. |
 |**/p:**|ImportContributorArguments=(STRING)|Specifies deployment contributor arguments for the deployment contributors. This should be a semi-colon delimited list of values.|
 |**/p:**|ImportContributors=(STRING)|Specifies the deployment contributors, which should run when the bacpac is imported. This should be a semi-colon delimited list of fully qualified build contributor names or IDs.|
 |**/p:**|ImportContributorPaths=(STRING)|Specifies paths to load additional deployment contributors. This should be a semi-colon delimited list of values. |
 |**/p:**|LongRunningCommandTimeout=(INT32)| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
-|**/p:**|RebuildIndexesOfflineForDataPhase=(BOOLEAN FALSE)|Rebuild indexes offline after importing data into SQL Server.|
+|**/p:**|RebuildIndexesOfflineForDataPhase=(BOOLEAN FALSE)|When true, rebuilds indexes offline after importing data into SQL Server.|
 |**/p:**|Storage=({File|Memory})|Specifies how elements are stored when building the database model. For performance reasons the default is InMemory. For large databases, File backed storage is required.|
 
-
 ## Next Steps
 
 - Learn more about [sqlpackage](sqlpackage.md)

docs/tools/sqlpackage/troubleshooting-import-export-sqlpackage.md

@@ -0,0 +1,59 @@
+---
+title: Troubleshooting Import/Export with SqlPackage
+description: Learn how to troubleshoot import and export with SqlPackage.exe.
+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: 5/5/2021
+---
+
+# Troubleshooting Import/Export with SqlPackage
+
+In some scenarios, import or export operations take longer than expected or fail to complete.  The following are some frequently suggested tactics to troubleshoot import and export operations. While reading the specific documentation page for each action to understand the available parameters and properties is recommended, this article serves as a starting point in investigating SqlPackage Import or Export operations.
+
+## Overall strategy
+As general guideline, better performance can be obtained via the [.NET Core version](sqlpackage-download.md#get-sqlpackage-net-core-for-windows) of SqlPackage.exe.
+
+1. [Download](sqlpackage-download.md#get-sqlpackage-net-core-for-windows) the zip for SqlPackage on .NET Core for your operating system (Windows, macOS, or Linux).
+2. Unzip archive as directed on the download page.
+3. Open a command prompt and change directory (`cd`) to the SqlPackage folder.
+
+For Import, an example command is:
+```bash
+./SqlPackage /Action:Import /sf:<source-bacpac-file-path> /tsn:<full-target-server-name> /tdn:<a new or empty database> /tu:<target-server-username> /tp:<target-server-password> /df:<log-file>
+```
+
+For Export, an example command is:
+```bash
+./SqlPackage /Action:Export /tf:<target-bacpac-file-path> /ssn:<full-source-server-name> /sdn:<source-database-name> /su:<source-server-username> /sp:<source-server-password> /df:<log-file>
+```
+
+Alternative to username and password, [Universal Authentication](/azure/azure-sql/database/authentication-mfa-ssms-overview) can be used to authenticate via Azure AD with MFA.  Substitute the username and password parameters for `/ua:true` and `/tid:"yourdomain.onmicrosoft.com"`.
+
+For issues related to timeouts, the properties `CommandTimeout` and `LongRunningCommandTimeout` can be used to tune the connection between SqlPackage.exe and the SQL instance.
+
+## Diagnostics
+Logs are essential to troubleshooting. Capture the diagnostic logs to a file with the `/DiagnosticsFile:<filename>` parameter.
+
+Additional performance-related trace data can be logged by setting the environment variable `DACFX_PERF_TRACE=true` before running SqlPackage.  To set this environment variable in PowerShell, use the following command:
+``` powershell
+Set-Item -Path Env:DACFX_PERF_TRACE -Value true
+```
+
+## Import action tips
+For imports that contain large tables or tables with many indexes, the use of `/p:RebuildIndexesOfflineForDataPhase=True` or `/p:DisableIndexesForDataPhase=False` may improve performance. These properties modify the index rebuild operation to occur offline or not occur, respectively. Those and other properties are available to tune the [SqlPackage.exe Import](sqlpackage-import.md) operation.
+
+## Export action tips
+As an alternative operation to obtain the database schema and data while skipping the schema validation, perform an [Extract](sqlpackage-extract.md) with `/p:ExtractAllTableData=True` and `/p:VerifyExtraction=True`.
+
+In scenarios where disk space is limited and runs out during the export, the use of `/p:TempDirectoryForTableData` allows the data for export to be buffered on an alternative disk. That and other properties are available to tune the [SqlPackage.exe Export](sqlpackage-export.md) operation.
+
+## Next steps
+
+- Learn more about [SqlPackage Import](sqlpackage-import.md)
+- Learn more about [SqlPackage Export](sqlpackage-export.md)