SharePoint DSC Gotchas and Best Practices

In the Microsoft Virtual Academy on SharePoint Automation with DSC my colleague Brian Farnhill and I recorded in June of 2017, we dedicated an entire module to SharePointDSC best practices. I thought I’d take a few minutes to put the items we discussed during that session on paper. This article will act as a list of the most frequent issues and problem encountered by people using SharePoint DSC. It will be updated as the tool evolves.

Frequent Issues

Installation of Prerequisites, Binaries or Language Pack is Stuck

Symptom:

This is one of the most frequent issue people encountered when starting off with SharePoint DSC. When running the configuration using Start-DSCConfiguration, or when in Pull mode, the installation seems to get stuck when trying to install components (prerequisites, binaries, or language pack). No errors are being thrown.

Most Likely Reason:

There is some level of User Account Control set on the installation file. In most cases this issues will happen when the installation is done from a Network Drive. Upon executing the installation of the component, windows triggers a prompt for the user to confirm the execution of an executable that was launched from an untrusted location, but because this was initiates from a background thread, it is impossible to ever approve that prompt and the installation gets stuck.

In order to test if this is your issue, launch a new PowerShell session, running as the user defined in the PsDscRunAsCredential parameter of the execution block. From there, run the following line of PowerShell. If there are any prompts that appear, that means that the installation is most likely stuck because of the User Account Control.

Start-Process -FilePath <Path to the Installer file> -Wait -PassThru

Solution:

The solution here is two fold. First off, we recommend you turn off the User Account Control feature for the user running the PsDscRunAsCredential installation block in your script. As a second step, launch Internet Explorer and go to Internet Explorer Settings. From there, go to the Security tab, click on the Local Intranet Zone, then click on the Sites button. In the prompt, click on the Advanced button, this will open the window that let’s you specify addresses to identify as being part of the Local Intranet Zone. In that window, type in the location of the Network share (or other common location) where the installer file is located, and click on Add.

Using a completely DSC based solution, you could use the xSystemSecurity module to disable the User Account Control prompt as follow:

# Make sure you import the module
Import-DSCResource -ModuleName "MSFT_xSystemSecurity"

# Put this in the node's configuration;
xUAC NeverNotifyAndDisableAll
{
    Setting = "NeverNotifyAndDisableAll"
}

Best Practices

Master Node

SharePoint is a distributed system, meaning that not all components run on the same server, and that most of the content and configuration is actually stored in a SQL Server database, that all servers in the farm can access at any time. When you define a DSC configuration file, you should identify one of the servers in your farm to be what I refer to has your Master Node. this is the node on which you will define most of the components in the Farm. All other nodes, referred to as secondary nodes in this scenario, should only define resources that allow them to install the required binaries and updates, to join the farm, and the service instances to run on that server. All other components should ONLY be defined on the Master Node.For example, don’t go and define an SPSite entry on multiple node, it is not necessary. SPSite objects are defined in the Content Databases anyway, so you don’t need every server in the farm to attempt to create them.

Take another example where you wish to update the DSC definition of a certain feature on a Site Collection to be disabled instead of enabled. If you properly defined your configuration, you only have to update the DSC definition for that feature within a single node (Master Node) in the DSC configuration file, but let’s imagine you have it defined within every node instead. You now have to go and modify it multiple times within your configuration, and that opens the door to mistakes. Let’s say our farm has 3 servers, that you updated the feature’s definition for Server #1 and #2, but forgot to update the definition in server #3. To make things worst, you’ve set all 3 servers’ Local Configuration Manager (LCM) to be set to ApplyAndAutocorrect. We all know that by default, the ConfigurationMode for the LCM will check every 15 minutes to make sure it is in its desired state, but that 15 minutes may not happen exactly at the same time on each of the servers in the farm. Imagine that at 10h a.m., server one has its LCM kick in, and realize that the feature has to be turned on based on the new definition. It will go and disable the feature. Now, let’s pretend that server #3’s LCM kicks in at 10h05 a.m., but since that server doesn’t have the proper definition, it re-disables the feature that was just turned on 5 minutes ago by Server #1. You can see where this is going, and that can cause a lot of headaches for your admin team. DO NOT DECLARE components (other than SPFarm, SPIntall, SPInstallPrereqs, and SPServiceInstance) on more than one server in the configuration.

Use ApplyAndAutocorrect with Caution

