Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[pull] development from d365collaborative:development #68

Merged
merged 5 commits into from
Oct 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions d365fo.tools/functions/import-d365bacpac.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -245,7 +259,9 @@ function Import-D365Bacpac {

[switch] $OutputCommandOnly,

[switch] $EnableException
[switch] $EnableException,

[string[]] $Properties
)

if (-not (Test-PathExists -Path $BacpacFile -Type Leaf)) {
Expand Down Expand Up @@ -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"
Expand All @@ -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 }

Expand Down
19 changes: 16 additions & 3 deletions d365fo.tools/tests/functions/Import-D365Bacpac.Tests.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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
#>
}

Expand Down
35 changes: 32 additions & 3 deletions docs/Import-D365Bacpac.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Import-D365Bacpac [-ImportModeTier1] [[-DatabaseServer] <String>] [[-DatabaseNam
[[-SqlUser] <String>] [[-SqlPwd] <String>] [-BacpacFile] <String> [-NewDatabaseName] <String>
[-CustomSqlFile <String>] [-ModelFile <String>] [-DiagnosticFile <String>] [-ImportOnly]
[-MaxParallelism <Int32>] [-LogPath <String>] [-ShowOriginalProgress] [-OutputCommandOnly] [-EnableException]
[<CommonParameters>]
[-Properties <String[]>] [<CommonParameters>]
```

### ImportOnlyTier2
Expand All @@ -29,7 +29,7 @@ Import-D365Bacpac [-ImportModeTier2] [[-DatabaseServer] <String>] [[-DatabaseNam
[[-AxMrRuntimeUserPwd] <String>] [[-AxRetailRuntimeUserPwd] <String>] [[-AxRetailDataSyncUserPwd] <String>]
[[-AxDbReadonlyUserPwd] <String>] [-CustomSqlFile <String>] [-ModelFile <String>] [-DiagnosticFile <String>]
[-ImportOnly] [-MaxParallelism <Int32>] [-LogPath <String>] [-ShowOriginalProgress] [-OutputCommandOnly]
[-EnableException] [<CommonParameters>]
[-EnableException] [-Properties <String[]>] [<CommonParameters>]
```

### ImportTier2
Expand All @@ -40,7 +40,7 @@ Import-D365Bacpac [-ImportModeTier2] [[-DatabaseServer] <String>] [[-DatabaseNam
[-AxMrRuntimeUserPwd] <String> [-AxRetailRuntimeUserPwd] <String> [-AxRetailDataSyncUserPwd] <String>
[-AxDbReadonlyUserPwd] <String> [-CustomSqlFile <String>] [-ModelFile <String>] [-DiagnosticFile <String>]
[-MaxParallelism <Int32>] [-LogPath <String>] [-ShowOriginalProgress] [-OutputCommandOnly] [-EnableException]
[<CommonParameters>]
[-Properties <String[]>] [<CommonParameters>]
```

## DESCRIPTION
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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).

Expand Down
38 changes: 38 additions & 0 deletions wiki/Troubleshoot.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Loading