From bed3b1267591ac4351de68eb04ddd22272d2926f Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Wed, 4 Jan 2023 08:39:48 +0100 Subject: [PATCH] SqlServerDsc: Add QA tests for commands (#1830) - SqlServerDsc - New QA tests for public commands and private functions. --- .github/prquantifier.yaml | 1 + CHANGELOG.md | 1 + .../Private/Assert-SetupActionProperties.ps1 | 1 + source/Private/Invoke-SetupAction.ps1 | 314 +++++++++++++++++- source/Public/Add-SqlDscNode.ps1 | 95 +++++- .../Public/Complete-SqlDscFailoverCluster.ps1 | 118 ++++++- source/Public/Complete-SqlDscImage.ps1 | 142 +++++++- .../Public/Connect-SqlDscDatabaseEngine.ps1 | 6 +- .../ConvertFrom-SqlDscDatabasePermission.ps1 | 4 + .../ConvertFrom-SqlDscServerPermission.ps1 | 4 + .../ConvertTo-SqlDscDatabasePermission.ps1 | 4 + .../ConvertTo-SqlDscServerPermission.ps1 | 4 + source/Public/Disable-SqlDscAudit.ps1 | 46 +-- source/Public/Enable-SqlDscAudit.ps1 | 46 +-- source/Public/Get-SqlDscAudit.ps1 | 40 ++- .../Public/Get-SqlDscDatabasePermission.ps1 | 61 ++-- source/Public/Get-SqlDscServerPermission.ps1 | 39 ++- .../Initialize-SqlDscRebuildDatabase.ps1 | 49 ++- source/Public/Install-SqlDscServer.ps1 | 311 ++++++++++++++++- source/Public/Invoke-SqlDscQuery.ps1 | 46 +-- source/Public/New-SqlDscAudit.ps1 | 177 +++++----- source/Public/Remove-SqlDscAudit.ps1 | 56 ++-- source/Public/Remove-SqlDscNode.ps1 | 17 +- source/Public/Repair-SqlDscServer.ps1 | 44 ++- source/Public/Set-SqlDscAudit.ps1 | 172 +++++----- .../Public/Set-SqlDscDatabasePermission.ps1 | 176 +++++----- source/Public/Set-SqlDscServerPermission.ps1 | 153 +++++---- .../Public/Test-SqlDscIsDatabasePrincipal.ps1 | 72 ++-- source/Public/Test-SqlDscIsLogin.ps1 | 18 +- source/Public/Uninstall-SqlDscServer.ps1 | 23 +- tests/QA/ScriptAnalyzer.Tests.ps1 | 22 ++ tests/QA/module.tests.ps1 | 256 ++++++++++++++ 32 files changed, 1977 insertions(+), 541 deletions(-) create mode 100644 tests/QA/module.tests.ps1 diff --git a/.github/prquantifier.yaml b/.github/prquantifier.yaml index 84b6c4b61..025c8c149 100644 --- a/.github/prquantifier.yaml +++ b/.github/prquantifier.yaml @@ -17,3 +17,4 @@ Thresholds: - Value: 1000 Label: PR extra large Color: Red +IgnoreRenamed: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 47282f5d0..45b820ddc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -68,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add the GitHub App _Pull Request Quantifier_ as an experiment to see if it brings any value ([issue #1811](https://github.com/dsccommunity/SqlServerDsc/issues/1811)). - Updated thresholds, and label names and colors. + - New QA tests for public commands and private functions. - SqlDatabase - Added compatibility levels for SQL Server 2022 (major version 16). - SqlSetup diff --git a/source/Private/Assert-SetupActionProperties.ps1 b/source/Private/Assert-SetupActionProperties.ps1 index ebed3c61a..b2d95d6e5 100644 --- a/source/Private/Assert-SetupActionProperties.ps1 +++ b/source/Private/Assert-SetupActionProperties.ps1 @@ -26,6 +26,7 @@ #> function Assert-SetupActionProperties { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '', Justification='The command uses plural noun to describe that it contain a collection of asserts.')] [CmdletBinding()] param ( diff --git a/source/Private/Invoke-SetupAction.ps1 b/source/Private/Invoke-SetupAction.ps1 index 081b60984..ea797540c 100644 --- a/source/Private/Invoke-SetupAction.ps1 +++ b/source/Private/Invoke-SetupAction.ps1 @@ -63,6 +63,312 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER SuppressPrivacyStatementNotice + See the notes section for more information. + + .PARAMETER IAcknowledgeEntCalLimits + See the notes section for more information. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER Enu + See the notes section for more information. + + .PARAMETER UpdateEnabled + See the notes section for more information. + + .PARAMETER UpdateSource + See the notes section for more information. + + .PARAMETER Features + See the notes section for more information. + + .PARAMETER Role + See the notes section for more information. + + .PARAMETER InstallSharedDir + See the notes section for more information. + + .PARAMETER InstallSharedWowDir + See the notes section for more information. + + .PARAMETER InstanceDir + See the notes section for more information. + + .PARAMETER InstanceId + See the notes section for more information. + + .PARAMETER PBEngSvcAccount + See the notes section for more information. + + .PARAMETER PBEngSvcPassword + See the notes section for more information. + + .PARAMETER PBEngSvcStartupType + See the notes section for more information. + + .PARAMETER PBDMSSvcAccount + See the notes section for more information. + + .PARAMETER PBDMSSvcPassword + See the notes section for more information. + + .PARAMETER PBDMSSvcStartupType + See the notes section for more information. + + .PARAMETER PBStartPortRange + See the notes section for more information. + + .PARAMETER PBEndPortRange + See the notes section for more information. + + .PARAMETER PBScaleOut + See the notes section for more information. + + .PARAMETER ProductKey + See the notes section for more information. + + .PARAMETER AgtSvcAccount + See the notes section for more information. + + .PARAMETER AgtSvcPassword + See the notes section for more information. + + .PARAMETER AgtSvcStartupType + See the notes section for more information. + + .PARAMETER ASBackupDir + See the notes section for more information. + + .PARAMETER ASCollation + See the notes section for more information. + + .PARAMETER ASConfigDir + See the notes section for more information. + + .PARAMETER ASDataDir + See the notes section for more information. + + .PARAMETER ASLogDir + See the notes section for more information. + + .PARAMETER ASTempDir + See the notes section for more information. + + .PARAMETER ASServerMode + See the notes section for more information. + + .PARAMETER ASSvcAccount + See the notes section for more information. + + .PARAMETER ASSvcPassword + See the notes section for more information. + + .PARAMETER ASSvcStartupType + See the notes section for more information. + + .PARAMETER ASSysAdminAccounts + See the notes section for more information. + + .PARAMETER ASProviderMSOLAP + See the notes section for more information. + + .PARAMETER FarmAccount + See the notes section for more information. + + .PARAMETER FarmPassword + See the notes section for more information. + + .PARAMETER Passphrase + See the notes section for more information. + + .PARAMETER FarmAdminiPort + See the notes section for more information. + + .PARAMETER BrowserSvcStartupType + See the notes section for more information. + + .PARAMETER FTUpgradeOption + See the notes section for more information. + + .PARAMETER EnableRanU + See the notes section for more information. + + .PARAMETER InstallSqlDataDir + See the notes section for more information. + + .PARAMETER SqlBackupDir + See the notes section for more information. + + .PARAMETER SecurityMode + See the notes section for more information. + + .PARAMETER SAPwd + See the notes section for more information. + + .PARAMETER SqlCollation + See the notes section for more information. + + .PARAMETER AddCurrentUserAsSqlAdmin + See the notes section for more information. + + .PARAMETER SqlSvcAccount + See the notes section for more information. + + .PARAMETER SqlSvcPassword + See the notes section for more information. + + .PARAMETER SqlSvcStartupType + See the notes section for more information. + + .PARAMETER SqlSysAdminAccounts + See the notes section for more information. + + .PARAMETER SqlTempDbDir + See the notes section for more information. + + .PARAMETER SqlTempDbLogDir + See the notes section for more information. + + .PARAMETER SqlTempDbFileCount + See the notes section for more information. + + .PARAMETER SqlTempDbFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbFileGrowth + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileGrowth + See the notes section for more information. + + .PARAMETER SqlUserDbDir + See the notes section for more information. + + .PARAMETER SqlSvcInstantFileInit + See the notes section for more information. + + .PARAMETER SqlUserDbLogDir + See the notes section for more information. + + .PARAMETER SqlMaxDop + See the notes section for more information. + + .PARAMETER UseSqlRecommendedMemoryLimits + See the notes section for more information. + + .PARAMETER SqlMinMemory + See the notes section for more information. + + .PARAMETER SqlMaxMemory + See the notes section for more information. + + .PARAMETER FileStreamLevel + See the notes section for more information. + + .PARAMETER FileStreamShareName + See the notes section for more information. + + .PARAMETER ISSvcAccount + See the notes section for more information. + + .PARAMETER ISSvcPassword + See the notes section for more information. + + .PARAMETER ISSvcStartupType + See the notes section for more information. + + .PARAMETER AllowUpgradeForSSRSSharePointMode + See the notes section for more information. + + .PARAMETER NpEnabled + See the notes section for more information. + + .PARAMETER TcpEnabled + See the notes section for more information. + + .PARAMETER RsInstallMode + See the notes section for more information. + + .PARAMETER RSSvcAccount + See the notes section for more information. + + .PARAMETER RSSvcPassword + See the notes section for more information. + + .PARAMETER RSSvcStartupType + See the notes section for more information. + + .PARAMETER MPYCacheDirectory + See the notes section for more information. + + .PARAMETER MRCacheDirectory + See the notes section for more information. + + .PARAMETER SqlInstJava + See the notes section for more information. + + .PARAMETER SqlJavaDir + See the notes section for more information. + + .PARAMETER FailoverClusterGroup + See the notes section for more information. + + .PARAMETER FailoverClusterDisks + See the notes section for more information. + + .PARAMETER FailoverClusterNetworkName + See the notes section for more information. + + .PARAMETER FailoverClusterIPAddresses + See the notes section for more information. + + .PARAMETER ConfirmIPDependencyChange + See the notes section for more information. + + .PARAMETER FailoverClusterRollOwnership + See the notes section for more information. + + .PARAMETER AzureSubscriptionId + See the notes section for more information. + + .PARAMETER AzureResourceGroup + See the notes section for more information. + + .PARAMETER AzureRegion + See the notes section for more information. + + .PARAMETER AzureTenantId + See the notes section for more information. + + .PARAMETER AzureServicePrincipal + See the notes section for more information. + + .PARAMETER AzureServicePrincipalSecret + See the notes section for more information. + + .PARAMETER AzureArcProxy + See the notes section for more information. + + .PARAMETER SkipRules + See the notes section for more information. + + .PARAMETER ProductCoveredBySA + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -150,16 +456,16 @@ Removes the node from the failover cluster of the instance 'MyInstance'. .NOTES - All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is - a link in the comment-based help that points to the SQL Server command line - setup documentation which will stay relevant. + The parameters are intentionally not described since it would take a lot + of effort to keep them up to date. Instead there is a link that points to + the SQL Server command line setup documentation which will stay relevant. For RebuildDatabase the parameter SAPwd must be set if the instance was installed with SecurityMode = 'SQL'. #> function Invoke-SetupAction { + # cSpell: ignore PBDMS Admini AZUREEXTENSION [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')] [OutputType()] param diff --git a/source/Public/Add-SqlDscNode.ps1 b/source/Public/Add-SqlDscNode.ps1 index bddcf0b8e..810f696ae 100644 --- a/source/Public/Add-SqlDscNode.ps1 +++ b/source/Public/Add-SqlDscNode.ps1 @@ -18,6 +18,93 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER IAcknowledgeEntCalLimits + See the notes section for more information. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER Enu + See the notes section for more information. + + .PARAMETER UpdateEnabled + See the notes section for more information. + + .PARAMETER UpdateSource + See the notes section for more information. + + .PARAMETER PBEngSvcAccount + See the notes section for more information. + + .PARAMETER PBEngSvcPassword + See the notes section for more information. + + .PARAMETER PBEngSvcStartupType + See the notes section for more information. + + .PARAMETER PBStartPortRange + See the notes section for more information. + + .PARAMETER PBEndPortRange + See the notes section for more information. + + .PARAMETER PBScaleOut + See the notes section for more information. + + .PARAMETER ProductKey + See the notes section for more information. + + .PARAMETER AgtSvcAccount + See the notes section for more information. + + .PARAMETER AgtSvcPassword + See the notes section for more information. + + .PARAMETER ASSvcAccount + See the notes section for more information. + + .PARAMETER ASSvcPassword + See the notes section for more information. + + .PARAMETER SqlSvcAccount + See the notes section for more information. + + .PARAMETER SqlSvcPassword + See the notes section for more information. + + .PARAMETER ISSvcAccount + See the notes section for more information. + + .PARAMETER ISSvcPassword + See the notes section for more information. + + .PARAMETER RsInstallMode + See the notes section for more information. + + .PARAMETER RSSvcAccount + See the notes section for more information. + + .PARAMETER RSSvcPassword + See the notes section for more information. + + .PARAMETER FailoverClusterIPAddresses + See the notes section for more information. + + .PARAMETER ConfirmIPDependencyChange + See the notes section for more information. + + .PARAMETER ProductCoveredBySA + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -30,13 +117,13 @@ Adds the current node's SQL Server instance 'MyInstance' to the Failover Cluster instance. .NOTES - All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is - a link in the comment-based help that points to the SQL Server command line - setup documentation which will stay relevant. + The parameters are intentionally not described since it would take a lot + of effort to keep them up to date. Instead there is a link that points to + the SQL Server command line setup documentation which will stay relevant. #> function Add-SqlDscNode { + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'Because ShouldProcess is used in Invoke-SetupAction')] [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'Because ShouldProcess is used in Invoke-SetupAction')] [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')] [OutputType()] diff --git a/source/Public/Complete-SqlDscFailoverCluster.ps1 b/source/Public/Complete-SqlDscFailoverCluster.ps1 index c71cbd8f1..41ab66f19 100644 --- a/source/Public/Complete-SqlDscFailoverCluster.ps1 +++ b/source/Public/Complete-SqlDscFailoverCluster.ps1 @@ -15,6 +15,117 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER Enu + See the notes section for more information. + + .PARAMETER ProductKey + See the notes section for more information. + + .PARAMETER ASBackupDir + See the notes section for more information. + + .PARAMETER ASCollation + See the notes section for more information. + + .PARAMETER ASConfigDir + See the notes section for more information. + + .PARAMETER ASDataDir + See the notes section for more information. + + .PARAMETER ASLogDir + See the notes section for more information. + + .PARAMETER ASTempDir + See the notes section for more information. + + .PARAMETER ASServerMode + See the notes section for more information. + + .PARAMETER ASSysAdminAccounts + See the notes section for more information. + + .PARAMETER ASProviderMSOLAP + See the notes section for more information. + + .PARAMETER InstallSqlDataDir + See the notes section for more information. + + .PARAMETER SqlBackupDir + See the notes section for more information. + + .PARAMETER SecurityMode + See the notes section for more information. + + .PARAMETER SAPwd + See the notes section for more information. + + .PARAMETER SqlCollation + See the notes section for more information. + + .PARAMETER SqlSysAdminAccounts + See the notes section for more information. + + .PARAMETER SqlTempDbDir + See the notes section for more information. + + .PARAMETER SqlTempDbLogDir + See the notes section for more information. + + .PARAMETER SqlTempDbFileCount + See the notes section for more information. + + .PARAMETER SqlTempDbFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbFileGrowth + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileGrowth + See the notes section for more information. + + .PARAMETER SqlUserDbDir + See the notes section for more information. + + .PARAMETER SqlUserDbLogDir + See the notes section for more information. + + .PARAMETER RsInstallMode + See the notes section for more information. + + .PARAMETER FailoverClusterGroup + See the notes section for more information. + + .PARAMETER FailoverClusterDisks + See the notes section for more information. + + .PARAMETER FailoverClusterNetworkName + See the notes section for more information. + + .PARAMETER FailoverClusterIPAddresses + See the notes section for more information. + + .PARAMETER ConfirmIPDependencyChange + See the notes section for more information. + + .PARAMETER ProductCoveredBySA + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -28,10 +139,9 @@ Failover Cluster instance. .NOTES - All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is - a link in the comment-based help that points to the SQL Server command line - setup documentation which will stay relevant. + The parameters are intentionally not described since it would take a lot + of effort to keep them up to date. Instead there is a link that points to + the SQL Server command line setup documentation which will stay relevant. #> function Complete-SqlDscFailoverCluster { diff --git a/source/Public/Complete-SqlDscImage.ps1 b/source/Public/Complete-SqlDscImage.ps1 index 55a43f517..17b32d873 100644 --- a/source/Public/Complete-SqlDscImage.ps1 +++ b/source/Public/Complete-SqlDscImage.ps1 @@ -19,6 +19,141 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER Enu + See the notes section for more information. + + .PARAMETER InstanceId + See the notes section for more information. + + .PARAMETER PBEngSvcAccount + See the notes section for more information. + + .PARAMETER PBEngSvcPassword + See the notes section for more information. + + .PARAMETER PBEngSvcStartupType + See the notes section for more information. + + .PARAMETER PBStartPortRange + See the notes section for more information. + + .PARAMETER PBEndPortRange + See the notes section for more information. + + .PARAMETER PBScaleOut + See the notes section for more information. + + .PARAMETER ProductKey + See the notes section for more information. + + .PARAMETER AgtSvcAccount + See the notes section for more information. + + .PARAMETER AgtSvcPassword + See the notes section for more information. + + .PARAMETER AgtSvcStartupType + See the notes section for more information. + + .PARAMETER BrowserSvcStartupType + See the notes section for more information. + + .PARAMETER EnableRanU + See the notes section for more information. + + .PARAMETER InstallSqlDataDir + See the notes section for more information. + + .PARAMETER SqlBackupDir + See the notes section for more information. + + .PARAMETER SecurityMode + See the notes section for more information. + + .PARAMETER SAPwd + See the notes section for more information. + + .PARAMETER SqlCollation + See the notes section for more information. + + .PARAMETER SqlSvcAccount + See the notes section for more information. + + .PARAMETER SqlSvcPassword + See the notes section for more information. + + .PARAMETER SqlSvcStartupType + See the notes section for more information. + + .PARAMETER SqlSysAdminAccounts + See the notes section for more information. + + .PARAMETER SqlTempDbDir + See the notes section for more information. + + .PARAMETER SqlTempDbLogDir + See the notes section for more information. + + .PARAMETER SqlTempDbFileCount + See the notes section for more information. + + .PARAMETER SqlTempDbFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbFileGrowth + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileGrowth + See the notes section for more information. + + .PARAMETER SqlUserDbDir + See the notes section for more information. + + .PARAMETER SqlUserDbLogDir + See the notes section for more information. + + .PARAMETER FileStreamLevel + See the notes section for more information. + + .PARAMETER FileStreamShareName + See the notes section for more information. + + .PARAMETER NpEnabled + See the notes section for more information. + + .PARAMETER TcpEnabled + See the notes section for more information. + + .PARAMETER RsInstallMode + See the notes section for more information. + + .PARAMETER RSSvcAccount + See the notes section for more information. + + .PARAMETER RSSvcPassword + See the notes section for more information. + + .PARAMETER RSSvcStartupType + See the notes section for more information. + + .PARAMETER ProductCoveredBySA + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -32,10 +167,9 @@ was prepared using `Install-SqlDscServer` with the parameter `-PrepareImage`. .NOTES - All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is - a link in the comment-based help that points to the SQL Server command line - setup documentation which will stay relevant. + The parameters are intentionally not described since it would take a lot + of effort to keep them up to date. Instead there is a link that points to + the SQL Server command line setup documentation which will stay relevant. #> function Complete-SqlDscImage { diff --git a/source/Public/Connect-SqlDscDatabaseEngine.ps1 b/source/Public/Connect-SqlDscDatabaseEngine.ps1 index 866ff2799..14eabf576 100644 --- a/source/Public/Connect-SqlDscDatabaseEngine.ps1 +++ b/source/Public/Connect-SqlDscDatabaseEngine.ps1 @@ -2,6 +2,10 @@ .SYNOPSIS Connect to a SQL Server Database Engine and return the server object. + .DESCRIPTION + This command connects to a SQL Server Database Engine instance and returns + the Server object. + .PARAMETER ServerName String containing the host name of the SQL Server to connect to. Default value is the current computer name. @@ -43,7 +47,7 @@ Connects to the instance 'MyInstance' on the server 'sql.company.local'. .OUTPUTS - None. + `[Microsoft.SqlServer.Management.Smo.Server]` #> function Connect-SqlDscDatabaseEngine { diff --git a/source/Public/ConvertFrom-SqlDscDatabasePermission.ps1 b/source/Public/ConvertFrom-SqlDscDatabasePermission.ps1 index ad7b9aa97..7121691b2 100644 --- a/source/Public/ConvertFrom-SqlDscDatabasePermission.ps1 +++ b/source/Public/ConvertFrom-SqlDscDatabasePermission.ps1 @@ -3,6 +3,10 @@ Converts a DatabasePermission object into an object of the type Microsoft.SqlServer.Management.Smo.DatabasePermissionSet. + .DESCRIPTION + Converts a DatabasePermission object into an object of the type + Microsoft.SqlServer.Management.Smo.DatabasePermissionSet. + .PARAMETER Permission Specifies a DatabasePermission object. diff --git a/source/Public/ConvertFrom-SqlDscServerPermission.ps1 b/source/Public/ConvertFrom-SqlDscServerPermission.ps1 index 61f4b3b12..a24b7c4f6 100644 --- a/source/Public/ConvertFrom-SqlDscServerPermission.ps1 +++ b/source/Public/ConvertFrom-SqlDscServerPermission.ps1 @@ -3,6 +3,10 @@ Converts a ServerPermission object into an object of the type Microsoft.SqlServer.Management.Smo.ServerPermissionSet. + .DESCRIPTION + Converts a ServerPermission object into an object of the type + Microsoft.SqlServer.Management.Smo.ServerPermissionSet. + .PARAMETER Permission Specifies a ServerPermission object. diff --git a/source/Public/ConvertTo-SqlDscDatabasePermission.ps1 b/source/Public/ConvertTo-SqlDscDatabasePermission.ps1 index 093b8510c..7ebd5a738 100644 --- a/source/Public/ConvertTo-SqlDscDatabasePermission.ps1 +++ b/source/Public/ConvertTo-SqlDscDatabasePermission.ps1 @@ -3,6 +3,10 @@ Converts a collection of Microsoft.SqlServer.Management.Smo.DatabasePermissionInfo objects into an array of DatabasePermission objects. + .DESCRIPTION + Converts a collection of Microsoft.SqlServer.Management.Smo.DatabasePermissionInfo + objects into an array of DatabasePermission objects. + .PARAMETER DatabasePermissionInfo Specifies a collection of Microsoft.SqlServer.Management.Smo.DatabasePermissionInfo objects. diff --git a/source/Public/ConvertTo-SqlDscServerPermission.ps1 b/source/Public/ConvertTo-SqlDscServerPermission.ps1 index 9198724e3..f45dd3c9e 100644 --- a/source/Public/ConvertTo-SqlDscServerPermission.ps1 +++ b/source/Public/ConvertTo-SqlDscServerPermission.ps1 @@ -3,6 +3,10 @@ Converts a collection of Microsoft.SqlServer.Management.Smo.ServerPermissionInfo objects into an array of ServerPermission objects. + .DESCRIPTION + Converts a collection of Microsoft.SqlServer.Management.Smo.ServerPermissionInfo + objects into an array of ServerPermission objects. + .PARAMETER ServerPermissionInfo Specifies a collection of Microsoft.SqlServer.Management.Smo.ServerPermissionInfo objects. diff --git a/source/Public/Disable-SqlDscAudit.ps1 b/source/Public/Disable-SqlDscAudit.ps1 index c77eef43d..dca7e3bfa 100644 --- a/source/Public/Disable-SqlDscAudit.ps1 +++ b/source/Public/Disable-SqlDscAudit.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Disables a server audit. + .DESCRIPTION + This command disables a server audit in a SQL Server Database Engine instance. + .PARAMETER ServerObject Specifies current server connection object. @@ -65,30 +68,33 @@ function Disable-SqlDscAudit $Refresh ) - if ($Force.IsPresent) - { - $ConfirmPreference = 'None' - } - - if ($PSCmdlet.ParameterSetName -eq 'ServerObject') + process { - $getSqlDscAuditParameters = @{ - ServerObject = $ServerObject - Name = $Name - Refresh = $Refresh - ErrorAction = 'Stop' + if ($Force.IsPresent) + { + $ConfirmPreference = 'None' } - # If this command does not find the audit it will throw an exception. - $AuditObject = Get-SqlDscAudit @getSqlDscAuditParameters - } + if ($PSCmdlet.ParameterSetName -eq 'ServerObject') + { + $getSqlDscAuditParameters = @{ + ServerObject = $ServerObject + Name = $Name + Refresh = $Refresh + ErrorAction = 'Stop' + } + + # If this command does not find the audit it will throw an exception. + $AuditObject = Get-SqlDscAudit @getSqlDscAuditParameters + } - $verboseDescriptionMessage = $script:localizedData.Audit_Disable_ShouldProcessVerboseDescription -f $AuditObject.Name, $AuditObject.Parent.InstanceName - $verboseWarningMessage = $script:localizedData.Audit_Disable_ShouldProcessVerboseWarning -f $AuditObject.Name - $captionMessage = $script:localizedData.Audit_Disable_ShouldProcessCaption + $verboseDescriptionMessage = $script:localizedData.Audit_Disable_ShouldProcessVerboseDescription -f $AuditObject.Name, $AuditObject.Parent.InstanceName + $verboseWarningMessage = $script:localizedData.Audit_Disable_ShouldProcessVerboseWarning -f $AuditObject.Name + $captionMessage = $script:localizedData.Audit_Disable_ShouldProcessCaption - if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) - { - $AuditObject.Disable() + if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) + { + $AuditObject.Disable() + } } } diff --git a/source/Public/Enable-SqlDscAudit.ps1 b/source/Public/Enable-SqlDscAudit.ps1 index 6e6a37a26..f492d912c 100644 --- a/source/Public/Enable-SqlDscAudit.ps1 +++ b/source/Public/Enable-SqlDscAudit.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Enables a server audit. + .DESCRIPTION + This command enables a server audit in a SQL Server Database Engine instance. + .PARAMETER ServerObject Specifies current server connection object. @@ -65,30 +68,33 @@ function Enable-SqlDscAudit $Refresh ) - if ($Force.IsPresent) - { - $ConfirmPreference = 'None' - } - - if ($PSCmdlet.ParameterSetName -eq 'ServerObject') + process { - $getSqlDscAuditParameters = @{ - ServerObject = $ServerObject - Name = $Name - Refresh = $Refresh - ErrorAction = 'Stop' + if ($Force.IsPresent) + { + $ConfirmPreference = 'None' } - # If this command does not find the audit it will throw an exception. - $AuditObject = Get-SqlDscAudit @getSqlDscAuditParameters - } + if ($PSCmdlet.ParameterSetName -eq 'ServerObject') + { + $getSqlDscAuditParameters = @{ + ServerObject = $ServerObject + Name = $Name + Refresh = $Refresh + ErrorAction = 'Stop' + } + + # If this command does not find the audit it will throw an exception. + $AuditObject = Get-SqlDscAudit @getSqlDscAuditParameters + } - $verboseDescriptionMessage = $script:localizedData.Audit_Enable_ShouldProcessVerboseDescription -f $AuditObject.Name, $AuditObject.Parent.InstanceName - $verboseWarningMessage = $script:localizedData.Audit_Enable_ShouldProcessVerboseWarning -f $AuditObject.Name - $captionMessage = $script:localizedData.Audit_Enable_ShouldProcessCaption + $verboseDescriptionMessage = $script:localizedData.Audit_Enable_ShouldProcessVerboseDescription -f $AuditObject.Name, $AuditObject.Parent.InstanceName + $verboseWarningMessage = $script:localizedData.Audit_Enable_ShouldProcessVerboseWarning -f $AuditObject.Name + $captionMessage = $script:localizedData.Audit_Enable_ShouldProcessCaption - if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) - { - $AuditObject.Enable() + if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) + { + $AuditObject.Enable() + } } } diff --git a/source/Public/Get-SqlDscAudit.ps1 b/source/Public/Get-SqlDscAudit.ps1 index 4a8943d6f..77f82a3c3 100644 --- a/source/Public/Get-SqlDscAudit.ps1 +++ b/source/Public/Get-SqlDscAudit.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Get server audit. + .DESCRIPTION + This command gets a server audit from a SQL Server Database Engine instance. + .PARAMETER ServerObject Specifies current server connection object. @@ -22,7 +25,7 @@ Get the audit named **MyFileAudit**. .OUTPUTS - `[Microsoft.SqlServer.Management.Smo.Audit]`. + `[Microsoft.SqlServer.Management.Smo.Audit]` #> function Get-SqlDscAudit { @@ -44,27 +47,30 @@ function Get-SqlDscAudit $Refresh ) - if ($Refresh.IsPresent) + process { - # Make sure the audits are up-to-date to get any newly created audits. - $ServerObject.Audits.Refresh() - } + if ($Refresh.IsPresent) + { + # Make sure the audits are up-to-date to get any newly created audits. + $ServerObject.Audits.Refresh() + } - $auditObject = $ServerObject.Audits[$Name] + $auditObject = $ServerObject.Audits[$Name] - if (-not $AuditObject) - { - $missingAuditMessage = $script:localizedData.Audit_Missing -f $Name + if (-not $AuditObject) + { + $missingAuditMessage = $script:localizedData.Audit_Missing -f $Name + + $writeErrorParameters = @{ + Message = $missingAuditMessage + Category = 'InvalidOperation' + ErrorId = 'GSDA0001' # cspell: disable-line + TargetObject = $Name + } - $writeErrorParameters = @{ - Message = $missingAuditMessage - Category = 'InvalidOperation' - ErrorId = 'GSDA0001' # cspell: disable-line - TargetObject = $Name + Write-Error @writeErrorParameters } - Write-Error @writeErrorParameters + return $auditObject } - - return $auditObject } diff --git a/source/Public/Get-SqlDscDatabasePermission.ps1 b/source/Public/Get-SqlDscDatabasePermission.ps1 index 8f9e3f49d..b27a1f7f6 100644 --- a/source/Public/Get-SqlDscDatabasePermission.ps1 +++ b/source/Public/Get-SqlDscDatabasePermission.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Returns the current permissions for the database principal. + .DESCRIPTION + Returns the current permissions for the database principal. + .PARAMETER ServerObject Specifies current server connection object. @@ -53,43 +56,47 @@ function Get-SqlDscDatabasePermission $Name ) - $getSqlDscDatabasePermissionResult = $null - - $sqlDatabaseObject = $null - - if ($ServerObject.Databases) + # cSpell: ignore GSDDP + process { - $sqlDatabaseObject = $ServerObject.Databases[$DatabaseName] - } + $getSqlDscDatabasePermissionResult = $null - if ($sqlDatabaseObject) - { - $testSqlDscIsDatabasePrincipalParameters = @{ - ServerObject = $ServerObject - DatabaseName = $DatabaseName - Name = $Name - ExcludeFixedRoles = $true - } + $sqlDatabaseObject = $null - $isDatabasePrincipal = Test-SqlDscIsDatabasePrincipal @testSqlDscIsDatabasePrincipalParameters + if ($ServerObject.Databases) + { + $sqlDatabaseObject = $ServerObject.Databases[$DatabaseName] + } - if ($isDatabasePrincipal) + if ($sqlDatabaseObject) { - $getSqlDscDatabasePermissionResult = $sqlDatabaseObject.EnumDatabasePermissions($Name) + $testSqlDscIsDatabasePrincipalParameters = @{ + ServerObject = $ServerObject + DatabaseName = $DatabaseName + Name = $Name + ExcludeFixedRoles = $true + } + + $isDatabasePrincipal = Test-SqlDscIsDatabasePrincipal @testSqlDscIsDatabasePrincipalParameters + + if ($isDatabasePrincipal) + { + $getSqlDscDatabasePermissionResult = $sqlDatabaseObject.EnumDatabasePermissions($Name) + } + else + { + $missingPrincipalMessage = $script:localizedData.DatabasePermission_MissingPrincipal -f $Name, $DatabaseName + + Write-Error -Message $missingPrincipalMessage -Category 'InvalidOperation' -ErrorId 'GSDDP0001' -TargetObject $Name + } } else { - $missingPrincipalMessage = $script:localizedData.DatabasePermission_MissingPrincipal -f $Name, $DatabaseName + $missingDatabaseMessage = $script:localizedData.DatabasePermission_MissingDatabase -f $DatabaseName - Write-Error -Message $missingPrincipalMessage -Category 'InvalidOperation' -ErrorId 'GSDDP0001' -TargetObject $Name + Write-Error -Message $missingDatabaseMessage -Category 'InvalidOperation' -ErrorId 'GSDDP0002' -TargetObject $DatabaseName } - } - else - { - $missingDatabaseMessage = $script:localizedData.DatabasePermission_MissingDatabase -f $DatabaseName - Write-Error -Message $missingDatabaseMessage -Category 'InvalidOperation' -ErrorId 'GSDDP0002' -TargetObject $DatabaseName + return , [Microsoft.SqlServer.Management.Smo.DatabasePermissionInfo[]] $getSqlDscDatabasePermissionResult } - - return , [Microsoft.SqlServer.Management.Smo.DatabasePermissionInfo[]] $getSqlDscDatabasePermissionResult } diff --git a/source/Public/Get-SqlDscServerPermission.ps1 b/source/Public/Get-SqlDscServerPermission.ps1 index 849eea315..6f49c6cb0 100644 --- a/source/Public/Get-SqlDscServerPermission.ps1 +++ b/source/Public/Get-SqlDscServerPermission.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Returns the current permissions for the principal. + .DESCRIPTION + Returns the current permissions for the principal. + .PARAMETER ServerObject Specifies current server connection object. @@ -42,25 +45,29 @@ function Get-SqlDscServerPermission $Name ) - $getSqlDscServerPermissionResult = $null + # cSpell: ignore GSDSP + process + { + $getSqlDscServerPermissionResult = $null - $testSqlDscIsLoginParameters = @{ - ServerObject = $ServerObject - Name = $Name - } + $testSqlDscIsLoginParameters = @{ + ServerObject = $ServerObject + Name = $Name + } - $isLogin = Test-SqlDscIsLogin @testSqlDscIsLoginParameters + $isLogin = Test-SqlDscIsLogin @testSqlDscIsLoginParameters - if ($isLogin) - { - $getSqlDscServerPermissionResult = $ServerObject.EnumServerPermissions($Name) - } - else - { - $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $Name, $ServerObject.InstanceName + if ($isLogin) + { + $getSqlDscServerPermissionResult = $ServerObject.EnumServerPermissions($Name) + } + else + { + $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $Name, $ServerObject.InstanceName - Write-Error -Message $missingPrincipalMessage -Category 'InvalidOperation' -ErrorId 'GSDSP0001' -TargetObject $Name - } + Write-Error -Message $missingPrincipalMessage -Category 'InvalidOperation' -ErrorId 'GSDSP0001' -TargetObject $Name + } - return , [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]] $getSqlDscServerPermissionResult + return , [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]] $getSqlDscServerPermissionResult + } } diff --git a/source/Public/Initialize-SqlDscRebuildDatabase.ps1 b/source/Public/Initialize-SqlDscRebuildDatabase.ps1 index 8866d27bf..4a0af444a 100644 --- a/source/Public/Initialize-SqlDscRebuildDatabase.ps1 +++ b/source/Public/Initialize-SqlDscRebuildDatabase.ps1 @@ -12,6 +12,48 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER SAPwd + See the notes section for more information. + + .PARAMETER SqlCollation + See the notes section for more information. + + .PARAMETER SqlSysAdminAccounts + See the notes section for more information. + + .PARAMETER SqlTempDbDir + See the notes section for more information. + + .PARAMETER SqlTempDbLogDir + See the notes section for more information. + + .PARAMETER SqlTempDbFileCount + See the notes section for more information. + + .PARAMETER SqlTempDbFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbFileGrowth + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileGrowth + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -24,10 +66,9 @@ Rebuilds the database of the instance 'MyInstance'. .NOTES - All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is - a link in the comment-based help that points to the SQL Server command line - setup documentation which will stay relevant. + The parameters are intentionally not described since it would take a lot + of effort to keep them up to date. Instead there is a link that points to + the SQL Server command line setup documentation which will stay relevant. For RebuildDatabase the parameter SAPwd must be set if the instance was installed with SecurityMode = 'SQL'. diff --git a/source/Public/Install-SqlDscServer.ps1 b/source/Public/Install-SqlDscServer.ps1 index 53a437874..03785e2b1 100644 --- a/source/Public/Install-SqlDscServer.ps1 +++ b/source/Public/Install-SqlDscServer.ps1 @@ -45,6 +45,309 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER SuppressPrivacyStatementNotice + See the notes section for more information. + + .PARAMETER IAcknowledgeEntCalLimits + See the notes section for more information. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER Enu + See the notes section for more information. + + .PARAMETER UpdateEnabled + See the notes section for more information. + + .PARAMETER UpdateSource + See the notes section for more information. + + .PARAMETER Features + See the notes section for more information. + + .PARAMETER Role + See the notes section for more information. + + .PARAMETER InstallSharedDir + See the notes section for more information. + + .PARAMETER InstallSharedWowDir + See the notes section for more information. + + .PARAMETER InstanceDir + See the notes section for more information. + + .PARAMETER InstanceId + See the notes section for more information. + + .PARAMETER PBEngSvcAccount + See the notes section for more information. + + .PARAMETER PBEngSvcPassword + See the notes section for more information. + + .PARAMETER PBEngSvcStartupType + See the notes section for more information. + + .PARAMETER PBDMSSvcAccount + See the notes section for more information. + + .PARAMETER PBDMSSvcPassword + See the notes section for more information. + + .PARAMETER PBDMSSvcStartupType + See the notes section for more information. + + .PARAMETER PBStartPortRange + See the notes section for more information. + + .PARAMETER PBEndPortRange + See the notes section for more information. + + .PARAMETER PBScaleOut + See the notes section for more information. + + .PARAMETER ProductKey + See the notes section for more information. + + .PARAMETER AgtSvcAccount + See the notes section for more information. + + .PARAMETER AgtSvcPassword + See the notes section for more information. + + .PARAMETER AgtSvcStartupType + See the notes section for more information. + + .PARAMETER ASBackupDir + See the notes section for more information. + + .PARAMETER ASCollation + See the notes section for more information. + + .PARAMETER ASConfigDir + See the notes section for more information. + + .PARAMETER ASDataDir + See the notes section for more information. + + .PARAMETER ASLogDir + See the notes section for more information. + + .PARAMETER ASTempDir + See the notes section for more information. + + .PARAMETER ASServerMode + See the notes section for more information. + + .PARAMETER ASSvcAccount + See the notes section for more information. + + .PARAMETER ASSvcPassword + See the notes section for more information. + + .PARAMETER ASSvcStartupType + See the notes section for more information. + + .PARAMETER ASSysAdminAccounts + See the notes section for more information. + + .PARAMETER ASProviderMSOLAP + See the notes section for more information. + + .PARAMETER FarmAccount + See the notes section for more information. + + .PARAMETER FarmPassword + See the notes section for more information. + + .PARAMETER Passphrase + See the notes section for more information. + + .PARAMETER FarmAdminiPort + See the notes section for more information. + + .PARAMETER BrowserSvcStartupType + See the notes section for more information. + + .PARAMETER FTUpgradeOption + See the notes section for more information. + + .PARAMETER EnableRanU + See the notes section for more information. + + .PARAMETER InstallSqlDataDir + See the notes section for more information. + + .PARAMETER SqlBackupDir + See the notes section for more information. + + .PARAMETER SecurityMode + See the notes section for more information. + + .PARAMETER SAPwd + See the notes section for more information. + + .PARAMETER SqlCollation + See the notes section for more information. + + .PARAMETER AddCurrentUserAsSqlAdmin + See the notes section for more information. + + .PARAMETER SqlSvcAccount + See the notes section for more information. + + .PARAMETER SqlSvcPassword + See the notes section for more information. + + .PARAMETER SqlSvcStartupType + See the notes section for more information. + + .PARAMETER SqlSysAdminAccounts + See the notes section for more information. + + .PARAMETER SqlTempDbDir + See the notes section for more information. + + .PARAMETER SqlTempDbLogDir + See the notes section for more information. + + .PARAMETER SqlTempDbFileCount + See the notes section for more information. + + .PARAMETER SqlTempDbFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbFileGrowth + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileSize + See the notes section for more information. + + .PARAMETER SqlTempDbLogFileGrowth + See the notes section for more information. + + .PARAMETER SqlUserDbDir + See the notes section for more information. + + .PARAMETER SqlSvcInstantFileInit + See the notes section for more information. + + .PARAMETER SqlUserDbLogDir + See the notes section for more information. + + .PARAMETER SqlMaxDop + See the notes section for more information. + + .PARAMETER UseSqlRecommendedMemoryLimits + See the notes section for more information. + + .PARAMETER SqlMinMemory + See the notes section for more information. + + .PARAMETER SqlMaxMemory + See the notes section for more information. + + .PARAMETER FileStreamLevel + See the notes section for more information. + + .PARAMETER FileStreamShareName + See the notes section for more information. + + .PARAMETER ISSvcAccount + See the notes section for more information. + + .PARAMETER ISSvcPassword + See the notes section for more information. + + .PARAMETER ISSvcStartupType + See the notes section for more information. + + .PARAMETER AllowUpgradeForSSRSSharePointMode + See the notes section for more information. + + .PARAMETER NpEnabled + See the notes section for more information. + + .PARAMETER TcpEnabled + See the notes section for more information. + + .PARAMETER RsInstallMode + See the notes section for more information. + + .PARAMETER RSSvcAccount + See the notes section for more information. + + .PARAMETER RSSvcPassword + See the notes section for more information. + + .PARAMETER RSSvcStartupType + See the notes section for more information. + + .PARAMETER MPYCacheDirectory + See the notes section for more information. + + .PARAMETER MRCacheDirectory + See the notes section for more information. + + .PARAMETER SqlInstJava + See the notes section for more information. + + .PARAMETER SqlJavaDir + See the notes section for more information. + + .PARAMETER FailoverClusterGroup + See the notes section for more information. + + .PARAMETER FailoverClusterDisks + See the notes section for more information. + + .PARAMETER FailoverClusterNetworkName + See the notes section for more information. + + .PARAMETER FailoverClusterIPAddresses + See the notes section for more information. + + .PARAMETER FailoverClusterRollOwnership + See the notes section for more information. + + .PARAMETER AzureSubscriptionId + See the notes section for more information. + + .PARAMETER AzureResourceGroup + See the notes section for more information. + + .PARAMETER AzureRegion + See the notes section for more information. + + .PARAMETER AzureTenantId + See the notes section for more information. + + .PARAMETER AzureServicePrincipal + See the notes section for more information. + + .PARAMETER AzureServicePrincipalSecret + See the notes section for more information. + + .PARAMETER AzureArcProxy + See the notes section for more information. + + .PARAMETER SkipRules + See the notes section for more information. + + .PARAMETER ProductCoveredBySA + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -97,13 +400,13 @@ Prepares to installs the database engine in a failover cluster with the instance name 'MyInstance'. .NOTES - All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is - a link in the comment-based help that points to the SQL Server command line - setup documentation which will stay relevant. + The parameters are intentionally not described since it would take a lot + of effort to keep them up to date. Instead there is a link that points to + the SQL Server command line setup documentation which will stay relevant. #> function Install-SqlDscServer { + # cSpell: ignore PBDMS Admini AZUREEXTENSION [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'Because ShouldProcess is used in Invoke-SetupAction')] [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')] [OutputType()] diff --git a/source/Public/Invoke-SqlDscQuery.ps1 b/source/Public/Invoke-SqlDscQuery.ps1 index 221c18420..ae44cc7e5 100644 --- a/source/Public/Invoke-SqlDscQuery.ps1 +++ b/source/Public/Invoke-SqlDscQuery.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Executes a query on the specified database. + .DESCRIPTION + Executes a query on the specified database. + .PARAMETER ServerObject Specifies current server connection object. @@ -87,26 +90,29 @@ function Invoke-SqlDscQuery $RedactText ) - $invokeQueryParameters = @{ - SqlServerObject = $ServerObject - Database = $DatabaseName - Query = $Query - } - - if ($PSBoundParameters.ContainsKey('PassThru')) + process { - $invokeQueryParameters.WithResults = $PassThru + $invokeQueryParameters = @{ + SqlServerObject = $ServerObject + Database = $DatabaseName + Query = $Query + } + + if ($PSBoundParameters.ContainsKey('PassThru')) + { + $invokeQueryParameters.WithResults = $PassThru + } + + if ($PSBoundParameters.ContainsKey('StatementTimeout')) + { + $invokeQueryParameters.StatementTimeout = $StatementTimeout + } + + if ($PSBoundParameters.ContainsKey('RedactText')) + { + $invokeQueryParameters.RedactText = $RedactText + } + + return (Invoke-Query @invokeQueryParameters) } - - if ($PSBoundParameters.ContainsKey('StatementTimeout')) - { - $invokeQueryParameters.StatementTimeout = $StatementTimeout - } - - if ($PSBoundParameters.ContainsKey('RedactText')) - { - $invokeQueryParameters.RedactText = $RedactText - } - - return (Invoke-Query @invokeQueryParameters) } diff --git a/source/Public/New-SqlDscAudit.ps1 b/source/Public/New-SqlDscAudit.ps1 index 1effcb200..99bad6a49 100644 --- a/source/Public/New-SqlDscAudit.ps1 +++ b/source/Public/New-SqlDscAudit.ps1 @@ -2,13 +2,16 @@ .SYNOPSIS Creates a server audit. + .DESCRIPTION + This command creates a server audit on a SQL Server Database Engine instance. + .PARAMETER ServerObject Specifies current server connection object. .PARAMETER Name Specifies the name of the server audit to be added. - .PARAMETER Filter + .PARAMETER AuditFilter Specifies the filter that should be used on the audit. See [predicate expression](https://docs.microsoft.com/en-us/sql/t-sql/statements/create-server-audit-transact-sql) how to write the syntax for the filter. @@ -39,7 +42,7 @@ Specifies the log location where the audit should write to. This can be SecurityLog or ApplicationLog. - .PARAMETER FilePath + .PARAMETER Path Specifies the location where te log files wil be placed. .PARAMETER ReserveDiskSpace @@ -60,6 +63,9 @@ Specifies the amount of files on disk before SQL Server starts reusing the files. If not specified then it is set to unlimited. + .PARAMETER PassThru + If specified the created audit object will be returned. + .OUTPUTS `[Microsoft.SqlServer.Management.Smo.Audit]` is passing parameter **PassThru**, otherwise none. @@ -194,116 +200,119 @@ function New-SqlDscAudit $MaximumRolloverFiles ) - if ($Force.IsPresent) + process { - $ConfirmPreference = 'None' - } + if ($Force.IsPresent) + { + $ConfirmPreference = 'None' + } - $getSqlDscAuditParameters = @{ - ServerObject = $ServerObject - Name = $Name - Refresh = $Refresh - ErrorAction = 'SilentlyContinue' - } + $getSqlDscAuditParameters = @{ + ServerObject = $ServerObject + Name = $Name + Refresh = $Refresh + ErrorAction = 'SilentlyContinue' + } - $auditObject = Get-SqlDscAudit @getSqlDscAuditParameters + $auditObject = Get-SqlDscAudit @getSqlDscAuditParameters - if ($auditObject) - { - $auditAlreadyPresentMessage = $script:localizedData.Audit_AlreadyPresent -f $Name - - $PSCmdlet.ThrowTerminatingError( - [System.Management.Automation.ErrorRecord]::new( - $auditAlreadyPresentMessage, - 'NSDA0001', # cspell: disable-line - [System.Management.Automation.ErrorCategory]::InvalidOperation, - $DatabaseName + if ($auditObject) + { + $auditAlreadyPresentMessage = $script:localizedData.Audit_AlreadyPresent -f $Name + + $PSCmdlet.ThrowTerminatingError( + [System.Management.Automation.ErrorRecord]::new( + $auditAlreadyPresentMessage, + 'NSDA0001', # cspell: disable-line + [System.Management.Automation.ErrorCategory]::InvalidOperation, + $DatabaseName + ) ) - ) - } + } - $auditObject = New-Object -TypeName 'Microsoft.SqlServer.Management.Smo.Audit' -ArgumentList @($ServerObject, $Name) + $auditObject = New-Object -TypeName 'Microsoft.SqlServer.Management.Smo.Audit' -ArgumentList @($ServerObject, $Name) - $queryType = switch ($PSCmdlet.ParameterSetName) - { - 'Log' + $queryType = switch ($PSCmdlet.ParameterSetName) { - $LogType - } + 'Log' + { + $LogType + } - default - { - 'File' + default + { + 'File' + } } - } - $auditObject.DestinationType = $queryType + $auditObject.DestinationType = $queryType - if ($PSCmdlet.ParameterSetName -match 'File') - { - $auditObject.FilePath = $Path - - if ($PSCmdlet.ParameterSetName -match 'FileWithSize') + if ($PSCmdlet.ParameterSetName -match 'File') { - $convertedMaximumFileSizeUnit = ( - @{ - Megabyte = 'MB' - Gigabyte = 'GB' - Terabyte = 'TB' - } - ).$MaximumFileSizeUnit + $auditObject.FilePath = $Path - $auditObject.MaximumFileSize = $MaximumFileSize - $auditObject.MaximumFileSizeUnit = $convertedMaximumFileSizeUnit - } + if ($PSCmdlet.ParameterSetName -match 'FileWithSize') + { + $convertedMaximumFileSizeUnit = ( + @{ + Megabyte = 'MB' + Gigabyte = 'GB' + Terabyte = 'TB' + } + ).$MaximumFileSizeUnit + + $auditObject.MaximumFileSize = $MaximumFileSize + $auditObject.MaximumFileSizeUnit = $convertedMaximumFileSizeUnit + } - if ($PSCmdlet.ParameterSetName -in @('FileWithMaxFiles', 'FileWithSizeAndMaxFiles')) - { - $auditObject.MaximumFiles = $MaximumFiles + if ($PSCmdlet.ParameterSetName -in @('FileWithMaxFiles', 'FileWithSizeAndMaxFiles')) + { + $auditObject.MaximumFiles = $MaximumFiles - if ($PSBoundParameters.ContainsKey('ReserveDiskSpace')) + if ($PSBoundParameters.ContainsKey('ReserveDiskSpace')) + { + $auditObject.ReserveDiskSpace = $ReserveDiskSpace.IsPresent + } + } + + if ($PSCmdlet.ParameterSetName -in @('FileWithMaxRolloverFiles', 'FileWithSizeAndMaxRolloverFiles')) { - $auditObject.ReserveDiskSpace = $ReserveDiskSpace.IsPresent + $auditObject.MaximumRolloverFiles = $MaximumRolloverFiles } } - if ($PSCmdlet.ParameterSetName -in @('FileWithMaxRolloverFiles', 'FileWithSizeAndMaxRolloverFiles')) + if ($PSBoundParameters.ContainsKey('OnFailure')) { - $auditObject.MaximumRolloverFiles = $MaximumRolloverFiles + $auditObject.OnFailure = $OnFailure } - } - if ($PSBoundParameters.ContainsKey('OnFailure')) - { - $auditObject.OnFailure = $OnFailure - } - - if ($PSBoundParameters.ContainsKey('QueueDelay')) - { - $auditObject.QueueDelay = $QueueDelay - } - - if ($PSBoundParameters.ContainsKey('AuditGuid')) - { - $auditObject.Guid = $AuditGuid - } + if ($PSBoundParameters.ContainsKey('QueueDelay')) + { + $auditObject.QueueDelay = $QueueDelay + } - if ($PSBoundParameters.ContainsKey('AuditFilter')) - { - $auditObject.Filter = $AuditFilter - } + if ($PSBoundParameters.ContainsKey('AuditGuid')) + { + $auditObject.Guid = $AuditGuid + } - $verboseDescriptionMessage = $script:localizedData.Audit_Add_ShouldProcessVerboseDescription -f $Name, $ServerObject.InstanceName - $verboseWarningMessage = $script:localizedData.Audit_Add_ShouldProcessVerboseWarning -f $Name - $captionMessage = $script:localizedData.Audit_Add_ShouldProcessCaption + if ($PSBoundParameters.ContainsKey('AuditFilter')) + { + $auditObject.Filter = $AuditFilter + } - if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) - { - $auditObject.Create() + $verboseDescriptionMessage = $script:localizedData.Audit_Add_ShouldProcessVerboseDescription -f $Name, $ServerObject.InstanceName + $verboseWarningMessage = $script:localizedData.Audit_Add_ShouldProcessVerboseWarning -f $Name + $captionMessage = $script:localizedData.Audit_Add_ShouldProcessCaption - if ($PassThru.IsPresent) + if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) { - return $auditObject + $auditObject.Create() + + if ($PassThru.IsPresent) + { + return $auditObject + } } } } diff --git a/source/Public/Remove-SqlDscAudit.ps1 b/source/Public/Remove-SqlDscAudit.ps1 index 0500dc435..56a6d5e0c 100644 --- a/source/Public/Remove-SqlDscAudit.ps1 +++ b/source/Public/Remove-SqlDscAudit.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Removes a server audit. + .DESCRIPTION + This command removes a server audit from a SQL Server Database Engine instance. + .PARAMETER ServerObject Specifies current server connection object. @@ -65,34 +68,37 @@ function Remove-SqlDscAudit $Refresh ) - if ($Force.IsPresent) + process { - $ConfirmPreference = 'None' - } - - if ($PSCmdlet.ParameterSetName -eq 'ServerObject') - { - $getSqlDscAuditParameters = @{ - ServerObject = $ServerObject - Name = $Name - Refresh = $Refresh - ErrorAction = 'Stop' + if ($Force.IsPresent) + { + $ConfirmPreference = 'None' } - # If this command does not find the audit it will throw an exception. - $AuditObject = Get-SqlDscAudit @getSqlDscAuditParameters - } - - $verboseDescriptionMessage = $script:localizedData.Audit_Remove_ShouldProcessVerboseDescription -f $AuditObject.Name, $AuditObject.Parent.InstanceName - $verboseWarningMessage = $script:localizedData.Audit_Remove_ShouldProcessVerboseWarning -f $AuditObject.Name - $captionMessage = $script:localizedData.Audit_Remove_ShouldProcessCaption + if ($PSCmdlet.ParameterSetName -eq 'ServerObject') + { + $getSqlDscAuditParameters = @{ + ServerObject = $ServerObject + Name = $Name + Refresh = $Refresh + ErrorAction = 'Stop' + } + + # If this command does not find the audit it will throw an exception. + $AuditObject = Get-SqlDscAudit @getSqlDscAuditParameters + } - if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) - { - <# - If the passed audit object has already been dropped, then we silently - do nothing, using the method DropIfExist(), since the job is done. - #> - $AuditObject.DropIfExists() + $verboseDescriptionMessage = $script:localizedData.Audit_Remove_ShouldProcessVerboseDescription -f $AuditObject.Name, $AuditObject.Parent.InstanceName + $verboseWarningMessage = $script:localizedData.Audit_Remove_ShouldProcessVerboseWarning -f $AuditObject.Name + $captionMessage = $script:localizedData.Audit_Remove_ShouldProcessCaption + + if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) + { + <# + If the passed audit object has already been dropped, then we silently + do nothing, using the method DropIfExist(), since the job is done. + #> + $AuditObject.DropIfExists() + } } } diff --git a/source/Public/Remove-SqlDscNode.ps1 b/source/Public/Remove-SqlDscNode.ps1 index 32bd8ed20..98911774c 100644 --- a/source/Public/Remove-SqlDscNode.ps1 +++ b/source/Public/Remove-SqlDscNode.ps1 @@ -12,6 +12,21 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER ConfirmIPDependencyChange + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -26,7 +41,7 @@ .NOTES All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is + since it would take a lot of effort to keep them up to date. Instead there is a link in the comment-based help that points to the SQL Server command line setup documentation which will stay relevant. #> diff --git a/source/Public/Repair-SqlDscServer.ps1 b/source/Public/Repair-SqlDscServer.ps1 index a7b9f78d7..811bbcc95 100644 --- a/source/Public/Repair-SqlDscServer.ps1 +++ b/source/Public/Repair-SqlDscServer.ps1 @@ -12,6 +12,42 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER Enu + See the notes section for more information. + + .PARAMETER Features + See the notes section for more information. + + .PARAMETER PBEngSvcAccount + See the notes section for more information. + + .PARAMETER PBEngSvcPassword + See the notes section for more information. + + .PARAMETER PBEngSvcStartupType + See the notes section for more information. + + .PARAMETER PBStartPortRange + See the notes section for more information. + + .PARAMETER PBEndPortRange + See the notes section for more information. + + .PARAMETER PBScaleOut + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -24,13 +60,13 @@ Repairs the database engine of the instance 'MyInstance'. .NOTES - All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is - a link in the comment-based help that points to the SQL Server command line - setup documentation which will stay relevant. + The parameters are intentionally not described since it would take a lot + of effort to keep them up to date. Instead there is a link that points to + the SQL Server command line setup documentation which will stay relevant. #> function Repair-SqlDscServer { + # cSpell: ignore AZUREEXTENSION [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'Because ShouldProcess is used in Invoke-SetupAction')] [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')] [OutputType()] diff --git a/source/Public/Set-SqlDscAudit.ps1 b/source/Public/Set-SqlDscAudit.ps1 index ff3695a52..e783cf920 100644 --- a/source/Public/Set-SqlDscAudit.ps1 +++ b/source/Public/Set-SqlDscAudit.ps1 @@ -2,6 +2,10 @@ .SYNOPSIS Updates a server audit. + .DESCRIPTION + This command updates and existing server audit on a SQL Server Database Engine + instance. + .PARAMETER ServerObject Specifies current server connection object. @@ -11,7 +15,7 @@ .PARAMETER Name Specifies the name of the server audit to be updated. - .PARAMETER Filter + .PARAMETER AuditFilter Specifies the filter that should be used on the audit. See [predicate expression](https://docs.microsoft.com/en-us/sql/t-sql/statements/create-server-audit-transact-sql) how to write the syntax for the filter. @@ -37,7 +41,7 @@ for example through T-SQL. But on instances with a large amount of audits it might be better to make sure the ServerObject is recent enough. - .PARAMETER FilePath + .PARAMETER Path Specifies the location where te log files wil be placed. .PARAMETER ReserveDiskSpace @@ -59,6 +63,9 @@ Specifies the amount of files on disk before SQL Server starts reusing the files. If not specified then it is set to unlimited. + .PARAMETER PassThru + If specified the changed audit object will be returned. + .OUTPUTS `[Microsoft.SqlServer.Management.Smo.Audit]` is passing parameter **PassThru**, otherwise none. @@ -236,111 +243,114 @@ function Set-SqlDscAudit $MaximumRolloverFiles ) - if ($Force.IsPresent) + process { - $ConfirmPreference = 'None' - } - - if ($PSCmdlet.ParameterSetName -eq 'ServerObject') - { - $getSqlDscAuditParameters = @{ - ServerObject = $ServerObject - Name = $Name - Refresh = $Refresh - ErrorAction = 'Stop' + if ($Force.IsPresent) + { + $ConfirmPreference = 'None' } - $AuditObject = Get-SqlDscAudit @getSqlDscAuditParameters - } - - if ($Refresh.IsPresent) - { - $AuditObject.Refresh() - } - - $verboseDescriptionMessage = $script:localizedData.Audit_Update_ShouldProcessVerboseDescription -f $AuditObject.Name, $AuditObject.Parent.InstanceName - $verboseWarningMessage = $script:localizedData.Audit_Update_ShouldProcessVerboseWarning -f $AuditObject.Name - $captionMessage = $script:localizedData.Audit_Update_ShouldProcessCaption - - if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) - { - if ($PSBoundParameters.ContainsKey('Path')) + if ($PSCmdlet.ParameterSetName -eq 'ServerObject') { - $AuditObject.FilePath = $Path + $getSqlDscAuditParameters = @{ + ServerObject = $ServerObject + Name = $Name + Refresh = $Refresh + ErrorAction = 'Stop' + } + + $AuditObject = Get-SqlDscAudit @getSqlDscAuditParameters } - if ($PSCmdlet.ParameterSetName -match 'WithSize') + if ($Refresh.IsPresent) { - $queryMaximumFileSizeUnit = ( - @{ - Megabyte = 'MB' - Gigabyte = 'GB' - Terabyte = 'TB' - } - ).$MaximumFileSizeUnit - - $AuditObject.MaximumFileSize = $MaximumFileSize - $AuditObject.MaximumFileSizeUnit = $queryMaximumFileSizeUnit + $AuditObject.Refresh() } - if ($PSCmdlet.ParameterSetName -match 'MaxFiles') + $verboseDescriptionMessage = $script:localizedData.Audit_Update_ShouldProcessVerboseDescription -f $AuditObject.Name, $AuditObject.Parent.InstanceName + $verboseWarningMessage = $script:localizedData.Audit_Update_ShouldProcessVerboseWarning -f $AuditObject.Name + $captionMessage = $script:localizedData.Audit_Update_ShouldProcessCaption + + if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) { - if ($AuditObject.MaximumRolloverFiles) + if ($PSBoundParameters.ContainsKey('Path')) { - # Switching to MaximumFiles instead of MaximumRolloverFiles. - $AuditObject.MaximumRolloverFiles = 0 - - # Must run method Alter() before setting MaximumFiles. - $AuditObject.Alter() + $AuditObject.FilePath = $Path } - $AuditObject.MaximumFiles = $MaximumFiles - - if ($PSBoundParameters.ContainsKey('ReserveDiskSpace')) + if ($PSCmdlet.ParameterSetName -match 'WithSize') { - $AuditObject.ReserveDiskSpace = $ReserveDiskSpace.IsPresent + $queryMaximumFileSizeUnit = ( + @{ + Megabyte = 'MB' + Gigabyte = 'GB' + Terabyte = 'TB' + } + ).$MaximumFileSizeUnit + + $AuditObject.MaximumFileSize = $MaximumFileSize + $AuditObject.MaximumFileSizeUnit = $queryMaximumFileSizeUnit } - } - if ($PSCmdlet.ParameterSetName -match 'MaxRolloverFiles') - { - if ($AuditObject.MaximumFiles) + if ($PSCmdlet.ParameterSetName -match 'MaxFiles') { - # Switching to MaximumRolloverFiles instead of MaximumFiles. - $AuditObject.MaximumFiles = 0 + if ($AuditObject.MaximumRolloverFiles) + { + # Switching to MaximumFiles instead of MaximumRolloverFiles. + $AuditObject.MaximumRolloverFiles = 0 + + # Must run method Alter() before setting MaximumFiles. + $AuditObject.Alter() + } + + $AuditObject.MaximumFiles = $MaximumFiles - # Must run method Alter() before setting MaximumRolloverFiles. - $AuditObject.Alter() + if ($PSBoundParameters.ContainsKey('ReserveDiskSpace')) + { + $AuditObject.ReserveDiskSpace = $ReserveDiskSpace.IsPresent + } } - $AuditObject.MaximumRolloverFiles = $MaximumRolloverFiles - } + if ($PSCmdlet.ParameterSetName -match 'MaxRolloverFiles') + { + if ($AuditObject.MaximumFiles) + { + # Switching to MaximumRolloverFiles instead of MaximumFiles. + $AuditObject.MaximumFiles = 0 - if ($PSBoundParameters.ContainsKey('OnFailure')) - { - $AuditObject.OnFailure = $OnFailure - } + # Must run method Alter() before setting MaximumRolloverFiles. + $AuditObject.Alter() + } - if ($PSBoundParameters.ContainsKey('QueueDelay')) - { - $AuditObject.QueueDelay = $QueueDelay - } + $AuditObject.MaximumRolloverFiles = $MaximumRolloverFiles + } - if ($PSBoundParameters.ContainsKey('AuditGuid')) - { - $AuditObject.Guid = $AuditGuid - } + if ($PSBoundParameters.ContainsKey('OnFailure')) + { + $AuditObject.OnFailure = $OnFailure + } - if ($PSBoundParameters.ContainsKey('AuditFilter')) - { - $AuditObject.Filter = $AuditFilter - } + if ($PSBoundParameters.ContainsKey('QueueDelay')) + { + $AuditObject.QueueDelay = $QueueDelay + } - $AuditObject.Alter() + if ($PSBoundParameters.ContainsKey('AuditGuid')) + { + $AuditObject.Guid = $AuditGuid + } - if ($PassThru.IsPresent) - { - return $AuditObject + if ($PSBoundParameters.ContainsKey('AuditFilter')) + { + $AuditObject.Filter = $AuditFilter + } + + $AuditObject.Alter() + + if ($PassThru.IsPresent) + { + return $AuditObject + } } } } diff --git a/source/Public/Set-SqlDscDatabasePermission.ps1 b/source/Public/Set-SqlDscDatabasePermission.ps1 index 3c382e5e9..2bd25c7fe 100644 --- a/source/Public/Set-SqlDscDatabasePermission.ps1 +++ b/source/Public/Set-SqlDscDatabasePermission.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Set permission for a database principal. + .DESCRIPTION + Set permission for a database principal. + .PARAMETER ServerObject Specifies current server connection object. @@ -90,123 +93,126 @@ function Set-SqlDscDatabasePermission $Force ) - if ($State -eq 'Deny' -and $WithGrant.IsPresent) - { - Write-Warning -Message $script:localizedData.DatabasePermission_IgnoreWithGrantForStateDeny - } - - if ($Force.IsPresent) + process { - $ConfirmPreference = 'None' - } - - $sqlDatabaseObject = $null - - if ($ServerObject.Databases) - { - $sqlDatabaseObject = $ServerObject.Databases[$DatabaseName] - } + if ($State -eq 'Deny' -and $WithGrant.IsPresent) + { + Write-Warning -Message $script:localizedData.DatabasePermission_IgnoreWithGrantForStateDeny + } - if ($sqlDatabaseObject) - { - $testSqlDscIsDatabasePrincipalParameters = @{ - ServerObject = $ServerObject - DatabaseName = $DatabaseName - Name = $Name - ExcludeFixedRoles = $true + if ($Force.IsPresent) + { + $ConfirmPreference = 'None' } - $isDatabasePrincipal = Test-SqlDscIsDatabasePrincipal @testSqlDscIsDatabasePrincipalParameters + $sqlDatabaseObject = $null - if ($isDatabasePrincipal) + if ($ServerObject.Databases) { - # Get the permissions names that are set to $true in the DatabasePermissionSet. - $permissionName = $Permission | - Get-Member -MemberType 'Property' | - Select-Object -ExpandProperty 'Name' | - Where-Object -FilterScript { - $Permission.$_ - } - - $verboseDescriptionMessage = $script:localizedData.DatabasePermission_ChangePermissionShouldProcessVerboseDescription -f $Name, $DatabaseName, $ServerObject.InstanceName - $verboseWarningMessage = $script:localizedData.DatabasePermission_ChangePermissionShouldProcessVerboseWarning -f $Name - $captionMessage = $script:localizedData.DatabasePermission_ChangePermissionShouldProcessCaption + $sqlDatabaseObject = $ServerObject.Databases[$DatabaseName] + } - if (-not $PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) - { - # Return without doing anything if the user did not want to continue processing. - return + if ($sqlDatabaseObject) + { + $testSqlDscIsDatabasePrincipalParameters = @{ + ServerObject = $ServerObject + DatabaseName = $DatabaseName + Name = $Name + ExcludeFixedRoles = $true } - switch ($State) - { - 'Grant' - { - Write-Verbose -Message ( - $script:localizedData.DatabasePermission_GrantPermission -f ($permissionName -join ','), $Name - ) + $isDatabasePrincipal = Test-SqlDscIsDatabasePrincipal @testSqlDscIsDatabasePrincipalParameters - if ($WithGrant.IsPresent) - { - $sqlDatabaseObject.Grant($Permission, $Name, $true) - } - else - { - $sqlDatabaseObject.Grant($Permission, $Name) + if ($isDatabasePrincipal) + { + # Get the permissions names that are set to $true in the DatabasePermissionSet. + $permissionName = $Permission | + Get-Member -MemberType 'Property' | + Select-Object -ExpandProperty 'Name' | + Where-Object -FilterScript { + $Permission.$_ } - } - 'Deny' - { - Write-Verbose -Message ( - $script:localizedData.DatabasePermission_DenyPermission -f ($permissionName -join ','), $Name - ) + $verboseDescriptionMessage = $script:localizedData.DatabasePermission_ChangePermissionShouldProcessVerboseDescription -f $Name, $DatabaseName, $ServerObject.InstanceName + $verboseWarningMessage = $script:localizedData.DatabasePermission_ChangePermissionShouldProcessVerboseWarning -f $Name + $captionMessage = $script:localizedData.DatabasePermission_ChangePermissionShouldProcessCaption - $sqlDatabaseObject.Deny($Permission, $Name) + if (-not $PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) + { + # Return without doing anything if the user did not want to continue processing. + return } - 'Revoke' + switch ($State) { - Write-Verbose -Message ( - $script:localizedData.DatabasePermission_RevokePermission -f ($permissionName -join ','), $Name - ) + 'Grant' + { + Write-Verbose -Message ( + $script:localizedData.DatabasePermission_GrantPermission -f ($permissionName -join ','), $Name + ) + + if ($WithGrant.IsPresent) + { + $sqlDatabaseObject.Grant($Permission, $Name, $true) + } + else + { + $sqlDatabaseObject.Grant($Permission, $Name) + } + } - if ($WithGrant.IsPresent) + 'Deny' { - $sqlDatabaseObject.Revoke($Permission, $Name, $false, $true) + Write-Verbose -Message ( + $script:localizedData.DatabasePermission_DenyPermission -f ($permissionName -join ','), $Name + ) + + $sqlDatabaseObject.Deny($Permission, $Name) } - else + + 'Revoke' { - $sqlDatabaseObject.Revoke($Permission, $Name) + Write-Verbose -Message ( + $script:localizedData.DatabasePermission_RevokePermission -f ($permissionName -join ','), $Name + ) + + if ($WithGrant.IsPresent) + { + $sqlDatabaseObject.Revoke($Permission, $Name, $false, $true) + } + else + { + $sqlDatabaseObject.Revoke($Permission, $Name) + } } } } + else + { + $missingPrincipalMessage = $script:localizedData.DatabasePermission_MissingPrincipal -f $Name, $DatabaseName + + $PSCmdlet.ThrowTerminatingError( + [System.Management.Automation.ErrorRecord]::new( + $missingPrincipalMessage, + 'GSDDP0001', + [System.Management.Automation.ErrorCategory]::InvalidOperation, + $Name + ) + ) + } } else { - $missingPrincipalMessage = $script:localizedData.DatabasePermission_MissingPrincipal -f $Name, $DatabaseName + $missingDatabaseMessage = $script:localizedData.DatabasePermission_MissingDatabase -f $DatabaseName $PSCmdlet.ThrowTerminatingError( [System.Management.Automation.ErrorRecord]::new( - $missingPrincipalMessage, - 'GSDDP0001', + $missingDatabaseMessage, + 'GSDDP0002', [System.Management.Automation.ErrorCategory]::InvalidOperation, - $Name + $DatabaseName ) ) } } - else - { - $missingDatabaseMessage = $script:localizedData.DatabasePermission_MissingDatabase -f $DatabaseName - - $PSCmdlet.ThrowTerminatingError( - [System.Management.Automation.ErrorRecord]::new( - $missingDatabaseMessage, - 'GSDDP0002', - [System.Management.Automation.ErrorCategory]::InvalidOperation, - $DatabaseName - ) - ) - } } diff --git a/source/Public/Set-SqlDscServerPermission.ps1 b/source/Public/Set-SqlDscServerPermission.ps1 index 860f13549..229e4ddf2 100644 --- a/source/Public/Set-SqlDscServerPermission.ps1 +++ b/source/Public/Set-SqlDscServerPermission.ps1 @@ -2,6 +2,10 @@ .SYNOPSIS Set permission for a login. + .DESCRIPTION + This command sets the permissions for a existing login on a SQL Server + Database Engine instance. + .PARAMETER ServerObject Specifies current server connection object. @@ -78,98 +82,101 @@ function Set-SqlDscServerPermission $Force ) - if ($State -eq 'Deny' -and $WithGrant.IsPresent) - { - Write-Warning -Message $script:localizedData.ServerPermission_IgnoreWithGrantForStateDeny - } - - if ($Force.IsPresent) - { - $ConfirmPreference = 'None' - } - - $testSqlDscIsLoginParameters = @{ - ServerObject = $ServerObject - Name = $Name - } - - $isLogin = Test-SqlDscIsLogin @testSqlDscIsLoginParameters - - if ($isLogin) + process { - # Get the permissions names that are set to $true in the ServerPermissionSet. - $permissionName = $Permission | - Get-Member -MemberType 'Property' | - Select-Object -ExpandProperty 'Name' | - Where-Object -FilterScript { - $Permission.$_ - } - - $verboseDescriptionMessage = $script:localizedData.ServerPermission_ChangePermissionShouldProcessVerboseDescription -f $Name, $ServerObject.InstanceName - $verboseWarningMessage = $script:localizedData.ServerPermission_ChangePermissionShouldProcessVerboseWarning -f $Name - $captionMessage = $script:localizedData.ServerPermission_ChangePermissionShouldProcessCaption - - if (-not $PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) + if ($State -eq 'Deny' -and $WithGrant.IsPresent) { - # Return without doing anything if the user did not want to continue processing. - return + Write-Warning -Message $script:localizedData.ServerPermission_IgnoreWithGrantForStateDeny } - switch ($State) + if ($Force.IsPresent) { - 'Grant' - { - Write-Verbose -Message ( - $script:localizedData.ServerPermission_GrantPermission -f ($permissionName -join ','), $Name - ) + $ConfirmPreference = 'None' + } - if ($WithGrant.IsPresent) - { - $ServerObject.Grant($Permission, $Name, $true) - } - else - { - $ServerObject.Grant($Permission, $Name) + $testSqlDscIsLoginParameters = @{ + ServerObject = $ServerObject + Name = $Name + } + + $isLogin = Test-SqlDscIsLogin @testSqlDscIsLoginParameters + + if ($isLogin) + { + # Get the permissions names that are set to $true in the ServerPermissionSet. + $permissionName = $Permission | + Get-Member -MemberType 'Property' | + Select-Object -ExpandProperty 'Name' | + Where-Object -FilterScript { + $Permission.$_ } - } - 'Deny' - { - Write-Verbose -Message ( - $script:localizedData.ServerPermission_DenyPermission -f ($permissionName -join ','), $Name - ) + $verboseDescriptionMessage = $script:localizedData.ServerPermission_ChangePermissionShouldProcessVerboseDescription -f $Name, $ServerObject.InstanceName + $verboseWarningMessage = $script:localizedData.ServerPermission_ChangePermissionShouldProcessVerboseWarning -f $Name + $captionMessage = $script:localizedData.ServerPermission_ChangePermissionShouldProcessCaption - $ServerObject.Deny($Permission, $Name) + if (-not $PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage)) + { + # Return without doing anything if the user did not want to continue processing. + return } - 'Revoke' + switch ($State) { - Write-Verbose -Message ( - $script:localizedData.ServerPermission_RevokePermission -f ($permissionName -join ','), $Name - ) + 'Grant' + { + Write-Verbose -Message ( + $script:localizedData.ServerPermission_GrantPermission -f ($permissionName -join ','), $Name + ) + + if ($WithGrant.IsPresent) + { + $ServerObject.Grant($Permission, $Name, $true) + } + else + { + $ServerObject.Grant($Permission, $Name) + } + } - if ($WithGrant.IsPresent) + 'Deny' { - $ServerObject.Revoke($Permission, $Name, $false, $true) + Write-Verbose -Message ( + $script:localizedData.ServerPermission_DenyPermission -f ($permissionName -join ','), $Name + ) + + $ServerObject.Deny($Permission, $Name) } - else + + 'Revoke' { - $ServerObject.Revoke($Permission, $Name) + Write-Verbose -Message ( + $script:localizedData.ServerPermission_RevokePermission -f ($permissionName -join ','), $Name + ) + + if ($WithGrant.IsPresent) + { + $ServerObject.Revoke($Permission, $Name, $false, $true) + } + else + { + $ServerObject.Revoke($Permission, $Name) + } } } } - } - else - { - $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $Name, $ServerObject.InstanceName - - $PSCmdlet.ThrowTerminatingError( - [System.Management.Automation.ErrorRecord]::new( - $missingPrincipalMessage, - 'GSDDP0001', - [System.Management.Automation.ErrorCategory]::InvalidOperation, - $Name + else + { + $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $Name, $ServerObject.InstanceName + + $PSCmdlet.ThrowTerminatingError( + [System.Management.Automation.ErrorRecord]::new( + $missingPrincipalMessage, + 'GSDDP0001', + [System.Management.Automation.ErrorCategory]::InvalidOperation, + $Name + ) ) - ) + } } } diff --git a/source/Public/Test-SqlDscIsDatabasePrincipal.ps1 b/source/Public/Test-SqlDscIsDatabasePrincipal.ps1 index bba2d89a7..9b51abda3 100644 --- a/source/Public/Test-SqlDscIsDatabasePrincipal.ps1 +++ b/source/Public/Test-SqlDscIsDatabasePrincipal.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Returns whether the database principal exist. + .DESCRIPTION + Returns whether the database principal exist. + .PARAMETER ServerObject Specifies current server connection object. @@ -94,51 +97,54 @@ function Test-SqlDscIsDatabasePrincipal $ExcludeApplicationRoles ) - $principalExist = $false + process + { + $principalExist = $false - $sqlDatabaseObject = $ServerObject.Databases[$DatabaseName] + $sqlDatabaseObject = $ServerObject.Databases[$DatabaseName] - if (-not $sqlDatabaseObject) - { - $PSCmdlet.ThrowTerminatingError( - [System.Management.Automation.ErrorRecord]::new( - ($script:localizedData.IsDatabasePrincipal_DatabaseMissing -f $DatabaseName), - 'TSDISO0001', - [System.Management.Automation.ErrorCategory]::InvalidOperation, - $DatabaseName + if (-not $sqlDatabaseObject) + { + $PSCmdlet.ThrowTerminatingError( + [System.Management.Automation.ErrorRecord]::new( + ($script:localizedData.IsDatabasePrincipal_DatabaseMissing -f $DatabaseName), + 'TSDISO0001', + [System.Management.Automation.ErrorCategory]::InvalidOperation, + $DatabaseName + ) ) - ) - } - - if (-not $ExcludeUsers.IsPresent -and $sqlDatabaseObject.Users[$Name]) - { - $principalExist = $true - } + } - if (-not $ExcludeRoles.IsPresent) - { - $userDefinedRole = if ($ExcludeFixedRoles.IsPresent) + if (-not $ExcludeUsers.IsPresent -and $sqlDatabaseObject.Users[$Name]) { - # Skip fixed roles like db_datareader. - $sqlDatabaseObject.Roles | Where-Object -FilterScript { - -not $_.IsFixedRole -and $_.Name -eq $Name - } + $principalExist = $true } - else + + if (-not $ExcludeRoles.IsPresent) { - $sqlDatabaseObject.Roles[$Name] + $userDefinedRole = if ($ExcludeFixedRoles.IsPresent) + { + # Skip fixed roles like db_datareader. + $sqlDatabaseObject.Roles | Where-Object -FilterScript { + -not $_.IsFixedRole -and $_.Name -eq $Name + } + } + else + { + $sqlDatabaseObject.Roles[$Name] + } + + if ($userDefinedRole) + { + $principalExist = $true + } } - if ($userDefinedRole) + if (-not $ExcludeApplicationRoles.IsPresent -and $sqlDatabaseObject.ApplicationRoles[$Name]) { $principalExist = $true } - } - if (-not $ExcludeApplicationRoles.IsPresent -and $sqlDatabaseObject.ApplicationRoles[$Name]) - { - $principalExist = $true + return $principalExist } - - return $principalExist } diff --git a/source/Public/Test-SqlDscIsLogin.ps1 b/source/Public/Test-SqlDscIsLogin.ps1 index 6659a18ef..66ae621f0 100644 --- a/source/Public/Test-SqlDscIsLogin.ps1 +++ b/source/Public/Test-SqlDscIsLogin.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS Returns whether the database principal exist. + .DESCRIPTION + Returns whether the database principal exist. + .PARAMETER ServerObject Specifies current server connection object. @@ -33,12 +36,15 @@ function Test-SqlDscIsLogin $Name ) - $loginExist = $false - - if ($ServerObject.Logins[$Name]) + process { - $loginExist = $true - } + $loginExist = $false + + if ($ServerObject.Logins[$Name]) + { + $loginExist = $true + } - return $loginExist + return $loginExist + } } diff --git a/source/Public/Uninstall-SqlDscServer.ps1 b/source/Public/Uninstall-SqlDscServer.ps1 index 0d3d76c4e..4085086db 100644 --- a/source/Public/Uninstall-SqlDscServer.ps1 +++ b/source/Public/Uninstall-SqlDscServer.ps1 @@ -13,6 +13,21 @@ Specifies the path where to find the SQL Server installation media. On this path the SQL Server setup executable must be found. + .PARAMETER Timeout + Specifies how long to wait for the setup process to finish. Default value + is `7200` seconds (2 hours). If the setup process does not finish before + this time, an exception will be thrown. + + .PARAMETER Force + If specified the command will not ask for confirmation. Same as if Confirm:$false + is used. + + .PARAMETER InstanceName + See the notes section for more information. + + .PARAMETER Features + See the notes section for more information. + .LINK https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt @@ -25,13 +40,13 @@ Uninstalls the database engine from the named instance MyInstance. .NOTES - All parameters has intentionally not been added to this comment-based help - since it would take a lot of effort to keep it up to date. Instead there is - a link in the comment-based help that points to the SQL Server command line - setup documentation which will stay relevant. + The parameters are intentionally not described since it would take a lot + of effort to keep them up to date. Instead there is a link that points to + the SQL Server command line setup documentation which will stay relevant. #> function Uninstall-SqlDscServer { + # cSpell: ignore AZUREEXTENSION [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'Because ShouldProcess is used in Invoke-SetupAction')] [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')] [OutputType()] diff --git a/tests/QA/ScriptAnalyzer.Tests.ps1 b/tests/QA/ScriptAnalyzer.Tests.ps1 index ccfc78435..6fbe746e6 100644 --- a/tests/QA/ScriptAnalyzer.Tests.ps1 +++ b/tests/QA/ScriptAnalyzer.Tests.ps1 @@ -10,8 +10,30 @@ repository DscResource.Test is resolved this should not be needed. See issue https://github.com/dsccommunity/DscResource.Test/issues/100. #> +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')] +param () BeforeDiscovery { + try + { + if (-not (Get-Module -Name 'DscResource.Test')) + { + # Assumes dependencies has been resolved, so if this module is not available, run 'noop' task. + if (-not (Get-Module -Name 'DscResource.Test' -ListAvailable)) + { + # Redirect all streams to $null, except the error stream (stream 2) + & "$PSScriptRoot/../../build.ps1" -Tasks 'noop' 2>&1 4>&1 5>&1 6>&1 > $null + } + + # If the dependencies has not been resolved, this will throw an error. + Import-Module -Name 'DscResource.Test' -Force -ErrorAction 'Stop' + } + } + catch [System.IO.FileNotFoundException] + { + throw 'DscResource.Test module dependency not found. Please run ".\build.ps1 -ResolveDependency -Tasks build" first.' + } + <# Need to add the SMO stub classes so that the analyzer rule 'UseSyntacticallyCorrectExamples' (from Indented.ScriptAnalyzerRules) can properly parse parameters that uses SMO types, diff --git a/tests/QA/module.tests.ps1 b/tests/QA/module.tests.ps1 new file mode 100644 index 000000000..21c019cca --- /dev/null +++ b/tests/QA/module.tests.ps1 @@ -0,0 +1,256 @@ +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')] +param () + +BeforeDiscovery { + try + { + if (-not (Get-Module -Name 'DscResource.Test')) + { + # Assumes dependencies has been resolved, so if this module is not available, run 'noop' task. + if (-not (Get-Module -Name 'DscResource.Test' -ListAvailable)) + { + # Redirect all streams to $null, except the error stream (stream 2) + & "$PSScriptRoot/../../build.ps1" -Tasks 'noop' 2>&1 4>&1 5>&1 6>&1 > $null + } + + # If the dependencies has not been resolved, this will throw an error. + Import-Module -Name 'DscResource.Test' -Force -ErrorAction 'Stop' + } + } + catch [System.IO.FileNotFoundException] + { + throw 'DscResource.Test module dependency not found. Please run ".\build.ps1 -ResolveDependency -Tasks build" first.' + } + + $projectPath = "$($PSScriptRoot)\..\.." | Convert-Path + + <# + If the QA tests are run outside of the build script (e.g with Invoke-Pester) + the parent scope has not set the variable $ProjectName. + #> + if (-not $ProjectName) + { + # Assuming project folder name is project name. + $ProjectName = Get-SamplerProjectName -BuildRoot $projectPath + } + + $script:moduleName = $ProjectName + + Remove-Module -Name $script:moduleName -Force -ErrorAction SilentlyContinue + + $mut = Get-Module -Name $script:moduleName -ListAvailable | + Select-Object -First 1 | + Import-Module -Force -ErrorAction Stop -PassThru +} + +BeforeAll { + # Convert-Path required for PS7 or Join-Path fails + $projectPath = "$($PSScriptRoot)\..\.." | Convert-Path + + <# + If the QA tests are run outside of the build script (e.g with Invoke-Pester) + the parent scope has not set the variable $ProjectName. + #> + if (-not $ProjectName) + { + # Assuming project folder name is project name. + $ProjectName = Get-SamplerProjectName -BuildRoot $projectPath + } + + $script:moduleName = $ProjectName + + $sourcePath = ( + Get-ChildItem -Path $projectPath\*\*.psd1 | + Where-Object -FilterScript { + ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) ` + -and $( + try + { + Test-ModuleManifest -Path $_.FullName -ErrorAction Stop + } + catch + { + $false + } + ) + } + ).Directory.FullName +} + +Describe 'Changelog Management' -Tag 'Changelog' { + It 'Changelog has been updated' -Skip:( + -not ([bool](Get-Command git -ErrorAction SilentlyContinue) -and + [bool](&(Get-Process -Id $PID).Path -NoProfile -Command 'git rev-parse --is-inside-work-tree 2>$null')) + ) { + # Get the list of changed files compared with branch main + $headCommit = &git rev-parse HEAD + $defaultBranchCommit = &git rev-parse origin/main + $filesChanged = &git @('diff', "$defaultBranchCommit...$headCommit", '--name-only') + $filesStagedAndUnstaged = &git @('diff', 'HEAD', '--name-only') + + $filesChanged += $filesStagedAndUnstaged + + # Only check if there are any changed files. + if ($filesChanged) + { + $filesChanged | Should -Contain 'CHANGELOG.md' -Because 'the CHANGELOG.md must be updated with at least one entry in the Unreleased section for each PR' + } + } + + It 'Changelog format compliant with keepachangelog format' -Skip:(![bool](Get-Command git -EA SilentlyContinue)) { + { Get-ChangelogData -Path (Join-Path $ProjectPath 'CHANGELOG.md') -ErrorAction Stop } | Should -Not -Throw + } + + It 'Changelog should have an Unreleased header' -Skip:$skipTest { + (Get-ChangelogData -Path (Join-Path -Path $ProjectPath -ChildPath 'CHANGELOG.md') -ErrorAction Stop).Unreleased | Should -Not -BeNullOrEmpty + } +} + +Describe 'General module control' -Tags 'FunctionalQuality' { + It 'Should import without errors' { + { Import-Module -Name $script:moduleName -Force -ErrorAction Stop } | Should -Not -Throw + + Get-Module -Name $script:moduleName | Should -Not -BeNullOrEmpty + } + + It 'Should remove without error' { + { Remove-Module -Name $script:moduleName -ErrorAction Stop } | Should -Not -Throw + + Get-Module $script:moduleName | Should -BeNullOrEmpty + } +} + +BeforeDiscovery { + # Must use the imported module to build test cases. + $allModuleFunctions = & $mut { Get-Command -Module $args[0] -CommandType Function } $script:moduleName + + # Build test cases. + $testCases = @() + + foreach ($function in $allModuleFunctions) + { + $testCases += @{ + Name = $function.Name + } + } +} + +Describe 'Quality for module' -Tags 'TestQuality' { + BeforeDiscovery { + if (Get-Command -Name Invoke-ScriptAnalyzer -ErrorAction SilentlyContinue) + { + $scriptAnalyzerRules = Get-ScriptAnalyzerRule + } + else + { + if ($ErrorActionPreference -ne 'Stop') + { + Write-Warning -Message 'ScriptAnalyzer not found!' + } + else + { + throw 'ScriptAnalyzer not found!' + } + } + } + + It 'Should have a unit test for ' -ForEach $testCases { + Get-ChildItem -Path 'tests\' -Recurse -Include "$Name.Tests.ps1" | Should -Not -BeNullOrEmpty + } + + It 'Should pass Script Analyzer for ' -ForEach $testCases -Skip:(-not $scriptAnalyzerRules) { + $functionFile = Get-ChildItem -Path $sourcePath -Recurse -Include "$Name.ps1" + + $pssaResult = (Invoke-ScriptAnalyzer -Path $functionFile.FullName) + $report = $pssaResult | Format-Table -AutoSize | Out-String -Width 110 + $pssaResult | Should -BeNullOrEmpty -Because ` + "some rule triggered.`r`n`r`n $report" + } +} + +Describe 'Help for module' -Tags 'helpQuality' { + It 'Should have .SYNOPSIS for ' -ForEach $testCases { + $functionFile = Get-ChildItem -Path $sourcePath -Recurse -Include "$Name.ps1" + + $scriptFileRawContent = Get-Content -Raw -Path $functionFile.FullName + + $abstractSyntaxTree = [System.Management.Automation.Language.Parser]::ParseInput($scriptFileRawContent, [ref] $null, [ref] $null) + + $astSearchDelegate = { $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] } + + $parsedFunction = $abstractSyntaxTree.FindAll( $astSearchDelegate, $true ) | + Where-Object -FilterScript { + $_.Name -eq $Name + } + + $functionHelp = $parsedFunction.GetHelpContent() + + $functionHelp.Synopsis | Should -Not -BeNullOrEmpty + } + + It 'Should have a .DESCRIPTION with length greater than 40 characters for ' -ForEach $testCases { + $functionFile = Get-ChildItem -Path $sourcePath -Recurse -Include "$Name.ps1" + + $scriptFileRawContent = Get-Content -Raw -Path $functionFile.FullName + + $abstractSyntaxTree = [System.Management.Automation.Language.Parser]::ParseInput($scriptFileRawContent, [ref] $null, [ref] $null) + + $astSearchDelegate = { $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] } + + $parsedFunction = $abstractSyntaxTree.FindAll($astSearchDelegate, $true) | + Where-Object -FilterScript { + $_.Name -eq $Name + } + + $functionHelp = $parsedFunction.GetHelpContent() + + $functionHelp.Description.Length | Should -BeGreaterThan 40 + } + + It 'Should have at least one (1) example for ' -ForEach $testCases { + $functionFile = Get-ChildItem -Path $sourcePath -Recurse -Include "$Name.ps1" + + $scriptFileRawContent = Get-Content -Raw -Path $functionFile.FullName + + $abstractSyntaxTree = [System.Management.Automation.Language.Parser]::ParseInput($scriptFileRawContent, [ref] $null, [ref] $null) + + $astSearchDelegate = { $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] } + + $parsedFunction = $abstractSyntaxTree.FindAll( $astSearchDelegate, $true ) | + Where-Object -FilterScript { + $_.Name -eq $Name + } + + $functionHelp = $parsedFunction.GetHelpContent() + + $functionHelp.Examples.Count | Should -BeGreaterThan 0 + $functionHelp.Examples[0] | Should -Match ([regex]::Escape($function.Name)) + $functionHelp.Examples[0].Length | Should -BeGreaterThan ($function.Name.Length + 10) + + } + + It 'Should have described all parameters for ' -ForEach $testCases { + $functionFile = Get-ChildItem -Path $sourcePath -Recurse -Include "$Name.ps1" + + $scriptFileRawContent = Get-Content -Raw -Path $functionFile.FullName + + $abstractSyntaxTree = [System.Management.Automation.Language.Parser]::ParseInput($scriptFileRawContent, [ref] $null, [ref] $null) + + $astSearchDelegate = { $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] } + + $parsedFunction = $abstractSyntaxTree.FindAll( $astSearchDelegate, $true ) | + Where-Object -FilterScript { + $_.Name -eq $Name + } + + $functionHelp = $parsedFunction.GetHelpContent() + + $parameters = $parsedFunction.Body.ParamBlock.Parameters.Name.VariablePath.ForEach({ $_.ToString() }) + + foreach ($parameter in $parameters) + { + $functionHelp.Parameters.($parameter.ToUpper()) | Should -Not -BeNullOrEmpty -Because ('the parameter {0} must have a description' -f $parameter) + $functionHelp.Parameters.($parameter.ToUpper()).Length | Should -BeGreaterThan 25 -Because ('the parameter {0} must have descriptive description' -f $parameter) + } + } +}