We took a decision a few years back not to let SharePointDSC deal with content such as SPList, SPContentTypes, etc. However, we do deal with items such as SPSite and SPWeb that are stored in the Content Database. The real beauty behind SharePoint is that it lets users deal with their content as they see fit. Users can easily go and create a new list, play with it for a few days, and then decide to delete it after because their tests are done.

PowerShell Desired State Configuration is very powerful. When you set the Local Configuration Manager of a server to ApplyAndAutocorrect, the server will automatically attempt to bring itself back into its defined Desired State Configuration whenever it detects that it drifted away from that configuration. While this feature is very powerful, my recommendation is not to set the LCM in ApplyAndAutocorrect the moment your configuration includes either and SPWeb or SPSite resource declaration, unless you are absolutely certain and aware of what this will do to your environment.

Imagine the following scenario where you have an environment which declares 3 SPWeb (say Web1, Web2, and Web3), and for which the LCM is set to ApplyAndAutocorrect. Come spring, the Information Management (IM) team at your organization undertakes a major cleanup project where they want to get rid of sites that have not been active in the past 6 months. There 3 SPWeb sites defined in the configuration, have been identified by the IM team to be deleted. The IM manager goes in and deletes the 3 sites, then sends an email to the IM director to let him know that the cleanup has been done. Two weeks after the IM director stumbles upon SPWeb2, which the IM Manager claimed to have deleted 14 days ago. Well, the moment the site was originally deleted by the IM Manager, 15 minutes after, the LCM detected that it was no longer in its desired state, and since its LCM is set to ApplyAndAutocorrect, it automatically recreated the site. Imagine the confusion this can cause.

this article will be updated on an on-going basis.

What’s New in SharePointDSC.Reverse 1.9.0.0

The DSC Resource Kit Wave that includes the 1.9.0.0 release of SharePointDSC has not yet been published to the PowerShell Gallery. In order to try out the 1.9.0.0 version of the ReverseDSC Orchestrator Script for SharePoint, you will need to manually download the following modules:

As well as grab the latest version of the Orchestrator script from its official GitHub Repository.

The latest release of the ReverseDSC Orchestrator Script for SharePoint is the biggest release we’ve had so far and it is packed with new features that will make it even easier for users to migrate their on-premises SharePoint 2013 or 2016 Farms from their on-premises data centers to the cloud. This release drastically changes the way the orchestrator script does its extraction. The following is a complete list of all improvements that have been included in the latest release.

New Features

  • Configuration Data: A new ConfigurationData.psd1 file will be generated with all extractions. This external .psd1 file exposes all parameters that are specific to the source SharePoint environment. If you are planning on deploying a copy of the extracted SharePoint Farm into a new environment (Azure, on-premises, etc.), all you need to do is update the values contained in that file to reflect the destination environment. For more information regarding what parameters are now exposed in the Configuration Data, please refer to the Configuration Data wiki Page.
  • Extraction Modes: Previous versions of the Orchestrator Script would expose a -Lite switch, which allow the extraction process to skip certain DSC Resources such as the Timer Job States, Features, SPWeb, etc. In version 1.9.0.0, we introduce the concept of Extraction Modes, where each mode will capture a different set of DSC resources. to learn more about what set of DSC Resource will be extracted in each mode, please refer to Extraction Mode wiki page.
  • Full Installation: Previous versions of the Orchestrator Script extracted resources starting at the SPFarm level, meaning that the machines you were trying to replicate your environment on had to have the SharePoint bits installed on them already for the configuration to get applied. With the new version, the SPInstallPrereqs and SPInstall resources are automatically included in the configuration file. The Configuration Data files drives whether or not these are included in the compiled MOF file using the FullInstallation. parameter. If this parameter is set to $True in the configuration data, then the compiled MOF instances will attempt to install the SharePoint Prerequisites (using the Online Mode) and the binaries on the servers being configured.

New Resources Supported

SharePointDSC.Reverse 1.9.0.0 introduces support for the following Resources:

  • SPInstallPrereqs
  • SPInstall
  • SPMachineTranslationServiceApp

Deprecated Features

the following switches have been deprecated with the 1.9.0.0 Release. The equivalent result can now be achieved 9in most part) by using the -Mode Lite parameter.

  • -Lite
  • -SkipFeatures
  • -SkipWebs
  • -SkipHealthRules
  • -SkipSearchFileType
  • -SkipTimerJobState
  • -SkipUserProfile