diff --git a/d365fo.tools/functions/import-d365bacpac.ps1 b/d365fo.tools/functions/import-d365bacpac.ps1 index aca14db2..98389379 100644 --- a/d365fo.tools/functions/import-d365bacpac.ps1 +++ b/d365fo.tools/functions/import-d365bacpac.ps1 @@ -103,6 +103,11 @@ This parameters disables user-friendly warnings and enables the throwing of exceptions This is less user friendly, but allows catching exceptions in calling scripts + .PARAMETER Properties + String array of properties to be used by SQLPackage.exe + See https://learn.microsoft.com/en-us/sql/tools/sqlpackage/sqlpackage-import#properties-specific-to-the-import-action for more information. + Note that some properties are already set by the cmdlet, and cannot be overridden. + .EXAMPLE PS C:\> Invoke-D365InstallSqlPackage @@ -155,6 +160,15 @@ This would be something that you can use when extract a bacpac file from a Tier1 and want to import it into a Tier1. You would still need to execute the Switch-D365ActiveDatabase cmdlet, to get the newly imported database to be the AXDB database. + .EXAMPLE + PS C:\> [System.Collections.ArrayList] $PropertiesList = New-Object -TypeName "System.Collections.ArrayList" + PS C:\> $PropertiesList.Add("DisableIndexesForDataPhase=false") + PS C:\> Import-D365Bacpac -ImportModeTier1 -BacpacFile "C:\temp\uat.bacpac" -NewDatabaseName "ImportedDatabase" -Properties $PropertiesList.ToArray() + + This will instruct the cmdlet that the import will be working against a SQL Server instance. + It will import the "C:\temp\uat.bacpac" file into a new database named "ImportedDatabase". + It will use the DisableIndexesForDataPhase SQLPackage property to disable the index rebuild during the data phase of the import. + .NOTES Tags: Database, Bacpac, Tier1, Tier2, Golden Config, Config, Configuration @@ -245,7 +259,9 @@ function Import-D365Bacpac { [switch] $OutputCommandOnly, - [switch] $EnableException + [switch] $EnableException, + + [string[]] $Properties ) if (-not (Test-PathExists -Path $BacpacFile -Type Leaf)) { @@ -289,6 +305,11 @@ function Import-D365Bacpac { $ImportParams.ModelFile = $ModelFile } + [System.Collections.ArrayList] $PropertiesList = New-Object -TypeName "System.Collections.ArrayList" + foreach ($item in $Properties) { + $PropertiesList.Add($item) > $null + } + Write-PSFMessage -Level Verbose "Testing if we are working against a Tier2 / Azure DB" if ($ImportModeTier2) { Write-PSFMessage -Level Verbose "Start collecting the current Azure DB instance settings" @@ -297,18 +318,19 @@ function Import-D365Bacpac { if ($null -eq $Objectives) { return } - [System.Collections.ArrayList] $Properties = New-Object -TypeName "System.Collections.ArrayList" - $null = $Properties.Add("DatabaseEdition=$($Objectives.DatabaseEdition)") - $null = $Properties.Add("DatabaseServiceObjective=$($Objectives.DatabaseServiceObjective)") - - $ImportParams.Properties = $Properties.ToArray() + $null = $PropertiesList.Add("DatabaseEdition=$($Objectives.DatabaseEdition)") + $null = $PropertiesList.Add("DatabaseServiceObjective=$($Objectives.DatabaseServiceObjective)") } + $ImportParams.Properties = $PropertiesList.ToArray() $Params = Get-DeepClone $BaseParams $Params.DatabaseName = $NewDatabaseName + $Params.TrustedConnection = $UseTrustedConnection + $Params.OutputCommandOnly = $OutputCommandOnly + $Params.LogPath = $LogPath Write-PSFMessage -Level Verbose "Start importing the bacpac with a new database name and current settings" - Invoke-SqlPackage @Params @ImportParams -TrustedConnection $UseTrustedConnection -ShowOriginalProgress:$ShowOriginalProgress -OutputCommandOnly:$OutputCommandOnly -LogPath $LogPath + Invoke-SqlPackage @Params @ImportParams -ShowOriginalProgress:$ShowOriginalProgress if ($OutputCommandOnly) { return } diff --git a/d365fo.tools/tests/functions/Import-D365Bacpac.Tests.ps1 b/d365fo.tools/tests/functions/Import-D365Bacpac.Tests.ps1 index a54d0d18..cf5194b1 100644 --- a/d365fo.tools/tests/functions/Import-D365Bacpac.Tests.ps1 +++ b/d365fo.tools/tests/functions/Import-D365Bacpac.Tests.ps1 @@ -413,24 +413,37 @@ $parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False $parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False } + It 'Should have the expected parameter Properties' { + $parameter = (Get-Command Import-D365Bacpac).Parameters['Properties'] + $parameter.Name | Should -Be 'Properties' + $parameter.ParameterType.ToString() | Should -Be System.String[] + $parameter.IsDynamic | Should -Be $False + $parameter.ParameterSets.Keys | Should -Be '__AllParameterSets' + $parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets' + $parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $False + $parameter.ParameterSets['__AllParameterSets'].Position | Should -Be -2147483648 + $parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False + $parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False + $parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False + } } Describe "Testing parameterset ImportTier1" { <# ImportTier1 -ImportModeTier1 -BacpacFile -NewDatabaseName - ImportTier1 -ImportModeTier1 -DatabaseServer -DatabaseName -SqlUser -SqlPwd -BacpacFile -NewDatabaseName -CustomSqlFile -ModelFile -DiagnosticFile -ImportOnly -MaxParallelism -LogPath -ShowOriginalProgress -OutputCommandOnly -EnableException + ImportTier1 -ImportModeTier1 -DatabaseServer -DatabaseName -SqlUser -SqlPwd -BacpacFile -NewDatabaseName -CustomSqlFile -ModelFile -DiagnosticFile -ImportOnly -MaxParallelism -LogPath -ShowOriginalProgress -OutputCommandOnly -EnableException -Properties #> } Describe "Testing parameterset ImportOnlyTier2" { <# ImportOnlyTier2 -ImportModeTier2 -SqlUser -SqlPwd -BacpacFile -NewDatabaseName -ImportOnly - ImportOnlyTier2 -ImportModeTier2 -DatabaseServer -DatabaseName -SqlUser -SqlPwd -BacpacFile -NewDatabaseName -AxDeployExtUserPwd -AxDbAdminPwd -AxRuntimeUserPwd -AxMrRuntimeUserPwd -AxRetailRuntimeUserPwd -AxRetailDataSyncUserPwd -AxDbReadonlyUserPwd -CustomSqlFile -ModelFile -DiagnosticFile -ImportOnly -MaxParallelism -LogPath -ShowOriginalProgress -OutputCommandOnly -EnableException + ImportOnlyTier2 -ImportModeTier2 -DatabaseServer -DatabaseName -SqlUser -SqlPwd -BacpacFile -NewDatabaseName -AxDeployExtUserPwd -AxDbAdminPwd -AxRuntimeUserPwd -AxMrRuntimeUserPwd -AxRetailRuntimeUserPwd -AxRetailDataSyncUserPwd -AxDbReadonlyUserPwd -CustomSqlFile -ModelFile -DiagnosticFile -ImportOnly -MaxParallelism -LogPath -ShowOriginalProgress -OutputCommandOnly -EnableException -Properties #> } Describe "Testing parameterset ImportTier2" { <# ImportTier2 -ImportModeTier2 -SqlUser -SqlPwd -BacpacFile -NewDatabaseName -AxDeployExtUserPwd -AxDbAdminPwd -AxRuntimeUserPwd -AxMrRuntimeUserPwd -AxRetailRuntimeUserPwd -AxRetailDataSyncUserPwd -AxDbReadonlyUserPwd - ImportTier2 -ImportModeTier2 -DatabaseServer -DatabaseName -SqlUser -SqlPwd -BacpacFile -NewDatabaseName -AxDeployExtUserPwd -AxDbAdminPwd -AxRuntimeUserPwd -AxMrRuntimeUserPwd -AxRetailRuntimeUserPwd -AxRetailDataSyncUserPwd -AxDbReadonlyUserPwd -CustomSqlFile -ModelFile -DiagnosticFile -MaxParallelism -LogPath -ShowOriginalProgress -OutputCommandOnly -EnableException + ImportTier2 -ImportModeTier2 -DatabaseServer -DatabaseName -SqlUser -SqlPwd -BacpacFile -NewDatabaseName -AxDeployExtUserPwd -AxDbAdminPwd -AxRuntimeUserPwd -AxMrRuntimeUserPwd -AxRetailRuntimeUserPwd -AxRetailDataSyncUserPwd -AxDbReadonlyUserPwd -CustomSqlFile -ModelFile -DiagnosticFile -MaxParallelism -LogPath -ShowOriginalProgress -OutputCommandOnly -EnableException -Properties #> } diff --git a/docs/Import-D365Bacpac.md b/docs/Import-D365Bacpac.md index eee7f121..3d0952da 100644 --- a/docs/Import-D365Bacpac.md +++ b/docs/Import-D365Bacpac.md @@ -18,7 +18,7 @@ Import-D365Bacpac [-ImportModeTier1] [[-DatabaseServer] ] [[-DatabaseNam [[-SqlUser] ] [[-SqlPwd] ] [-BacpacFile] [-NewDatabaseName] [-CustomSqlFile ] [-ModelFile ] [-DiagnosticFile ] [-ImportOnly] [-MaxParallelism ] [-LogPath ] [-ShowOriginalProgress] [-OutputCommandOnly] [-EnableException] - [] + [-Properties ] [] ``` ### ImportOnlyTier2 @@ -29,7 +29,7 @@ Import-D365Bacpac [-ImportModeTier2] [[-DatabaseServer] ] [[-DatabaseNam [[-AxMrRuntimeUserPwd] ] [[-AxRetailRuntimeUserPwd] ] [[-AxRetailDataSyncUserPwd] ] [[-AxDbReadonlyUserPwd] ] [-CustomSqlFile ] [-ModelFile ] [-DiagnosticFile ] [-ImportOnly] [-MaxParallelism ] [-LogPath ] [-ShowOriginalProgress] [-OutputCommandOnly] - [-EnableException] [] + [-EnableException] [-Properties ] [] ``` ### ImportTier2 @@ -40,7 +40,7 @@ Import-D365Bacpac [-ImportModeTier2] [[-DatabaseServer] ] [[-DatabaseNam [-AxMrRuntimeUserPwd] [-AxRetailRuntimeUserPwd] [-AxRetailDataSyncUserPwd] [-AxDbReadonlyUserPwd] [-CustomSqlFile ] [-ModelFile ] [-DiagnosticFile ] [-MaxParallelism ] [-LogPath ] [-ShowOriginalProgress] [-OutputCommandOnly] [-EnableException] - [] + [-Properties ] [] ``` ## DESCRIPTION @@ -114,6 +114,18 @@ No cleanup or prepping jobs will be executed, because this is for importing only This would be something that you can use when extract a bacpac file from a Tier1 and want to import it into a Tier1. You would still need to execute the Switch-D365ActiveDatabase cmdlet, to get the newly imported database to be the AXDB database. +### EXAMPLE 7 +``` +[System.Collections.ArrayList] $PropertiesList = New-Object -TypeName "System.Collections.ArrayList" +``` + +PS C:\\\> $PropertiesList.Add("DisableIndexesForDataPhase=false") +PS C:\\\> Import-D365Bacpac -ImportModeTier1 -BacpacFile "C:\temp\uat.bacpac" -NewDatabaseName "ImportedDatabase" -Properties $PropertiesList.ToArray() + +This will instruct the cmdlet that the import will be working against a SQL Server instance. +It will import the "C:\temp\uat.bacpac" file into a new database named "ImportedDatabase". +It will use the DisableIndexesForDataPhase SQLPackage property to disable the index rebuild during the data phase of the import. + ## PARAMETERS ### -ImportModeTier1 @@ -622,6 +634,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Properties +String array of properties to be used by SQLPackage.exe +See https://learn.microsoft.com/en-us/sql/tools/sqlpackage/sqlpackage-import#properties-specific-to-the-import-action for more information. +Note that some properties are already set by the cmdlet, and cannot be overridden. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). diff --git a/wiki/Troubleshoot.md b/wiki/Troubleshoot.md index cf7ea4f3..b0816708 100644 --- a/wiki/Troubleshoot.md +++ b/wiki/Troubleshoot.md @@ -1,3 +1,41 @@ +We appreciate you taking the time to read up on how to troubleshoot issues with the d365fo.tools. Ideally, this will enable you to get to a solution for your issue on your own. If not, it will still help you gather the information needed to get help from others. + +> **IMPORTANT** Note that some of the information gathered may contain sensitive information. Make sure to remove any sensitive information before sharing the information with others. + +# General Powershell troubleshooting + +## Check the versions + +### d365fo.tools + +Check whether the latest version of d365fo.tools is being used. This can be done with the `Get-Module d365fo.tools` cmdlet. If the cmdlet shows no output, add the `-ListAvailable` switch to see all versions installed on the machine. Usually the latest version will be used unless a different version is specified when loading the module. Compare the version with the latest version on [PowerShell Gallery](https://www.powershellgallery.com/packages/d365fo.tools/). + +> *Why is this important?* If an older version is used, a first step in troubleshooting is to update to the latest version. If the issue is already fixed in the latest version, there is no need to troubleshoot further. On the other hand, if the module needs to be on a specific older version, this is important information to know. + +### PowerShell + +Check which version of PowerShell is being used. This can be done with the `$PSVersionTable` variable. + +> *Why is this important?* The module is primarily developed and tested on Windows Server environments with Windows PowerShell (i.e. PowerShell 5.1). If you are using PowerShell Core (i.e. PowerShell 6 or 7) or an older version of Windows PowerShell, there may be issues. + +### Other components + +Some cmdlets of the module rely on other components, for example SQLPackage.exe for importing and creating bacpac and dacpac files. If you know the components used by the cmdlet, check the version of those components as well. + +> *Why is this important?* Sometimes the issue is not with the d365fo.tools, but the component it relies on. If the component is not up to date, it may contain a bug that is already fixed in a newer version. + +## Use common parameters + +Powershell provides some common parameters that can be used with any cmdlet, see [about common parameters](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_commonparameters). Often used parameters for troubleshooting are `-Verbose` and `-Debug`. Support for common parameters varies per cmdlet, but these two are supported by most. + +> *Why is this important?* The `-Verbose` parameter will provide additional information about what the cmdlet is doing. The `-Debug` parameter will provide even more information, including the values of variables used in the cmdlet. This can be very useful to see what is going on and where the issue is. + +## Additional error details + +Even with `-Verbose` and `-Debug`, the output of a cmdlet may not contain all the available information about an error that ocurred. To get more information, use the [automatic variable](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables) `$Error`. This variable contains an array of all errors that have occurred in the current session. The most recent error is `$Error[0]`, the second most recent is `$Error[1]`, etc. To get more information about an error, use the `| Format-List` cmdlet. For example, `$Error[0] | Format-List` will show the error message, the stack trace, and more. + +> *Why is this important?* The error message may not contain all the information needed to troubleshoot an issue. The stack trace may contain more information about where the issue occurred. + ## **Record a PowerShell session** ```PS Start-Transcript -Path "C:\Temp\PowerShellSession.log" -Append