Skip to content

Commit 56d0132

Browse files
sjohanssonsjohansson
committed
Enhance documentation for utility scripts with detailed descriptions, parameters, and examples
1 parent 23cb3f8 commit 56d0132

9 files changed

Lines changed: 409 additions & 90 deletions

‎Scripts/Utils/ConvertTo-MarkdownTable.ps1‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,45 @@
1+
<#
2+
.SYNOPSIS
3+
Converts pipeline objects to a Markdown-formatted table.
4+
5+
.DESCRIPTION
6+
This function takes objects from the pipeline and converts them into a Markdown table format.
7+
It supports automatic property detection or custom property selection, handles escaping of
8+
special characters, and formats datetime values consistently.
9+
10+
.PARAMETER InputObject
11+
The object(s) to convert to a Markdown table. Accepts pipeline input.
12+
13+
.PARAMETER Property
14+
Optional array of property names to include in the table. If not specified,
15+
all NoteProperty members from the first object are used.
16+
17+
.EXAMPLE
18+
Get-Process | Select-Object -First 5 Name, Id, CPU | ConvertTo-MarkdownTable
19+
20+
.EXAMPLE
21+
$results | ConvertTo-MarkdownTable -Property 'Name', 'Status', 'Duration'
22+
23+
.OUTPUTS
24+
System.String - A Markdown-formatted table string.
25+
26+
.NOTES
27+
File Name : ConvertTo-MarkdownTable.ps1
28+
Prerequisite : PowerShell 5.1 or later
29+
License : LGPL-3.0 (GNU Lesser General Public License v3.0)
30+
31+
.LINK
32+
https://github.com/data-solution-automation-engine/DIRECT
33+
34+
.LINK
35+
https://github.com/data-solution-automation-engine/DIRECT/blob/main/COPYING.txt
36+
37+
.COMPONENT
38+
DIRECT Framework - Data Integration Runtime Execution Control Tools
39+
40+
.FUNCTIONALITY
41+
Utility function for generating Markdown output from PowerShell objects.
42+
#>
143
function ConvertTo-MarkdownTable {
244
[CmdletBinding()]
345
param(

‎Scripts/Utils/Deploy-Dacpac.ps1‎

Lines changed: 46 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,60 @@
11
<#
22
.SYNOPSIS
3-
Deploys a DACPAC to a SQL Server database.
3+
Deploys a DACPAC to a SQL Server database.
4+
45
.DESCRIPTION
5-
Handles connection, optional database drop, and calls sqlpackage to deploy
6-
the specified DACPAC to the target database.
6+
Handles connection, optional database drop, and calls sqlpackage to deploy
7+
the specified DACPAC to the target database. Supports both interactive and
8+
automated deployment modes with configurable database purge behavior.
9+
710
.PARAMETER DacpacPath
8-
The path to the DACPAC file to deploy.
11+
The path to the DACPAC file to deploy.
12+
913
.PARAMETER ConnectionString
10-
The connection string for the SQL Server instance.
14+
The connection string for the SQL Server instance.
15+
1116
.PARAMETER DatabaseName
12-
The name of the database to deploy to (optional).
17+
The name of the database to deploy to. If not specified, extracted from
18+
the connection string.
19+
1320
.PARAMETER Description
14-
A description for the deployment (optional).
21+
A description for the deployment (optional). Defaults to the DACPAC filename.
22+
1523
.PARAMETER AutoDeploy
16-
If true, skips user prompt and deploys automatically.
24+
If true, skips user prompt and deploys automatically.
25+
1726
.PARAMETER AutoPurge
18-
If true, drops the database if it exists before deploying.
27+
If true, drops the database if it exists before deploying.
28+
1929
.EXAMPLE
20-
Deploy-Dacpac -DacpacPath "./db/Direct_Framework.dacpac" -ConnectionString $cs `
21-
-DatabaseName "Direct_Framework" -AutoDeploy $true -AutoPurge $true
30+
Deploy-Dacpac -DacpacPath "./db/Direct_Framework.dacpac" -ConnectionString $cs `
31+
-DatabaseName "Direct_Framework" -AutoDeploy $true -AutoPurge $true
32+
33+
.EXAMPLE
34+
Deploy-Dacpac -DacpacPath $dacpacFile -ConnectionString $connectionString
35+
36+
.OUTPUTS
37+
System.Boolean - Returns $true if deployment succeeds, otherwise $false.
38+
2239
.NOTES
23-
Returns $true if deployment succeeds, otherwise $false.
40+
File Name : Deploy-Dacpac.ps1
41+
Prerequisite : PowerShell 5.1 or later, sqlpackage dotnet tool
42+
License : LGPL-3.0 (GNU Lesser General Public License v3.0)
43+
44+
.LINK
45+
https://github.com/data-solution-automation-engine/DIRECT
46+
47+
.LINK
48+
https://github.com/data-solution-automation-engine/DIRECT/blob/main/COPYING.txt
49+
50+
.LINK
51+
https://learn.microsoft.com/en-us/sql/tools/sqlpackage/sqlpackage
52+
53+
.COMPONENT
54+
DIRECT Framework - Data Integration Runtime Execution Control Tools
55+
56+
.FUNCTIONALITY
57+
Database deployment and DACPAC management.
2458
#>
2559
function Deploy-Dacpac {
2660
param(

‎Scripts/Utils/Get-DacpacVersion.ps1‎

Lines changed: 31 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,40 @@
11
<#
22
.SYNOPSIS
3-
Extracts the version from a DACPAC file.
3+
Extracts the version from a DACPAC file.
4+
45
.DESCRIPTION
5-
Unzips the DACPAC file, reads the model.xml, and returns the version property if present.
6+
Unzips the DACPAC file, reads the model.xml, and returns the version property
7+
if present. The DACPAC is extracted to a temporary directory which is cleaned
8+
up after processing.
9+
610
.PARAMETER DacpacPath
7-
The path to the DACPAC file, relative to the script file location.
11+
The path to the DACPAC file to extract version information from.
12+
813
.EXAMPLE
9-
$version = Get-DacpacVersion -DacpacPath "./db/Direct_Framework.dacpac"
14+
$version = Get-DacpacVersion -DacpacPath "./db/Direct_Framework.dacpac"
15+
16+
.EXAMPLE
17+
Get-ChildItem -Filter *.dacpac | ForEach-Object { Get-DacpacVersion -DacpacPath $_.FullName }
18+
19+
.OUTPUTS
20+
System.String - The version string from the DACPAC, or $null if not found.
21+
1022
.NOTES
11-
Returns the version string or $null if not found.
23+
File Name : Get-DacpacVersion.ps1
24+
Prerequisite : PowerShell 5.1 or later
25+
License : LGPL-3.0 (GNU Lesser General Public License v3.0)
26+
27+
.LINK
28+
https://github.com/data-solution-automation-engine/DIRECT
29+
30+
.LINK
31+
https://github.com/data-solution-automation-engine/DIRECT/blob/main/COPYING.txt
32+
33+
.COMPONENT
34+
DIRECT Framework - Data Integration Runtime Execution Control Tools
35+
36+
.FUNCTIONALITY
37+
DACPAC version extraction and analysis.
1238
#>
1339
function Get-DacpacVersion {
1440
param([string]$DacpacPath)

‎Scripts/Utils/Install-SqlServerModule.ps1‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,48 @@
1+
<#
2+
.SYNOPSIS
3+
Installs or updates the SqlServer PowerShell module.
4+
5+
.DESCRIPTION
6+
Ensures the SqlServer module is installed from PSGallery. Handles NuGet provider
7+
installation, PSGallery trust configuration, module version checking, and optional
8+
upgrade to the latest version. Supports both interactive and non-interactive modes.
9+
10+
.PARAMETER NoAutoUpgrade
11+
If specified, prevents automatic upgrade to the latest version when a newer
12+
version is available.
13+
14+
.PARAMETER Interactive
15+
If specified, prompts the user for upgrade confirmation rather than just logging.
16+
17+
.EXAMPLE
18+
Install-SqlServerModule
19+
20+
.EXAMPLE
21+
Install-SqlServerModule -NoAutoUpgrade -Interactive
22+
23+
.OUTPUTS
24+
System.Version - The version of the installed SqlServer module, or $null on failure.
25+
26+
.NOTES
27+
File Name : Install-SqlServerModule.ps1
28+
Prerequisite : PowerShell 5.1 or later, Internet connectivity
29+
License : LGPL-3.0 (GNU Lesser General Public License v3.0)
30+
31+
.LINK
32+
https://github.com/data-solution-automation-engine/DIRECT
33+
34+
.LINK
35+
https://github.com/data-solution-automation-engine/DIRECT/blob/main/COPYING.txt
36+
37+
.LINK
38+
https://www.powershellgallery.com/packages/SqlServer
39+
40+
.COMPONENT
41+
DIRECT Framework - Data Integration Runtime Execution Control Tools
42+
43+
.FUNCTIONALITY
44+
PowerShell module management and SQL Server tooling setup.
45+
#>
146
function Install-SqlServerModule {
247
[CmdletBinding()]
348
param(

‎Scripts/Utils/Invoke-Sqlcmd.ps1‎

Lines changed: 45 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,56 @@
11
<#
22
.SYNOPSIS
3-
Executes a Sql File on a SQL Server database.
3+
Executes a SQL file or query on a SQL Server database.
4+
45
.DESCRIPTION
5-
Executes SQL file using sqlcmd against a SQL Server instance.
6+
Executes SQL file or inline query using the sqlcmd utility against a SQL Server
7+
instance. Supports both file-based and inline query execution with configurable
8+
output display options.
9+
610
.PARAMETER SqlPath
7-
The path to the SQL file to deploy.
11+
The path to the SQL file to execute. Either SqlPath or Query must be provided.
12+
13+
.PARAMETER Query
14+
An inline SQL query to execute. Either SqlPath or Query must be provided.
15+
816
.PARAMETER ConnectionString
9-
The connection string for the SQL Server instance.
17+
The connection string for the SQL Server instance. Must include Server,
18+
Initial Catalog, User ID, and Password.
19+
1020
.PARAMETER ShowResult
11-
Should the function print the output from the command.
21+
If true (default), prints the output from the sqlcmd command.
22+
23+
.PARAMETER Silent
24+
If specified, suppresses informational output messages.
25+
26+
.EXAMPLE
27+
Invoke-Sqlcmd -SqlPath "./sqlFile.sql" -ConnectionString $cs
28+
1229
.EXAMPLE
13-
Invoke-Sqlcmd -SqlPath "./sqlFile.sql" -ConnectionString $cs
30+
Invoke-Sqlcmd -Query "SELECT @@VERSION" -ConnectionString $cs -Silent
31+
32+
.OUTPUTS
33+
Returns the command output on success, or $false on failure.
34+
1435
.NOTES
15-
Returns $true if invocation succeeds, otherwise $false.
36+
File Name : Invoke-Sqlcmd.ps1
37+
Prerequisite : PowerShell 5.1 or later, sqlcmd utility
38+
License : LGPL-3.0 (GNU Lesser General Public License v3.0)
39+
40+
.LINK
41+
https://github.com/data-solution-automation-engine/DIRECT
42+
43+
.LINK
44+
https://github.com/data-solution-automation-engine/DIRECT/blob/main/COPYING.txt
45+
46+
.LINK
47+
https://learn.microsoft.com/en-us/sql/tools/sqlcmd/sqlcmd-utility
48+
49+
.COMPONENT
50+
DIRECT Framework - Data Integration Runtime Execution Control Tools
51+
52+
.FUNCTIONALITY
53+
SQL script execution and database query management.
1654
#>
1755
function Invoke-Sqlcmd {
1856
param(

‎Scripts/Utils/Invoke-WithRetry.ps1‎

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,47 @@
11
<#
22
.SYNOPSIS
3-
Executes a script block with retry logic.
3+
Executes a script block with retry logic.
4+
45
.DESCRIPTION
5-
Runs a script block up to a maximum number of attempts, waiting between attempts, and returns $true if successful.
6+
Runs a script block up to a maximum number of attempts, waiting between attempts,
7+
and returns $true if successful. Useful for operations that may fail transiently,
8+
such as network calls or resource availability checks.
9+
610
.PARAMETER ScriptBlock
7-
The script block to execute. Should return $true on success, $false or throw on failure.
11+
The script block to execute. Should return $true on success, $false or throw
12+
an exception on failure.
13+
814
.PARAMETER MaxAttempts
9-
Maximum number of attempts (default: 10).
15+
Maximum number of attempts before giving up. Default is 10.
16+
1017
.PARAMETER NapLength
11-
Seconds to wait between attempts (default: 5).
18+
Seconds to wait between retry attempts. Default is 5.
19+
1220
.EXAMPLE
13-
Invoke-WithRetry -ScriptBlock { Test-Connection ... } -MaxAttempts 5 -NapLength 2
21+
Invoke-WithRetry -ScriptBlock { Test-Connection -ComputerName 'server' -Quiet } -MaxAttempts 5 -NapLength 2
22+
23+
.EXAMPLE
24+
Invoke-WithRetry -ScriptBlock { Test-NetConnection -ComputerName 'localhost' -Port 1433 } -MaxAttempts 30
25+
26+
.OUTPUTS
27+
System.Boolean - Returns $true if the script block succeeds, otherwise $false.
28+
1429
.NOTES
15-
Returns $true if the script block succeeds, otherwise $false.
30+
File Name : Invoke-WithRetry.ps1
31+
Prerequisite : PowerShell 5.1 or later
32+
License : LGPL-3.0 (GNU Lesser General Public License v3.0)
33+
34+
.LINK
35+
https://github.com/data-solution-automation-engine/DIRECT
36+
37+
.LINK
38+
https://github.com/data-solution-automation-engine/DIRECT/blob/main/COPYING.txt
39+
40+
.COMPONENT
41+
DIRECT Framework - Data Integration Runtime Execution Control Tools
42+
43+
.FUNCTIONALITY
44+
Resilient execution and retry pattern implementation.
1645
#>
1746
function Invoke-WithRetry {
1847
param(

‎Scripts/Utils/Test-DotnetTool.ps1‎

Lines changed: 35 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,44 @@
1-
21
<#
32
.SYNOPSIS
4-
Checks for the existence and usability of a dotnet tool (local or global).
3+
Checks for the existence and usability of a dotnet tool (local or global).
4+
55
.DESCRIPTION
6-
Checks if the specified dotnet tool is installed locally or globally, attempts to restore if missing, and returns a hashtable with tool existence and command string.
6+
Checks if the specified dotnet tool is installed locally or globally, attempts
7+
to restore from dotnet-tools.json if missing, and returns a hashtable with tool
8+
existence status and the command string to invoke it.
9+
710
.PARAMETER ToolName
8-
The name of the dotnet tool to check (e.g., 'sqlpackage').
11+
The name of the dotnet tool to check (e.g., 'sqlpackage').
12+
913
.EXAMPLE
10-
$tool = Test-Tool -ToolName "sqlpackage"
14+
$tool = Test-DotnetTool -ToolName "sqlpackage"
15+
if ($tool.Exists) { & $tool.Command --version }
16+
17+
.EXAMPLE
18+
$result = Test-DotnetTool -ToolName "dotnet-ef"
19+
20+
.OUTPUTS
21+
System.Collections.Hashtable - Returns @{ Exists = $true/$false; Command = "..." }
22+
1123
.NOTES
12-
Returns a hashtable: @{ Exists = $true/$false; Command = "..." }
24+
File Name : Test-DotnetTool.ps1
25+
Prerequisite : PowerShell 5.1 or later, .NET SDK
26+
License : LGPL-3.0 (GNU Lesser General Public License v3.0)
27+
28+
.LINK
29+
https://github.com/data-solution-automation-engine/DIRECT
30+
31+
.LINK
32+
https://github.com/data-solution-automation-engine/DIRECT/blob/main/COPYING.txt
33+
34+
.LINK
35+
https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-install
36+
37+
.COMPONENT
38+
DIRECT Framework - Data Integration Runtime Execution Control Tools
39+
40+
.FUNCTIONALITY
41+
Dotnet tool discovery and validation.
1342
#>
1443
function Test-DotnetTool {
1544
param(

0 commit comments

Comments
 (0)