SqlServerDsc: Update module to use auto-documentation (#1573)

- SqlServerDsc
  - Update resource parameter documentation (issue #1568).
  - Documentation is now published to the GitHub Wiki.

CHANGELOG.md

@@ -5,6 +5,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- SqlServerDsc
+  - Update resource parameter documentation ([issue #1568](https://github.com/dsccommunity/SqlServerDsc/issues/1568)).
+  - Documentation is now published to the GitHub Wiki.
+
 ## [14.0.0] - 2020-06-12
 
 ### Remove

build.yaml

@@ -32,7 +32,7 @@ BuildWorkflow:
     - Clean
     - Build_Module_ModuleBuilder
     - Build_NestedModules_ModuleBuilder
-    - Create_changelog_release_output
+    - Create_Changelog_Release_Output
     - Generate_Conceptual_Help
     - Generate_Wiki_Content
 
@@ -45,11 +45,12 @@ BuildWorkflow:
 
   test:
     - Pester_Tests_Stop_On_Fail
-    - Pester_if_Code_Coverage_Under_Threshold
+    - Pester_If_Code_Coverage_Under_Threshold
 
   publish:
-    - Publish_release_to_GitHub
-    - publish_module_to_gallery
+    - Publish_Release_To_GitHub
+    - Publish_Module_To_gallery
+    - Publish_Wiki_Content
 
 ####################################################
 #       PESTER  Configuration                      #

source/DSCResources/DSC_SqlAG/DSC_SqlAG.schema.mof

@@ -1,11 +1,11 @@
 [ClassVersion("1.0.0.0"), FriendlyName("SqlAG")]
 class DSC_SqlAG : OMI_BaseResource
 {
-    [Key, Description("The name of the availability group.")] String Name;
+    [Key, Description("Specifies the name of the availability group.")] String Name;
     [Required, Description("Hostname of the SQL Server to be configured.")] String ServerName;
     [Key, Description("Name of the SQL instance to be configured.")] String InstanceName;
     [Write, Description("Specifies if the availability group should be present or absent. Default is Present."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
-    [Write, Description("Specifies the automated backup preference for the availability group. When creating a group the default is None"), ValueMap{"Primary","SecondaryOnly","Secondary","None"}, Values{"Primary","SecondaryOnly","Secondary","None"}] String AutomatedBackupPreference;
+    [Write, Description("Specifies the automated backup preference for the availability group. When creating a group the default is None."), ValueMap{"Primary","SecondaryOnly","Secondary","None"}, Values{"Primary","SecondaryOnly","Secondary","None"}] String AutomatedBackupPreference;
     [Write, Description("Specifies the replica availability mode. When creating a group the default is 'AsynchronousCommit'."), ValueMap{"AsynchronousCommit","SynchronousCommit"}, Values{"AsynchronousCommit","SynchronousCommit"}] String AvailabilityMode;
     [Write, Description("Specifies the desired priority of the replicas in performing backups. The acceptable values for this parameter are: integers from 0 through 100. Of the set of replicas which are online and available, the replica that has the highest priority performs the backup. When creating a group the default is 50.")] UInt32 BackupPriority;
     [Write, Description("Specifies the type of availability group is Basic. This is only available is SQL Server 2016 and later and is ignored when applied to previous versions.")] Boolean BasicAvailabilityGroup;
@@ -18,8 +18,8 @@ class DSC_SqlAG : OMI_BaseResource
     [Write, Description("Specifies the failover mode. When creating a group the default is 'Manual'."), ValueMap{"Automatic","Manual"}, Values{"Automatic","Manual"}] String FailoverMode;
     [Write, Description("Specifies the length of time, in milliseconds, after which AlwaysOn availability groups declare an unresponsive server to be unhealthy. When creating a group the default is 30000.")] UInt32 HealthCheckTimeout;
     [Write, Description("Specifies that the resource will only determine if a change is needed if the target node is the active host of the SQL Server Instance.")] Boolean ProcessOnlyOnActiveNode;
-    [Read, Description("Gets the Endpoint URL of the availability group replica endpoint.")] String EndpointUrl;
-    [Read, Description("Gets the port the database mirroring endpoint is listening on.")] UInt32 EndpointPort;
-    [Read, Description("Gets the major version of the SQL Server instance.")] UInt32 Version;
-    [Read, Description("Determines if the current node is actively hosting the SQL Server instance.")] Boolean IsActiveNode;
+    [Read, Description("Returns the Endpoint URL of the availability group replica endpoint.")] String EndpointUrl;
+    [Read, Description("Returns the port the database mirroring endpoint is listening on.")] UInt32 EndpointPort;
+    [Read, Description("Returns the major version of the SQL Server instance.")] UInt32 Version;
+    [Read, Description("Returns if the current node is actively hosting the SQL Server instance.")] Boolean IsActiveNode;
 };

source/DSCResources/DSC_SqlAGDatabase/DSC_SqlAGDatabase.schema.mof

@@ -3,13 +3,13 @@ class DSC_SqlAGDatabase : OMI_BaseResource
 {
     [Required, Description("The name of the database(s) to add to the availability group. This accepts wildcards.")] String DatabaseName[];
     [Key, Description("Hostname of the SQL Server where the primary replica of the availability group lives. If the availability group is not currently on this server, the resource will attempt to connect to the server where the primary replica lives.")] String ServerName;
-    [Key, Description("Name of the SQL instance to be configured.")] String InstanceName;
+    [Key, Description("Name of the SQL instance where the primary replica of the availability group lives. If the availability group is not currently on this instance, the resource will attempt to connect to the instance where the primary replica lives.")] String InstanceName;
     [Key, Description("The name of the availability group in which to manage the database membership(s).")] String AvailabilityGroupName;
-    [Required, Description("The path used to seed the availability group replicas. This should be a path that is accessible by all of the replicas")] String BackupPath;
-    [Write, Description("Specifies the membership of the database(s) in the availability group. The options are: Present: The defined database(s) are added to the availability group. All other databases that may be a member of the availability group are ignored. Absent: The defined database(s) are removed from the availability group. All other databases that may be a member of the availability group are ignored. The default is 'Present'."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
+    [Required, Description("The path used to seed the availability group replicas. This should be a path that is accessible by all of the replicas.")] String BackupPath;
+    [Write, Description("Specifies the membership of the database(s) in the availability group. The option 'Present' means that the defined database(s) are added to the availability group. All other databases that may be a member of the availability group are ignored. The option 'Absent' means that the defined database(s) are removed from the availability group. All other databases that may be a member of the availability group are ignored. The default is 'Present'."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
     [Write, Description("When used with 'Ensure = 'Present'' it ensures the specified database(s) are the only databases that are a member of the specified Availability Group. This parameter is ignored when 'Ensure' is 'Absent'.")] Boolean Force;
-    [Write, Description("If set to $true, this ensures the database owner of the database on the primary replica is the owner of the database on all secondary replicas. This requires the database owner is available as a login on all replicas and that the PsDscRunAsCredential has impersonate any login, control server, impersonate login, or control login permissions. If set to $false, the owner of the database will be the PsDscRunAsCredential. The default is '$false'")] Boolean MatchDatabaseOwner;
-    [Write, Description("If set to $true, this adds the restore option WITH REPLACE. If set to $false, Existing databases and files will block the restore and throw error. The default is '$false'.")] Boolean ReplaceExisting;
+    [Write, Description("If set to $true, this ensures the database owner of the database on the primary replica is the owner of the database on all secondary replicas. This requires the database owner is available as a login on all replicas and that the PsDscRunAsCredential has impersonate any login, control server, impersonate login, or control login permissions. If set to $false, the owner of the database will be the PsDscRunAsCredential. The default is $false.")] Boolean MatchDatabaseOwner;
+    [Write, Description("If set to $true, this adds the restore option WITH REPLACE. If set to $false, existing databases and files will block the restore and throw error. The default is $false.")] Boolean ReplaceExisting;
     [Write, Description("Specifies that the resource will only determine if a change is needed if the target node is the active host of the SQL Server Instance.")] Boolean ProcessOnlyOnActiveNode;
-    [Read, Description("Determines if the current node is actively hosting the SQL Server instance.")] Boolean IsActiveNode;
+    [Read, Description("Returns if the current node is actively hosting the SQL Server instance.")] Boolean IsActiveNode;
 };

source/DSCResources/DSC_SqlAGListener/DSC_SqlAGListener.schema.mof

@@ -8,7 +8,7 @@ class DSC_SqlAGListener : OMI_BaseResource
     [Write, Description("If the availability group listener should be present or absent. Default value is 'Present'."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
     [Key, Description("The name of the availability group to which the availability group listener is or will be connected.")] String AvailabilityGroup;
     [Write, Description("The IP address used for the availability group listener, in the format 192.168.10.45/255.255.252.0. If using DHCP, set to the first IP-address of the DHCP subnet, in the format 192.168.8.1/255.255.252.0. Must be valid in the cluster-allowed IP range.")] String IpAddress[];
-    [Write, Description("The port used for the availability group listener")] UInt16 Port;
+    [Write, Description("The port used for the availability group listener.")] UInt16 Port;
     [Write, Description("If DHCP should be used for the availability group listener instead of static IP address.")] Boolean DHCP;
 };
 

source/DSCResources/DSC_SqlAGReplica/DSC_SqlAGReplica.schema.mof

@@ -7,17 +7,17 @@ class DSC_SqlAGReplica : OMI_BaseResource
     [Key, Description("Name of the SQL instance to be configured.")] String InstanceName;
     [Write, Description("Hostname of the SQL Server where the primary replica is expected to be active. If the primary replica is not found here, the resource will attempt to find the host that holds the primary replica and connect to it.")] String PrimaryReplicaServerName;
     [Write, Description("Name of the SQL instance where the primary replica lives.")] String PrimaryReplicaInstanceName;
-    [Write, Description("Specifies if the availability group replica should be present or absent. Default is Present."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
-    [Write, Description("Specifies the replica availability mode. Default when creating a replica is 'AsynchronousCommit'."), ValueMap{"AsynchronousCommit","SynchronousCommit"}, Values{"AsynchronousCommit","SynchronousCommit"}] String AvailabilityMode;
-    [Write, Description("Specifies the desired priority of the replicas in performing backups. The acceptable values for this parameter are: integers from 0 through 100. Of the set of replicas which are online and available, the replica that has the highest priority performs the backup. Default is 50.")] UInt32 BackupPriority;
+    [Write, Description("Specifies if the availability group replica should be present or absent. Default is 'Present'."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
+    [Write, Description("Specifies the replica availability mode. When creating a replica the default is 'AsynchronousCommit'."), ValueMap{"AsynchronousCommit","SynchronousCommit"}, Values{"AsynchronousCommit","SynchronousCommit"}] String AvailabilityMode;
+    [Write, Description("Specifies the desired priority of the replicas in performing backups. The acceptable values for this parameter are: integers from 0 through 100. Of the set of replicas which are online and available, the replica that has the highest priority performs the backup. When creating a replica the default is 50.")] UInt32 BackupPriority;
     [Write, Description("Specifies how the availability replica handles connections when in the primary role."), ValueMap{"AllowAllConnections","AllowReadWriteConnections"}, Values{"AllowAllConnections","AllowReadWriteConnections"}] String ConnectionModeInPrimaryRole;
     [Write, Description("Specifies how the availability replica handles connections when in the secondary role."), ValueMap{"AllowNoConnections","AllowReadIntentConnectionsOnly","AllowAllConnections"}, Values{"AllowNoConnections","AllowReadIntentConnectionsOnly","AllowAllConnections"}] String ConnectionModeInSecondaryRole;
     [Write, Description("Specifies the hostname or IP address of the availability group replica endpoint. When creating a group the default is the instance network name which is set in the code because the value can only be determined when connected to the SQL Instance.")] String EndpointHostName;
-    [Write, Description("Specifies the failover mode. Default when creating a replica is 'Manual'."), ValueMap{"Automatic","Manual"}, Values{"Automatic","Manual"}] String FailoverMode;
+    [Write, Description("Specifies the failover mode. When creating a replica the default is 'Manual'."), ValueMap{"Automatic","Manual"}, Values{"Automatic","Manual"}] String FailoverMode;
     [Write, Description("Specifies the fully-qualified domain name (FQDN) and port to use when routing to the replica for read only connections.")] String ReadOnlyRoutingConnectionUrl;
     [Write, Description("Specifies an ordered list of replica server names that represent the probe sequence for connection director to use when redirecting read-only connections through this availability replica. This parameter applies if the availability replica is the current primary replica of the availability group.")] String ReadOnlyRoutingList[];
     [Write, Description("Specifies that the resource will only determine if a change is needed if the target node is the active host of the SQL Server instance.")] Boolean ProcessOnlyOnActiveNode;
-    [Read, Description("Output the network port the endpoint is listening on. Used by Get-TargetResource.")] Uint16 EndpointPort;
-    [Read, Description("Output the endpoint URL of the Availability Group Replica. Used by Get-TargetResource.")] String EndpointUrl;
-    [Read, Description("Determines if the current node is actively hosting the SQL Server instance.")] Boolean IsActiveNode;
+    [Read, Description("Returns the network port the endpoint is listening on.")] Uint16 EndpointPort;
+    [Read, Description("Returns the endpoint URL of the Availability Group Replica.")] String EndpointUrl;
+    [Read, Description("Returns if the current node is actively hosting the SQL Server instance.")] Boolean IsActiveNode;
 };

source/DSCResources/DSC_SqlAgentFailsafe/DSC_SqlAgentFailsafe.schema.mof

@@ -5,5 +5,5 @@ class DSC_SqlAgentFailsafe : OMI_BaseResource
     [Write, Description("Specifies if the SQL Agent Failsafe Operator should be present or absent. Default is Present."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
     [Write, Description("The host name of the SQL Server to be configured. Default is $env:COMPUTERNAME.")] String ServerName;
     [Key, Description("The name of the SQL instance to be configured.")] String InstanceName;
-    [Write, Description("The method of notification for the Failsafe Operator."), ValueMap{"None","NotifyEmail","Pager","NetSend","NotifyAll"}, Values{"None","NotifyEmail","Pager","NetSend","NotifyAll"}] String NotificationMethod;
+    [Write, Description("The method of notification for the Failsafe Operator. The default is none."), ValueMap{"None","NotifyEmail","Pager","NetSend","NotifyAll"}, Values{"None","NotifyEmail","Pager","NetSend","NotifyAll"}] String NotificationMethod;
 };

source/DSCResources/DSC_SqlAlias/DSC_SqlAlias.schema.mof

@@ -4,8 +4,8 @@ class DSC_SqlAlias : OMI_BaseResource
     [Key, Description("The name of Alias (e.g. svr01\\inst01).")] String Name;
     [Write, Description("Protocol to use when connecting. Valid values are 'TCP' or 'NP' (Named Pipes). Default value is 'TCP'."), ValueMap{"TCP","NP"}, Values{"TCP","NP"}] String Protocol;
     [Write, Description("The SQL Server you are aliasing (the NetBIOS name or FQDN).")] String ServerName;
-    [Write, Description("The TCP port SQL is listening on. Only used when protocol is set to 'TCP'. Default value is port 1433.")] UInt16 TcpPort;
-    [Write, Description("The UseDynamicTcpPort specify that the Net-Library will determine the port dynamically. The port specified in Port number will not be used. Default value is '$false'.")] Boolean UseDynamicTcpPort;
-    [Write, Description("Determines whether the alias should be added or removed. Default value is 'Present'"), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
-    [Read, Description("Named Pipes path from the Get-TargetResource method.")] String PipeName;
+    [Write, Description("The TCP port the SQL Server instance is listening on. Only used when protocol is set to 'TCP'. Default value is port 1433.")] UInt16 TcpPort;
+    [Write, Description("The UseDynamicTcpPort specify that the Net-Library will determine the port dynamically. The port specified in Port number will not be used. Default value is $false.")] Boolean UseDynamicTcpPort;
+    [Write, Description("Determines whether the alias should be added or removed. Default value is 'Present'."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
+    [Read, Description("Returns the Named Pipes path if Protocol is set to 'NP'.")] String PipeName;
 };

source/DSCResources/DSC_SqlAlwaysOnService/DSC_SqlAlwaysOnService.schema.mof

@@ -4,6 +4,6 @@ class DSC_SqlAlwaysOnService : OMI_BaseResource
     [Key, Description("The name of the SQL instance to be configured.")] String InstanceName;
     [Required, Description("An enumerated value that describes if the SQL Server should have Always On high availability and disaster recovery (HADR) property enabled ('Present') or disabled ('Absent')."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
     [Write, Description("The hostname of the SQL Server to be configured. Default value is $env:COMPUTERNAME.")] String ServerName;
-    [Write, Description("The length of time, in seconds, to wait for the service to restart. Default is 120 seconds.")] UInt32 RestartTimeout;
+    [Write, Description("The length of time, in seconds, to wait for the service to restart. Default value is 120 seconds.")] UInt32 RestartTimeout;
     [Read, Description("Returns the status of AlwaysOn high availability and disaster recovery (HADR).")] Boolean IsHadrEnabled;
 };

source/DSCResources/DSC_SqlConfiguration/DSC_SqlConfiguration.schema.mof

@@ -2,7 +2,7 @@
 class DSC_SqlConfiguration : OMI_BaseResource
 {
     [Key, Description("Name of the SQL instance to be configured.")] String InstanceName;
-    [Key, Description("The name of the SQL configuration option to be checked.")] String OptionName;
+    [Key, Description("The name of the SQL configuration option to be checked. For all possible values reference [MSDN](https://msdn.microsoft.com/en-us/library/ms189631.aspx) or run sp_configure.")] String OptionName;
     [Required, Description("The desired value of the SQL configuration option.")] SInt32 OptionValue;
     [Write, Description("The hostname of the SQL Server to be configured. Default value is $env:COMPUTERNAME.")] String ServerName;
     [Write, Description("Determines whether the instance should be restarted after updating the configuration option.")] Boolean RestartService;