Skip to content

Commit

Permalink
SqlServerDsc: Updating note comments (#1958)
Browse files Browse the repository at this point in the history
- SqlServerDsc
  - Updating note comments throughout markdown and generated markdown.
  • Loading branch information
johlju authored Aug 16, 2023
1 parent 0dda9c3 commit 38ea597
Show file tree
Hide file tree
Showing 18 changed files with 108 additions and 80 deletions.
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Fix header in unit tests that referenced the wrong path.
- Fix a path in VS Code workspace settings to correctly use Script Analyzer on
Linux and macOS.
- Updating a note comment in the CONTRIBUTING.md.
- Updating note comments throughout markdown and generated markdown.
- SqlSetup
- Updating a note comment in the README.md.

Expand Down
7 changes: 4 additions & 3 deletions source/Classes/020.SqlDatabasePermission.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,10 @@
permissions for a user in a database. For more information about permissions,
please read the article [Permissions (Database Engine)](https://docs.microsoft.com/en-us/sql/relational-databases/security/permissions-database-engine).
>**Note:** When revoking permission with PermissionState 'GrantWithGrant', both the
>grantee and _all the other users the grantee has granted the same permission to_,
>will also get their permission revoked.
> [!NOTE]
> When revoking permission with PermissionState 'GrantWithGrant', both the
> grantee and _all the other users the grantee has granted the same permission_
> _to_, will also get their permission revoked.
## Requirements
Expand Down
7 changes: 4 additions & 3 deletions source/Classes/020.SqlPermission.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,10 @@
Server permissions for a login. For more information about permissions,
please read the article [Permissions (Database Engine)](https://docs.microsoft.com/en-us/sql/relational-databases/security/permissions-database-engine).
>**Note:** When revoking permission with PermissionState 'GrantWithGrant', both the
>grantee and _all the other users the grantee has granted the same permission to_,
>will also get their permission revoked.
> [!NOTE]
> When revoking permission with PermissionState 'GrantWithGrant', both the
> grantee and _all the other users the grantee has granted the same permission_
> _to_, will also get their permission revoked.
## Requirements
Expand Down
3 changes: 2 additions & 1 deletion source/DSCResources/DSC_SqlDatabaseMail/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

The `SqlDatabaseMail` DSC resource manages SQL Server Database Mail.

>**Note:** Database Mail XPs can be enabled using the resource `SqlConfiguration`.
> [!NOTE]
> Database Mail XPs can be enabled using the resource `SqlConfiguration`.
## Requirements

Expand Down
7 changes: 4 additions & 3 deletions source/DSCResources/DSC_SqlDatabaseObjectPermission/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,10 @@ of database objects in a database for a SQL Server instance.
For more information about permission names that can be managed, see the
property names of the [ObjectPermissionSet](https://docs.microsoft.com/en-us/dotnet/api/microsoft.sqlserver.management.smo.objectpermissionset#properties) class.

>**Note:** When revoking permission with PermissionState 'GrantWithGrant', both the
>grantee and _all the other users the grantee has granted the same permission to_,
>will also get their permission revoked.
> [!NOTE]
> When revoking permission with PermissionState 'GrantWithGrant', both the
> grantee and _all the other users the grantee has granted the same permission to_,
> will also get their permission revoked.
## Requirements

Expand Down
3 changes: 2 additions & 1 deletion source/DSCResources/DSC_SqlDatabaseUser/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ user can be mapped to a certificate or asymmetric key. The resource also
allows re-mapping of the SQL login. If the targeted database is not updatable,
the resource returns true.

> **Note:** This resource does not yet support [Contained Databases](https://docs.microsoft.com/en-us/sql/relational-databases/databases/contained-databases).
> [!NOTE]
> This resource does not yet support [Contained Databases](https://docs.microsoft.com/en-us/sql/relational-databases/databases/contained-databases).
## Requirements

Expand Down
9 changes: 5 additions & 4 deletions source/DSCResources/DSC_SqlEndpoint/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@ The `SqlEndpoint` DSC resource is used to create an endpoint. Currently
it only supports creating a database mirror and a service broker endpoint. A database mirror
endpoint can be used by AlwaysOn.

>Note: The endpoint will be started after creation, but will not be enforced
>unless the the parameter `State` is specified.
>To set connect permission to the endpoint, please use
>the resource [**SqlEndpointPermission**](#sqlendpointpermission).
> [!NOTE]
> The endpoint will be started after creation, but will not be enforced
> unless the the parameter `State` is specified.
> To set connect permission to the endpoint, please use
> the resource [**SqlEndpointPermission**](#sqlendpointpermission).
## Requirements

Expand Down
9 changes: 5 additions & 4 deletions source/DSCResources/DSC_SqlMaxDop/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,11 @@ the number of processors to use in parallel plan execution. Read more about
max degree of parallelism in this article
[Configure the max degree of parallelism Server Configuration Option](https://msdn.microsoft.com/en-us/library/ms189094.aspx)

>**NOTE** This configuration option can also be configured using the DSC
>resource _SqlConfiguration_ but will not allow the dynamic configuration
>as this resource provides. Make sure this value is not configured by both
>the resources _SqLMaxDop_ and _SqlConfiguration_!
> [!NOTE]
> This configuration option can also be configured using the DSC
> resource _SqlConfiguration_ but will not allow the dynamic configuration
> as this resource provides. Make sure this value is not configured by both
> the resources _SqLMaxDop_ and _SqlConfiguration_!
## Formula for dynamically allocating max degree of parallelism

Expand Down
9 changes: 5 additions & 4 deletions source/DSCResources/DSC_SqlMemory/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,11 @@ and the default setting for maximum server memory is 2147483647 MB. Read
more about minimum server memory and maximum server memory in this article
[Server Memory Server Configuration Options](https://msdn.microsoft.com/en-us/library/ms178067.aspx).

>**NOTE** These configuration options can also be configured using the DSC
>resource _SqlConfiguration_ but will not allow the dynamic configuration
>as this resource provides. Make sure this value is not configured by both
>the resources _SqLMemory_ and _SqlConfiguration_!
> [!NOTE]
> These configuration options can also be configured using the DSC
> resource _SqlConfiguration_ but will not allow the dynamic configuration
> as this resource provides. Make sure this value is not configured by both
> the resources _SqLMemory_ and _SqlConfiguration_!
## Formula for dynamically allocating maximum memory

Expand Down
25 changes: 13 additions & 12 deletions source/DSCResources/DSC_SqlRSSetup/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,19 +26,20 @@ used, then the installation will run as SYSTEM.
is successful (because the executable returns exit code 0) but the
Microsoft SQL Server Reporting Services instance was not actually removed.

>NOTE: When using the action 'Uninstall' and the target node to begin with
>requires a restart, on the first run the Microsoft SQL Server Reporting
>Services instance will not be uninstalled, but instead exits with code
>3010 and the node will be, by default, restarted. On the second run after
>restart, the Microsoft SQL Server Reporting Services instance will be
>uninstalled. If the parameter SuppressRestart is used, then the node must
>be restarted manually before the Microsoft SQL Server Reporting Services
>instance will be successfully uninstalled.
> [!NOTE]
> When using the action 'Uninstall' and the target node to begin with
> requires a restart, on the first run the Microsoft SQL Server Reporting
> Services instance will not be uninstalled, but instead exits with code
> 3010 and the node will be, by default, restarted. On the second run after
> restart, the Microsoft SQL Server Reporting Services instance will be
> uninstalled. If the parameter SuppressRestart is used, then the node must
> be restarted manually before the Microsoft SQL Server Reporting Services
> instance will be successfully uninstalled.
>
>The Microsoft SQL Server Reporting Services log will indicate that a
>restart is required by outputting; "*No action was taken as a system
>reboot is required (0x8007015E)*". The log is default located in the
>SSRS folder in `%TEMP%`, e.g. `C:\Users\<user>\AppData\Local\Temp\SSRS`.
> The Microsoft SQL Server Reporting Services log will indicate that a
> restart is required by outputting; "*No action was taken as a system
> reboot is required (0x8007015E)*". The log is default located in the
> SSRS folder in `%TEMP%`, e.g. `C:\Users\<user>\AppData\Local\Temp\SSRS`.
## Known issues

Expand Down
7 changes: 4 additions & 3 deletions source/DSCResources/DSC_SqlSecureConnection/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,10 @@ The `SqlSecureConnection` DSC resource configures SQL connections
to be encrypted. Read more about encrypted connections in this article
[Enable Encrypted Connections](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine).

>**Note:** The 'LocalSystem' service account will return a connection
>error, even though the connection has been successful. In that case,
>the 'SYSTEM' service account can be used.
> [!NOTE]
> The 'LocalSystem' service account will return a connection
> error, even though the connection has been successful. In that case,
> the 'SYSTEM' service account can be used.
## Requirements

Expand Down
2 changes: 1 addition & 1 deletion source/DSCResources/DSC_SqlSetup/DSC_SqlSetup.schema.mof
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[ClassVersion("1.0.0.0"), FriendlyName("SqlSetup")]
class DSC_SqlSetup : OMI_BaseResource
{
[Write, Description("The action to be performed. Default value is `'Install'`. **NOTE: AddNode is not currently functional.**"), ValueMap{"Install","Upgrade","InstallFailoverCluster","AddNode","PrepareFailoverCluster","CompleteFailoverCluster"}, Values{"Install","Upgrade","InstallFailoverCluster","AddNode","PrepareFailoverCluster","CompleteFailoverCluster"}] String Action;
[Write, Description("The action to be performed. Default value is `'Install'`. <br />> [!NOTE] **AddNode is not currently functional.**"), ValueMap{"Install","Upgrade","InstallFailoverCluster","AddNode","PrepareFailoverCluster","CompleteFailoverCluster"}, Values{"Install","Upgrade","InstallFailoverCluster","AddNode","PrepareFailoverCluster","CompleteFailoverCluster"}] String Action;
[Required, Description("The path to the root of the source files for installation. I.e and UNC path to a shared resource. Environment variables can be used in the path.")] String SourcePath;
[Write, EmbeddedInstance("MSFT_Credential"), Description("Credentials used to access the path set in the parameter **SourcePath**. See section [Considerations](#considerations) regarding the parameter **SourceCredential**.")] String SourceCredential;
[Write, Description("Suppresses reboot.")] Boolean SuppressReboot;
Expand Down
5 changes: 3 additions & 2 deletions source/DSCResources/DSC_SqlSetup/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,8 +142,9 @@ Feature flags are used to toggle resource functionality on or off. One or
more feature flags can be added to the parameter `FeatureFlag`, i.e.
`FeatureFlag = @('DetectionSharedFeatures')`.

>**NOTE:** The functionality, exposed with a feature flag, can be changed
>from one release to another, including having breaking changes.
> [!NOTE]
> The functionality, exposed with a feature flag, can be changed
> from one release to another, including having breaking changes.
<!-- markdownlint-disable MD013 -->
Feature flag | Description
Expand Down
20 changes: 12 additions & 8 deletions source/Examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,9 @@ changed to match your configuration. Also, please see other resource examples in
[xFailOverCluster](https://github.com/PowerShell/xFailOverCluster) to see if
they could improve you configuration, for example the resource xClusterQuorum.

>**Note:** Make sure any user accounts you use in the configuration exist in
>Active Directory and that they have the correct permission.
> [!NOTE]
> Make sure any user accounts you use in the configuration exist in
> Active Directory and that they have the correct permission.
#### Install SQL Server Failover Cluster Instance

Expand All @@ -150,8 +151,9 @@ The example shows how to
And this example shows how to
[install the second SQL Server Failover Cluster node for a named instance](https://github.com/PowerShell/SqlServerDsc/blob/dev/Examples/Resources/SqlSetup/5-InstallNamedInstanceInFailoverClusterSecondNode.ps1).

>**Note:** Make sure any user accounts you use in the configuration exist in
>Active Directory and that they have the correct permission.
> [!NOTE]
> Make sure any user accounts you use in the configuration exist in
> Active Directory and that they have the correct permission.
## Setting up a SQL Server AlwaysOn Availability Groups

Expand All @@ -172,8 +174,9 @@ to the failover cluster needed for SQL Server AlwaysOn Availability Groups.

#### Install SQL Server on replicas

>**Note:** Make sure any user accounts you use in the configuration exist in
>Active Directory and that they have the correct permission.
> [!NOTE]
> Make sure any user accounts you use in the configuration exist in
> Active Directory and that they have the correct permission.
##### Install SQL Server on the primary node

Expand Down Expand Up @@ -202,5 +205,6 @@ Once AlwaysOn is enabled we can create the Availability Group. The example [Crea
shows how to create the Availability Group on the primary replica and join the
Availability Group on the secondary replica.

>**Note:** Make sure any user accounts you use in the configuration exist in
>Active Directory and that they have the correct permission.
> [!NOTE]
> Make sure any user accounts you use in the configuration exist in
> Active Directory and that they have the correct permission.
3 changes: 2 additions & 1 deletion source/Examples/Resources/SqlRS/2-CustomConfiguration.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@
http://localhost:80/MyReports
https://localhost:443/MyReports
Note: this resource does not currently handle SSL bindings for HTTPS endpoints.
> [!NOTE]
> This resource does not currently handle SSL bindings for HTTPS endpoints.
#>
Configuration Example
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
Report Server Web Service: https://localhost:443/MyReportServer ()
Report Manager: https://localhost:443/MyReports
Note: this resource does not currently handle SSL bindings for HTTPS endpoints.
> [!NOTE]
> This resource does not currently handle SSL bindings for HTTPS endpoints.
#>
Configuration Example
{
Expand Down
5 changes: 3 additions & 2 deletions source/WikiSource/Home.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,9 @@ machine-wide, or at minimum set for each user that runs DSC resources, on
the target node. Make sure you comply with any license terms that is part
of dbatools.

>**NOTE:** It is also possible to use any module as a preferred module if
>its name is set as the value of the environment variable `SMODefaultModuleName`.
> [!NOTE]
> It is also possible to use any module as a preferred module if
> its name is set as the value of the environment variable `SMODefaultModuleName`.
## Change log

Expand Down
62 changes: 36 additions & 26 deletions tests/Integration/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,8 +80,9 @@ All running Database Engine instances also have a SQL Server Agent that is start
The instance DSCSQLTEST support mixed authentication mode, and will have
both Named Pipes and TCP/IP protocol enabled.

>**Note:** Some services are stopped to save memory on the build worker. See the
>column *State*.
> [!NOTE]
> Some services are stopped to save memory on the build worker. See the
> column *State*.
#### Properties for all instances

Expand All @@ -94,7 +95,8 @@ both Named Pipes and TCP/IP protocol enabled.
The following local users are created on the AppVeyor build worker and can
be used by other integration tests.

> Note: User account names was kept to a maximum of 15 characters.
> [!NOTE]
> User account names was kept to a maximum of 15 characters.
<!-- markdownlint-disable MD013 -->
User | Password | Permission | Description
Expand Down Expand Up @@ -137,18 +139,20 @@ The integration tests will install (or upgrade) separate, Microsoft SQL Server
2017 and 2019, Reporting Services instances and leave them on the build server
for other integration tests to use.

>**NOTE:** Uninstall is not tested, because when upgrading the existing
>Microsoft SQL Server Reporting Services instance it requires a restart,
>that prevents uninstall until the node is restarted.
> [!NOTE]
> Uninstall is not tested, because when upgrading the existing
> Microsoft SQL Server Reporting Services instance it requires a restart,
> that prevents uninstall until the node is restarted.
Instance | State
--- | ---
SSRS | Stopped

>**Note:** The Reporting Services instance is not configured after it is
>installed or upgraded, but if there are already an instance of Reporting
>Services installed on the build worker, it could have been configured.
>Other integration tests need to take that into consideration.
> [!NOTE]
> The Reporting Services instance is not configured after it is
> installed or upgraded, but if there are already an instance of Reporting
> Services installed on the build worker, it could have been configured.
> Other integration tests need to take that into consideration.
#### Properties for the instance SSRS 2017

Expand Down Expand Up @@ -193,14 +197,16 @@ tests creates an Active Directory Detached Cluster with an IP address of
'192.168.40.11' and the cluster will ignore any other static IP addresses.

<!-- markdownlint-disable MD028 -->
>**Note:** During the tests the gateway of the loopback adapter named 'ClusterNetwork'
>will be set to '192.168.40.254', because it is a requirement to create the cluster,
>but the gateway will be removed in the last clean up test. Gateway is removed so
>that there will be no conflict with the default gateway.
>**Note:** The Active Directory Detached Cluster is not fully functioning in the
>sense that it cannot start the Name resource in the 'Cluster Group', but it
>starts enough to be able to run integration tests for AlwaysOn service.s
> [!NOTE]
> During the tests the gateway of the loopback adapter named 'ClusterNetwork'
> will be set to '192.168.40.254', because it is a requirement to create the cluster,
> but the gateway will be removed in the last clean up test. Gateway is removed so
> that there will be no conflict with the default gateway.
> [!NOTE]
> The Active Directory Detached Cluster is not fully functioning in the
> sense that it cannot start the Name resource in the 'Cluster Group', but it
> starts enough to be able to run integration tests for AlwaysOn service.s
<!-- markdownlint-enable MD028 -->
The tests will leave the AlwaysOn service disabled.
Expand Down Expand Up @@ -264,11 +270,13 @@ DscUser4 | SQL | P@ssw0rd1 | *None*
`$env:COMPUTERNAME`\DscSqlUsers1 | Windows Group | -- | *None*

<!-- markdownlint-disable MD028 -->
>**Note:** The `$env:COMPUTERNAME` is reference to the build workers computer
>name. The SQL login could for example be 'APPVYR-WIN\DscUser1'.
> [!NOTE]
> The `$env:COMPUTERNAME` is reference to the build workers computer
> name. The SQL login could for example be 'APPVYR-WIN\DscUser1'.
>**Note:** The password for `DscUser4` is changed to `P@ssw0rd2` during one of the
>`SqlLogin`, integration tests and then set back again in a subsequent test.
> [!NOTE]
> The password for `DscUser4` is changed to `P@ssw0rd2` during one of the
> `SqlLogin`, integration tests and then set back again in a subsequent test.
<!-- markdownlint-disable MD028 -->
### SqlAgentAlert
Expand Down Expand Up @@ -354,8 +362,9 @@ Instance | Feature | Description
--- | --- | ---
SSRS | - | The Reporting Services (2017 or 2019) is initialized, and in a working state.

>**Note:** The Reporting Services service is stopped to save memory on the build
>worker.
> [!NOTE]
> The Reporting Services service is stopped to save memory on the build
> worker.
#### Properties for the instance

Expand Down Expand Up @@ -398,8 +407,9 @@ User3 | NoLogin | SqlLogin | - | - | -
User5 | Certificate | Certificate | - | Certificate1 | -
User6 | AsymmetricKey | AsymmetricKey | - | - | AsymmetricKey1

>**Note:** The `$env:COMPUTERNAME` is reference to the build workers computer
>name. The SQL login could for example be 'APPVYR-WIN\DscUser1'.
> [!NOTE]
> The `$env:COMPUTERNAME` is reference to the build workers computer
> name. The SQL login could for example be 'APPVYR-WIN\DscUser1'.
The integration test will leave this database certificate for other integration
tests to use.
Expand Down

0 comments on commit 38ea597

Please sign in to comment.