Merge pull request #8636 from TrishaMc/install-sql-server-with-powershell-desired-state-configuration2

ShawnJackson · web-flow · commit 17885d29f36e · 2019-01-03T19:33:01.000-06:00
Edit pass: Install sql server with powershell desired state configuration2
diff --git a/docs/database-engine/install-windows/install-sql-server-with-powershell-desired-state-configuration.md b/docs/database-engine/install-windows/install-sql-server-with-powershell-desired-state-configuration.md
@@ -1,6 +1,6 @@
 ---
 title: "Install SQL Server with PowerShell Desired State Configuration | Microsoft Docs"
-description: "Learn how to install SQL Server using PowerShell Desired State Configuration (DSC)."
+description: "Learn how to install SQL Server by using PowerShell Desired State Configuration (DSC)."
 ms.custom: ""
 ms.date: "10/26/2018"
 ms.devlang: PowerShell
@@ -15,34 +15,43 @@ monikerRange: ">=sql-server-2016||=sqlallproducts-allversions"
 
 # Install SQL Server with PowerShell Desired State Configuration
 
-How many times have you clicked through the SQL Server installation interface just clicking the same old buttons, entering the same old information, not giving it much of a second thought? Then the installation finishes and the realization of "I forgot to specify the DBA group in the sysadmin role" hits. Now you have to spend precious time dropping into single-user mode, adding the appropriate users or groups, bringing SQL back up in multi-user mode, and testing. What's worse is now the confidence of the entire installation is shaken. "What else did I forget?" I for one have been in that situation more than once.
+Have you ever gone through the SQL Server installation interface just by selecting the same buttons, entering the same information, and not giving it a second thought? The installation finished, but you forgot to specify the DBA group in the **sysadmin** role. Then you had to do these things:
+* Drop into single-user mode.
+* Add the appropriate users or groups.
+* Bring SQL Server back up in multiuser mode.
+* Test. 
 
