SqlServerDsc: Prepare for auto-documentation (dsccommunity#1567)

- SqlServerDsc
  - Prepare repository for auto-documentation by adding README.md to each
    resource folder with the content of the README.md.

CHANGELOG.md

@@ -43,6 +43,8 @@ in a future release.
   - Added new resource SqlServerProtocolTcpIp ([issue #1378](https://github.com/dsccommunity/SqlServerDsc/issues/1378)).
   - Fixing a problem with the latest ModuleBuild 1.7.0 that breaks the CI
     pipeline.
+  - Prepare repository for auto-documentation by adding README.md to each
+    resource folder with the content from the root README.md.
 - SqlServerDsc.Common
   - Added function `Import-Assembly` that can help import an assembly
     into the PowerShell session.

README.md

@@ -73,7 +73,7 @@ in a future release.
 
 * SqlDatabaseOwner _(replaced by a property in [**SqlDatabase**](#sqldatabase))_.
 * SqlDatabaseRecoveryModel _(replaced by a property in [**SqlDatabase**](#sqldatabase))_.
-* SqlServerEndpointState _(replaced by [**SqlServerEndpoint**](#sqlserverendpoint))_.
+* SqlServerEndpointState _(replaced by a property in [**SqlServerEndpoint**](#sqlserverendpoint))_.
 * SqlServerNetwork _(replaced by [**SqlServerProtocol**](#sqlserverprotocol) and_
   _[**SqlServerProtocolTcpIp**](#sqlserverprotocoltcpip))_.
 

source/DSCResources/DSC_SqlAG/README.md

@@ -0,0 +1,16 @@
+# Description
+
+The `SqlAG` DSC resource is used to create, remove, and update an Always On
+Availability Group. It will also manage the Availability Group replica on the
+specified node.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+* 'NT SERVICE\ClusSvc' or 'NT AUTHORITY\SYSTEM' must have the 'Connect SQL',
+  'Alter Any Availability Group', and 'View Server State' permissions.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAG).

source/DSCResources/DSC_SqlAGDatabase/README.md

@@ -0,0 +1,14 @@
+# Description
+
+The `SqlAGDatabase` DSC resource is used to add databases or remove
+databases from a specified availability group.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+* Target machine must be running Windows Management Framework (WMF) 5 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAGDatabase).

source/DSCResources/DSC_SqlAGListener/README.md

@@ -0,0 +1,18 @@
+# Description
+
+The `SqlAGListener` DSC resource is used to configure the listener
+for an Always On Availability Group.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+* Target machine must have access to the SQLPS PowerShell module or the SqlServer
+  PowerShell module.
+* Requires that the Cluster name Object (CNO) has been delegated the right
+  _Create Computer Object_ in the organizational unit (OU) in which the
+  Cluster Name Object (CNO) resides.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAGListener).

source/DSCResources/DSC_SqlAGReplica/README.md

@@ -0,0 +1,15 @@
+# Description
+
+The `SqlAGReplica` DSC resource is used to create, remove, and update an
+Always On Availability Group Replica.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+* 'NT SERVICE\ClusSvc' or 'NT AUTHORITY\SYSTEM' must have the 'Connect SQL',
+  'Alter Any Availability Group', and 'View Server State' permissions.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAGReplica).

source/DSCResources/DSC_SqlAgentAlert/README.md

@@ -0,0 +1,13 @@
+# Description
+
+The `SqlAgentFailsafe` DSC resource is used to add/remove the SQL Agent
+Failsafe Operator. The resource can also update the Notification method.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAgentFailsafe).

source/DSCResources/DSC_SqlAgentFailsafe/README.md

@@ -0,0 +1,13 @@
+# Description
+
+The `SqlAgentAlert` DSC resource is used to add/remove SQL Agent Alerts.
+The resource can also update the severity or message id.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAgentAlert).

source/DSCResources/DSC_SqlAgentOperator/README.md

@@ -0,0 +1,13 @@
+# Description
+
+The `SqlAgentOperator` DSC resource is used to add/remove SQL Agent Operators.
+The resource can also update the operators email address.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAgentOperator).

source/DSCResources/DSC_SqlAlias/README.md

@@ -0,0 +1,11 @@
+# Description
+
+The `SqlAlias` DSC resource is used to configure SQL Server Aliases on the node.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAlias).

source/DSCResources/DSC_SqlAlwaysOnService/README.md

@@ -0,0 +1,15 @@
+# Description
+
+The `SqlAlwaysOnService` DSC resource enables or disables SQL Server Always
+On high availability and disaster recovery (Always On HADR) for a SQL
+Server instance.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+* Target machine must be a member of a Windows Server Failover Cluster.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlAlwaysOnService).

source/DSCResources/DSC_SqlDatabase/README.md

@@ -0,0 +1,23 @@
+# Description
+
+The `SqlDatabase` DSC resource is used to create or delete a database.
+For more information about SQL Server databases, please read the following
+articles [Create a Database](https://docs.microsoft.com/en-us/sql/relational-databases/databases/create-a-database)
+and [Delete a Database](https://docs.microsoft.com/en-us/sql/relational-databases/databases/delete-a-database).
+
+This resource sets the recovery model for a database. The recovery model controls
+how transactions are logged, whether the transaction log requires (and allows)
+backing up, and what kinds of restore operations are available. Three recovery
+models exist: full, simple, and bulk-logged. Read more about recovery model in
+the article [View or Change the Recovery Model of a Database](https://msdn.microsoft.com/en-us/library/ms189272.aspx).
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+* Valid values per SQL Server version for the parameter `CompatibilityLevel`
+  can be found in the article [ALTER DATABASE (Transact-SQL) Compatibility Level](https://docs.microsoft.com/en-us/sql/t-sql/statements/alter-database-transact-sql-compatibility-level).
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlDatabase).

source/DSCResources/DSC_SqlDatabaseDefaultLocation/README.md

@@ -0,0 +1,15 @@
+# Description
+
+The `SqlDatabaseDefaultLocation` DSC resource is used to configure default
+locations for user databases. The types of default locations that can be
+changed are Data, Log, and Backup. For more information about database
+default locations, please read the article [Changing the Database Default Locations](https://technet.microsoft.com/en-us/library/dd206993.aspx).
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlDatabaseDefaultLocation).

source/DSCResources/DSC_SqlDatabasePermission/README.md

@@ -0,0 +1,18 @@
+# Description
+
+The `SqlDatabasePermission` DSC resource is used to grant, deny or revoke
+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.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlDatabasePermission).

source/DSCResources/DSC_SqlDatabaseRole/README.md

@@ -0,0 +1,15 @@
+# Description
+
+The `SqlDatabaseRole` DSC resource is used to create a database role when
+Ensure is set to 'Present' or remove a database role when Ensure is set to
+'Absent'. The resource also manages members in both built-in and user
+created database roles.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlDatabaseRole).

source/DSCResources/DSC_SqlDatabaseUser/README.md

@@ -0,0 +1,17 @@
+# Description
+
+The `SqlDatabaseUser` DSC resource is used to create database users.
+A database user can be created with or without a login, and a database
+user can be mapped to a certificate or asymmetric key. The resource also
+allows re-mapping of the SQL login.
+
+> **Note:** This resource does not yet support [Contained Databases](https://docs.microsoft.com/en-us/sql/relational-databases/databases/contained-databases).
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+
+## Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlDatabaseUser).

source/DSCResources/DSC_SqlRS/README.md

@@ -0,0 +1,40 @@
+# Description
+
+The `SqlRS` DSC resource initializes and configures SQL Reporting Services
+server.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Reporting Services 20012 or later.
+* To use parameter `UseSSL` target machine must be running SQL Server Reporting
+  Services 2012 or later.
+* If `PsDscRunAsCredential` common parameter is used to run the resource, the
+  specified credential must have permissions to connect to the SQL Server instance
+  specified in `DatabaseServerName` and `DatabaseInstanceName`, and have permission
+  to create the Reporting Services databases.
+
+## Known issues
+
+* This resource does not currently have full SSL support, please see
+  [issue #587](https://github.com/dsccommunity/SqlServerDsc/issues/587) for more
+  information.
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlRS).
+
+## Known error messages
+
+### Error: The parameter is incorrect (HRESULT:-2147024809)
+
+This is caused by trying to add an URL with the wrong format
+i.e. 'htp://+:80'.
+
+### Error: The Url has already been reserved (HRESULT:-2147220932)
+
+This is caused when the URL is already reserved. For example when 'http://+:80'
+already exist.
+
+### Error: Cannot create a file when that file already exists (HRESULT:-2147024713)
+
+This is caused when trying to add another URL using the same protocol. For example
+when trying to add 'http://+:443' when 'http://+:80' already exist.

source/DSCResources/DSC_SqlRSSetup/README.md

@@ -0,0 +1,47 @@
+# Description
+
+The `SqlRSSetup` DSC resource installs the standalone
+[Microsoft SQL Server Reporting Services](https://docs.microsoft.com/en-us/sql/reporting-services/create-deploy-and-manage-mobile-and-paginated-reports).
+
+If both `SourceCredential` and `PsDscRunAsCredential` is used then the
+credentials in `SourceCredential` will only be used to copy the
+installation media locally, and then the credentials in `PsDscRunAsCredential`
+will be used during installation. If `PsDscRunAsCredential` is not
+used, then the installation will run as SYSTEM.
+
+>To install Microsoft SQL Server Reporting Services 2016 (or older),
+>please use the resource SqlSetup.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* If `PsDscRunAsCredential` common parameter is used to run the resource,
+  the specified credential must have permissions to connect to the location
+  where the Microsoft SQL Server Reporting Services media is placed.
+* The parameter IAcceptLicenseTerms must be set to 'Yes'.
+* The parameter InstanceName can only be set to 'SSRS' since there is
+  no way to change the instance name.
+* When using action 'Uninstall', the same version of the executable as the version
+  of the installed product must be used. If not, sometimes the uninstall
+  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.
+>
+>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
+
+* [SqlRSSetup: Will always make an edition upgrade](https://github.com/dsccommunity/SqlServerDsc/issues/1311)
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlRSSetup).

source/DSCResources/DSC_SqlScript/README.md

@@ -0,0 +1,37 @@
+# Description
+
+The `SqlScript` DSC resource provides the means to run a user generated
+T-SQL script on the SQL Server instance. Three scripts are required;
+Get T-SQL script, Set T-SQL script and the Test T-SQL script.
+
+## Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server 2012 or later.
+* Target machine must have access to the SQLPS PowerShell module or the SqlServer
+  PowerShell module.
+
+## Known issues
+
+* There is a known problem running this resource using PowerShell 4.0.
+See [issue #273](https://github.com/dsccommunity/SqlServerDsc/issues/273)
+for more information.
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlScript).
+
+## Scripts
+
+### Get T-SQL Script (GetFilePath)
+
+The Get T-SQL script is used to query the status when running the cmdlet
+Get-DscConfiguration, and the result can be found in the property `GetResult`.
+
+### Test T-SQL Script (TestFilePath)
+
+The Test T-SQL script is used to test if the desired state is met. If Test
+T-SQL raises an error or returns any value other than 'null' the test fails, thus
+the Set T-SQL script is run.
+
+### Set T-SQL Script (SetFilePath)
+
+The Set T-SQL script performs the actual change when Test T-SQL script fails.