-Enter [PowerShell Desired State Configuration (DSC)](https://docs.microsoft.com/powershell/dsc/overview). Using DSC I can build one configuration template that can be reused over hundreds and thousands of servers. Depending on the build, I may have to tweak a few of the setup parameters, however that's not a big deal because I can still keep all of the standard settings in place. The beautiful thing is it eliminates the possibility that will forget to enter an important parameter after spending a sleepless night caring for my kids.
+What's worse is now the confidence of the entire installation is shaken. "What else did I forget?" you might ask yourself.
 
-In this article, I will explore the initial setup of a standalone instance of SQL Server 2017 on Windows Server 2016 using the SqlServerDsc DSC resource. Some prior knowledge of DSC will be helpful as I will not explore the how DSC works.
+Read about [PowerShell Desired State Configuration (DSC)](https://docs.microsoft.com/powershell/dsc/overview). By using DSC, you build one configuration template that you can reuse over hundreds and thousands of servers. Depending on the build, you might have to tweak a few of the setup parameters. But that's not a significant issue because you can keep all of the standard settings in place. It eliminates the possibility that you'll forget to enter an important parameter.
+
+This article explores the initial setup of a standalone instance of SQL Server 2017 on Windows Server 2016 by using the **SqlServerDsc** DSC resource. Some prior knowledge of DSC is helpful as we won't explore how DSC works.
 
 The following items are required for this walkthrough:
 
-- A machine running Windows Server 2016
-- SQL Server 2017 installation media
-- The SqlServerDsc DSC resource (version 10.0.0.0 is the current release at the time of this writing)
+- A machine that runs Windows Server 2016.
+- SQL Server 2017 installation media.
+- The **SqlServerDsc** DSC resource.
 
 ## Prerequisites
 
-In most cases, DSC will be used to handle the prerequisite requirements. However, for the purposes of this demo, I will handle the prerequisites manually.
+In most cases, DSC is used to handle the prerequisite requirements. But for the purposes of this demo, we handle the prerequisites manually.
 
 ## Install the SqlServerDsc DSC resource
 
-The [SqlServerDsc](https://www.powershellgallery.com/packages/SqlServerDsc) DSC resource can be downloaded from the [PowerShell Gallery](https://www.powershellgallery.com/) using the [Install-Module](https://docs.microsoft.com/powershell/module/powershellget/Install-Module?view=powershell-5.1) cmdlet. _Note: Ensure PowerShell is running "As Administrator" to install the module._
+Download the [SqlServerDsc](https://www.powershellgallery.com/packages/SqlServerDsc) DSC resource from the [PowerShell Gallery](https://www.powershellgallery.com/) by using the [Install-Module](https://docs.microsoft.com/powershell/module/powershellget/Install-Module?view=powershell-5.1) cmdlet. 
+
+> [!NOTE]
+> Make sure PowerShell is running **As Administrator** to install the module.
 
 ```PowerShell
 Install-Module -Name SqlServerDsc
 ```
 
-Obtain the SQL Server 2017 Installation Media
-Download the SQL Server 2017 installation media to the server. I downloaded SQL Server 2017 Enterprise from my Visual Studio subscription and copied the ISO to "C:\en_sql_server_2017_enterprise_x64_dvd_11293666.iso".
+### Get the SQL Server 2017 installation media
+Download the SQL Server 2017 installation media to the server. We downloaded SQL Server 2017 Enterprise from a Visual Studio subscription and copied the ISO to `C:\en_sql_server_2017_enterprise_x64_dvd_11293666.iso`.
 
-Now the ISO must be extracted to a directory.
+Now the ISO must be extracted to a directory:
 
 ```PowerShell
 New-Item -Path C:\SQL2017 -ItemType Directory
@@ -57,7 +66,7 @@ Dismount-DiskImage -ImagePath 'C:\en_sql_server_2017_enterprise_x64_dvd_11293666
 
 ### Configuration
 
-Create the configuration function that will be called to generate the [Managed Object Format (MOF)](https://docs.microsoft.com/windows/desktop/WmiSdk/managed-object-format--mof-) document(s).
+Create the configuration function that will be called to generate the [Managed Object Format (MOF)](https://docs.microsoft.com/windows/desktop/WmiSdk/managed-object-format--mof-) documents:
 
 ```PowerShell
 Configuration SQLInstall
@@ -66,7 +75,7 @@ Configuration SQLInstall
 
 ### Modules
 
-Import the modules into the current session. These modules tell the configuration document how to build the MOF document(s) and tells the DSC engine how to apply the MOF document(s) to the server.
+Import the modules into the current session. These modules tell the configuration document how to build the MOF documents. They also tell the DSC engine how to apply the MOF documents to the server:
 
 ```PowerShell
 Import-DscResource -ModuleName SqlServerDsc
@@ -76,7 +85,7 @@ Import-DscResource -ModuleName SqlServerDsc
 
 #### .NET Framework
 
-SQL Server relies on the .NET framework, therefore we need to ensure it is installed prior to installing SQL Server. The WindowsFeature resource is utilized to install the Net-Framework-45-Core Windows Feature.
+SQL Server relies on the .NET Framework. So we need to make sure it's installed before we install SQL Server. The **WindowsFeature** resource is used to install the **Net-Framework-45-Core** Windows feature:
 
 ```PowerShell
 WindowsFeature 'NetFramework45'
@@ -88,18 +97,21 @@ WindowsFeature 'NetFramework45'
 
 #### SqlSetup
 
-The SqlSetup resource is used to tell DSC how to install SQL Server. The parameters required for a basic installation are:
+The **SqlSetup** resource is used to tell DSC how to install SQL Server. The parameters required for a basic installation are as follows:
+
+- **InstanceName**. The name of the instance. Use **MSSQLSERVER** for a default instance.
+- **Features**. The features to install. In this example, we install only the **SQLEngine** feature.
+- **SourcePath**. The path to the SQL installation media. In this example, we stored the SQL installation media in `C:\SQL2017`. A network share can minimize the space used on the server.
+- **SQLSysAdminAccounts**. The users or groups who are to be a member of the **sysadmin** role. In this example, we grant the local Administrators group **sysadmin** access. 
 
-- **InstanceName**: The name of the instance. Utilize MSSQLSERVER for a default instance.
-- **Features** The features to install. In this example, I am only installing the SQLEngine feature.
-- **SourcePath**: The path to the SQL installation media. In this example, I stored the SQL installation media in "C:\SQL2017". A network share can be utilized to minimize the space used on the server.
-- **SQLSysAdminAccounts**: The users or groups who are to be a member of the sysadmin role. In this example, I am granting the local Administrators group sysadmin access. _Note: This configuration is not recommended in a high security environment._
+> [!NOTE]
+> We don't recommend this configuration in a high-security environment.
 
-A full list and description of the parameters available on SqlSetup are available on the [SqlServerDsc GitHub respository](https://github.com/PowerShell/SqlServerDsc/tree/master#sqlsetup).
+A full list and description of the parameters available on **SqlSetup** are available on the [SqlServerDsc GitHub repository](https://github.com/PowerShell/SqlServerDsc/tree/master#sqlsetup).
 
-The SqlSetup resource is odd because it only installs SQL and DOES NOT maintain the settings that are applied. For example, if the SQLSysAdminAccounts are specified at installation time, an admin could add or remove logins from to or from the sysadmin role and the SqlSetup resource wouldn't care. If it is desired that DSC enforces the membership of the sysadmin role, the [SqlServerRole](https://github.com/PowerShell/SqlServerDsc/tree/master#sqlserverrole) resource should be utilized.
+The **SqlSetup** resource installs only SQL Server and **doesn't** maintain the settings that are applied. An example is if the **SQLSysAdminAccounts** are specified at installation time. An admin might add or remove sign-ins to or from the **sysadmin** role. But the **SqlSetup** resource won't be affected. If you want DSC to enforce the membership of the **sysadmin** role, use the [SqlServerRole](https://github.com/PowerShell/SqlServerDsc/tree/master#sqlserverrole) resource.
 
-#### Complete configuration
+#### Finish configuration
 
 ```PowerShell
 Configuration SQLInstall
@@ -130,40 +142,40 @@ Configuration SQLInstall
 
 ### Compile the configuration
 
-Dot-source the configuration script:
+Dot source the configuration script:
 
 ```PowerShell
 . .\SQLInstallConfiguration.ps1
 ```
 
-Execute the configuration function:
+Run the configuration function:
 
 ```PowerShell
 SQLInstall
 ```
 
-A directory will be created in the working directory called "SQLInstall" and will contain a file call "localhost.mof". Examining the contents of the MOF will show the compiled DSC configuration.
+A directory called **SQLInstall** is created in the working directory. It contains a file called **localhost.mof**. Examine the contents of the MOF, which shows the compiled DSC configuration.
 
 ### Deploy the configuration
 
-To start the DSC deployment of SQL Server, call the Start-DscConfiguration cmdlet. The parameters provided to the cmdlet are:
+To start the DSC deployment of SQL Server, call the **Start-DscConfiguration** cmdlet. The following parameters are provided to the cmdlet:
 
-- **Path**: The path to the folder containing the MOF documents to deploy. (for example "C:\SQLInstall")
-- **Wait**: Wait for the configuration job to complete.
-- **Force**: Override any existing DSC configurations.
-- **Verbose**: Show the verbose output. Useful when pushing a configuration for the first time to aid in troubleshooting.
+- **Path**. The path to the folder that contains the MOF documents to deploy. An example is `C:\SQLInstall`.
+- **Wait**. Wait for the configuration job to finish.
+- **Force**. Override any existing DSC configurations.
+- **Verbose**. Show the verbose output. It's useful when you push a configuration for the first time to aid in troubleshooting.
 
 ```PowerShell
 Start-DscConfiguration -Path C:\SQLInstall -Wait -Force -Verbose
 ```
 
-As the configuration applies, the Verbose output will show you what is happening and give you a warm and fuzzy feeling that SOMETHING is happening. As long as no errors (red text) are thrown, when "Operation 'Invoke CimMethod' complete." is displayed on the screen, SQL should be installed.
+As the configuration applies, the verbose output shows you what's happening. As long as no errors (red text) are thrown, when **Operation 'Invoke CimMethod' complete** appears on the screen, SQL Server should be installed.
 
 ## Validate installation
 
 ### DSC
 
-The [Test-DscConfiguration](https://docs.microsoft.com/powershell/module/psdesiredstateconfiguration/test-dscconfiguration) cmdlets can be utilized to determine if the current state of the server, in this case the SQL installation, meets the desired state. The result of Test-DscConfiguration should be "True".
+The [Test-DscConfiguration](https://docs.microsoft.com/powershell/module/psdesiredstateconfiguration/test-dscconfiguration) cmdlets can determine if the current state of the server meets the desired state. In this case, it's the SQL Server installation. The result of **Test-DscConfiguration** should be **True**:
 
 ```PowerShell
 PS C:\> Test-DscConfiguration
@@ -172,7 +184,7 @@ True
 
 ### Services
 
-The services listing should now return SQL Server services
+The services list now returns SQL Server services:
 
 ```PowerShell
 PS C:\> Get-Service -Name *SQL*
@@ -198,6 +210,6 @@ PS C:\> & sqlcmd -S $env:COMPUTERNAME
 
 [Windows PowerShell Desired State Configuration Overview](https://docs.microsoft.com/powershell/dsc/overview)
 
-[Install SQL Server from the Command Prompt](../../database-engine/install-windows/install-sql-server-from-the-command-prompt.md)
+[Install SQL Server from the command prompt](../../database-engine/install-windows/install-sql-server-from-the-command-prompt.md)
 
-[Install SQL Server using a configuration file](../../database-engine/install-windows/install-sql-server-using-a-configuration-file.md)
+[Install SQL Server by using a configuration file](../../database-engine/install-windows/install-sql-server-using-a-configuration-file.md)
