Brian Farnhill

Moving my blog!

Brian Farnhill — Thu, 26 Oct 2017 14:56:42 GMT

I've made the decision to move my blog to a personal website - don't worry though, I'll continue posting about similar things so the content won't change! Head on over to https://brianfarnhill.com/blog/ and check it out (don't forget to update your RSS readers!)

Using the launch.json file in VS code for improved PowerShell debugging

Brian Farnhill — Wed, 27 Sep 2017 11:42:12 GMT

Anyone that has talked to me recently about how I write PowerShell scripts will know that Visual Studio Code is my new one and only! You can write PowerShell scripts in there and hit F5 to have a similar debugging experience to what you would get in PowerShell ISE - but did you know that you can extend that to make it easier to debug and test different scenarios from within VS Code? If the answer to that is no, then read on!

What is launch.json?

VS Code has a number of files that it will look for when you open a directory that it will use to customise the way it behaves, launch.json is one of these. If you place this file at "/.vscode/launch.json" within a directory that you are working with, you'll be able to create customised ways to launch the debugger for your project. This applies to any language that VS Code supports debugging for, not just PowerShell - but let me show you what I'm talking about in some detail.

Working without launch.json

First lets talk about what happens when you debug a PowerShell script in VS Code without a launch.json file in place. In this screen shot you can see a few things. Firstly note that in the debug tab I see "No Configurations" - this is what happens when there is no launch.json file (or when you have one that has an empty configurations element in it). But you can see I can still press F5 (or use the little green arrow icon in the debug tab) to run my script and VS Code will launch the current PowerShell file and attach the debugger to it using the integrated PowerShell host. The last thing you'll notice is that next to the "No Configurations" drop down that you see a cog shaped icon with a red dot over it - this is an indicator that you don't have a launch.json file or that there is some sort of issue with it. If you click on this you'll actually see that VS code will create a launch.json file for you with a couple of default configurations (which will be based on PowerShell because we have a PowerShell file open in our directory)

The default PowerShell launch.json file

When you add the default launch.json file to a folder with PowerShell files you'll see the following new "Configurations" that appear in the drop down that previously said "No configurations" Now these are all fairly common scenarios for when you want to debug a PowerShell script, here are some of the times you might use each of them:

Launch current file - this is the same as what you had without a launch.json file, it will launch the currently open file and attach the debugger
Launch current file in a temporary console - this is similar to the above, but instead of using the current integrated PowerShell host VS code will create a new host just to execute this file, and it will remove the host when the script completes. This is great if you need to validate your script in a perfectly clean PowerShell session on each test run, just remember to put a pause or breakpoint at the end of your script if you need to see the output, as the host will immediately close when the script finishes
Launch current file /args prompt - This option will run the current file, the same as the first option does - but before it runs you will be prompted to enter any arguments that should be passed to the script when it runs. It looks like this:
Attach to host process - This option will allow you to attach to an existing process. This option is useful if you are trying to debug PowerShell that is executing in an external process (such as debugging a DSC resource). You'll be prompted to select which process to attach to and you can debug from there
Interactive session - This option will simply attach the debugger to the current integrated PowerShell host without actually running a script. You can then type commands in to the session window as you please and any breakpoints that are triggered in scripts will still be hit as usual, giving you the flexibility to call anything you want in any way that you can possibly call it from PowerShell

So you can see that with the default launch.json file you gain quite a lot of flexibility beyond the old 'F5' experience. But we can take things further than this.

Customising launch.json

Now lets assume that you want to debug your scripts in a way that doesn't line up with one of those default options, you can actually configure the launch.json file to have custom configurations that you create yourself. In this example, I'm going to work with a basic script file called "test.ps1" which looks like this:

param(
 [Parameter(Mandatory=$false)]
 [ValidateSet("Date", "Time")]
 [String]
 $OutputMode = "Time"
)
switch($OutputMode)
{
 "Date" {
 $dateString = [DateTime]::Now.ToShortDateString()
 }
 "Time" {
 $dateString = [DateTime]::Now.ToShortTimeString()
 }
}
Write-Output "I was executed at $dateString"

Basically all the script does is to output either the current date or the current time, based on a parameter that is optionally passed in to the file itself. Now if you want to add a new configuration you can open the launch.json file up and use the "Add configuration" button, which will then let you select from a range of "stubs" that you can choose for your configuration as a starting point.

Here there are some PowerShell options in the list that look similar to the defaults. For my example I'm going to choose to add the "launch script" activity - here I can tell VS Code to run a specific script file (no matter what is open in the current window) and I can optionally add arguments to this call as well. I'll add two activities here so I can call test.ps1 with each of the argument options from the debugger there, one for "Date" and the other for "Time". The two new activities in launch.json look like this:

 {
 "type": "PowerShell",
 "request": "launch",
 "name": "Run test.ps1 with Date",
 "script": "${workspaceRoot}/test.ps1",
 "args": ["Date"],
 "cwd": "${workspaceRoot}"
 },
 {
 "type": "PowerShell",
 "request": "launch",
 "name": "Run test.ps1 with Time",
 "script": "${workspaceRoot}/test.ps1",
 "args": ["Time"],
 "cwd": "${workspaceRoot}"
 }

Now as soon as I have added these to launch.json I see that they appear in my configurations drop down... ... and when I select each one, I see my test script will run with the debugger attached but with the appropriate arguments passed This is a pretty simple example of how you can customise the launch.json file - I'm sure next time you find yourself debugging PowerShell scripts that you can find some ways to use this. Another example of how I'm using it is a recent change to the SharePointDsc project - we are adding the option to run the currently open unit test file but to simulate either SharePoint 2013 or 2016 based on which arguments are passed to the test file. Hopefully this is useful for you as well. Happy debugging!

"The provided value for the template parameter is not valid" in ARM template deployments

Brian Farnhill — Thu, 14 Sep 2017 12:58:32 GMT

I've come across this one before, but I hit it again today and I wanted to share the details of what happened. Basically the scenario is this, I have an ARM template that I want to deploy and it takes in parameters. The deployment needs to run through PowerShell using the Azure RM PowerShell cmdlets. When I call New-AzureRmResourceGroupDeployment I get the error that says "The provided value for the template parameter is {parameter name} not valid", and this is where things start getting weird. Here is an example of how I was calling it:

New-AzureRmResourceGroupDeployment -ResourceGroupName "MyRGName" `
                                   -Name "MyDeployment" `
                                   -TemplateUri "https://url.of/MyTemplate.json" `
                                   -TemplateParameterObject @{
                                       Parameter1 = "Value"
                                       Parameter2 = "Other value"
                                   }

Now what you're looking at here is perfectly valid PowerShell - it gets parsed by the engine, compiled and executed as you would expect it to, but for some reason I was getting the error about Parameter1 not being a valid value. This error typically comes up where there is a data type mismatch or some other type of parameter validation error - such as asking for a string in the template but you give it a number, or you didn't provide a mandatory value, or those sorts of things. But in my case, none of that was true - the data type was a string and there was a value and that's all there was to it. I even put the parameter values in to an external file and ran that, and that worked! So I knew there was no issue with the value I was providing, so I had to figure out why it wouldn't accept it in the format I was providing. I started trying things, I tried taking the hashtable out in to a separate variable and that didn't seem to help - but then I found another way of calling things that seemed to do the trick:

$params = @{}
$params.Add("Parameter1", "Value")
$params.Add("Parameter2", "Other value")

New-AzureRmResourceGroupDeployment -ResourceGroupName "MyRGName" `
                                   -Name "MyDeployment" `
                                   -TemplateUri "https://url.of/MyTemplate.json" `
                                   -TemplateParameterObject $params

For those not familiar, the first line of that example is creating a new and empty hashtable (it's the equivalent of running 'New-Object -TypeName System.Collections.Hashtable'). From there I call the .Add() method to add each item to the hashtable rather than doing it inline like I was doing in the first example. Now I've done this both ways in separate PowerShell windows and I absolutely cannot for the life of me pick a difference between a hashtable declared in the first example and the second one. They are the same object time, they compare the same, they have the same keys and values ... and yet for some reason when I pass the second example in to the Azure RM cmdlets it works, while the first is clearly losing the value somewhere along the way. So I don't have an explanation on the "why" in this case, but I can tell you that the second example works where the first one doesn't. I've observed this behavior from both my laptop when I run cmdlets, as well as in Azure Automation when I try to do a deployment from a runbook as well, so look out for it anywhere the RM cmdlets run. I hope this helps other people get around this one if you come up against it!

Adding additional intellisense to VS Code when editing PowerShell scripts

Brian Farnhill — Mon, 21 Aug 2017 10:18:31 GMT

Most people that I talk to about my experiences writing PowerShell scripts these days will know that Visual Studio Code is my absolute preference for editor these days. It's a great tool with lots of little tricks to help you improve your productivity - and recently I came across another one to help when I work on SharePoint related scripts for SharePointDsc, and this is how I add intellisense for SharePoint PowerShell cmdlets when I'm authoring scripts on my laptop (which doesn't have SharePoint installed on it). If you start to rip apart how VS Code provides it's intellisense for PowerShell you'll see that it is able to do so through the use of a PowerShell Integrated Terminal - the program keeps this open in the background so that it can make calls to this session to get details to aid it's intellisense and other PowerShell interactivity. Now by default if I try typing something like "New-SPSite" in to this PowerShell file you'll see that the intellisense doesn't give me anything back to help. But if we know that VS Code draws its intellisense data from the PowerShell session, we can actually load the SharePoint cmdlets up and have them available. Now if I was running VS Code from a machine that has SharePoint installed it would be easy, I could just type the command to load the snap-in to the terminal and the cmdlets would then be available. However given I don't have SharePoint installed on my laptop that isn't an option. I do however know that to make sure the unit tests for SharePointDsc run that we keep non-functional copies of the SharePoint PowerShell cmdlets in what we call "stub" files, which will provide me enough of a structure to get this intellisense without needing SharePoint installed (if you are curious about how we came up with this approach, I have a previous blog post that addresses this topic). So if I want to load those up so I can add the intellisense I just need to use Import-Module to the path of either the 2013 or the 2016 cmdlets.

Import-Module C:\repos\SharePointDsc\Tests\Unit\Stubs\SharePoint\16.0.4456.1000\Microsoft.SharePoint.PowerShell.psm1

In that example I have the source code for SharePointDsc saved at C:\repos\SharePointDsc - so update the path accordingly to where you have the code stored. But once I have run that command you'll see that the intellisense lights up in full! This makes it much easier to author scripts without needing to have SharePoint installed, improving my productivity when authoring SharePointDsc. You could use these for any SharePoint script, not just working with SharePointDsc - just make sure you have the code for SharePointDsc around to load the stubs up and then you can use this for any script. I hope that helps improve how you write your scripts guys!

Getting IDs to use with the Package DSC resource

Brian Farnhill — Tue, 04 Jul 2017 11:34:07 GMT

One of the questions I get from customers who are looking at using the Package DSC resource to install MSI's and executables is "What is the ProductID for the installer I want to run?". If you look at the documentation the ProductID is meant to be a unique identified for the product you are installing, but how can you figure out what the correct value for any given installation is? Lucky for us you can actually use a little bit of PowerShell to look this up after you manually install the product once. Let me give you an example, I recently had to write a DSC script which would install SQL Server Management Studio 17.1 with DSC, so here is the approach I took. Step one: Manually install the product somewhere This is pretty straightforward - but we need to manually install it once so that we can look up the product ID from the registry after the fact. We can uninstall it after we are done if you like - I tend to provision a quick virtual machine in Azure for this to get the ID and then I can delete the VM after I'm done with it. Step two: Find the ID with PowerShell Since all the IDs of products that are installed on a machine are stored in the registry, it's actually quite straightforward to interrogate the registry to get a list of products with their corresponding ID is. Here is the script I use to output the list of installed products:

$x86Path = "HKLM:\Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*"
$installedItemsX86 = Get-ItemProperty -Path $x86Path | Select-Object -Property DisplayName, PSChildName
    
$x64Path = "HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*"
$installedItemsX64 = Get-ItemProperty -Path $x64Path | Select-Object -Property DisplayName, PSChildName

$installedItems = $installedItemsX86 + $installedItemsX64
$installedItems | Where-Object -FilterScript { $null -ne $_.DisplayName } | Sort-Object -Property DisplayName | Out-GridView

This will output you a GridView in PowerShell that looks a little like this And once we have it in a GridView we can actually add filters pretty easily as well Now we can see what the GUID is for SQL Management Studio 17.1 and I can now use this to make a DSC resource Step three: Create the DSC resource Now that I have the ID I can craft my resource

Package InstallSSMS
{
    Ensure = "Present"
    Name = "SSMS-Setup-ENU"
    Path = "C:\Software\ssms2016\SSMS-Setup-ENU.exe"
    Arguments = "/install /passive /norestart"
    ProductId = "b636c6f4-2183-4b76-b5a0-c8d6422df9f4"
}

Here you can see I've used the ID we retrieved in step 2 as the ProductId attribute, and that I'm also passing arguments to make sure the installer won't need any user input (remember, DSC runs in the background so just running the installer on it's own without those arguments won't help).

But that's all there is to it - a nice simple script to help you figure out the ProductID values to use in your package resource. Happy DSC'ing!

Running Azure Automation runbooks from IFTTT tasks

Brian Farnhill — Wed, 09 Nov 2016 09:36:43 GMT

I recently had an idea (ok lets call it 'collaboratively came up with while talking to one of the grads in our office) to look at ways that I could trigger runbooks in my Azure Automation account from my phone. The specific issue we were looking to solve in this case was "how can I easily shut down all the VMs in my subscription from my phone if I forget to turn them off". Now I already have a runbook that was scheduled to shut down the VMs every night at 11pm as a 'just in case' but surely there was a better way if I remembered before than to rely on that automation schedule. After a little bit of thought, the idea of create a "do button" from IFTTT (stands for "if this then that", great little automation site that I recommend you check out if you haven't used it already) seemed to be the perfect solution for me. So here's a run through of the solution from start to end.

Creating the runbook

For my example here my runbook I wanted to look for all Virtual Machines in my subscription and shut them down to avoid excess billing. The script I use for this is fairly straightforward:

$connectionName = "AzureRunAsConnection"
try
{
    $servicePrincipalConnection = Get-AutomationConnection -Name $connectionName        

    Add-AzureRmAccount `
        -ServicePrincipal `
        -TenantId $servicePrincipalConnection.TenantId `
        -ApplicationId $servicePrincipalConnection.ApplicationId `
        -CertificateThumbprint $servicePrincipalConnection.CertificateThumbprint | Out-Null
}
catch 
{
    if (!$servicePrincipalConnection)
    {
        $ErrorMessage = "Connection $connectionName not found."
        throw $ErrorMessage
    } 
    else
    {
        Write-Error -Message $_.Exception
        throw $_.Exception
    }
}

Write-Output -InputObject "Looking for VMs that are running"
Get-AzureRmVm | ForEach-Object -Process {
    $status = Get-AzureRmVM -ResourceGroupName $_.ResourceGroupName -Name $_.Name -Status
    if($status.Statuses | Where-Object -FilterScript { $_.Code -match "PowerState/running" })  
    {
        Write-Output "Stopping VM [$($_.Name)] from Resource Group [$($_.ResourceGroupName)]"
        $_ | Stop-AzureRmVM -Force
    }
}

This bit of script basically calls out all the VMs in the subscription, checks their power state and if they are running, we pipe out to Stop-AzureRMVM to tell Azure to de-provision the virtual machines.

Creating a webhook

The next piece of the puzzle is to create a webhook on the runbook. This allows the runbook to be triggered by a specific URL being called. To create a webhook for our runbook we simply go in to the runbook in the Azure portal, select "webhooks" and then select the "add webhook" at the top. You'll be presented with a screen like this: Here you set whether or not a webbook can be enabled, when it expires (it's a good idea from a security stand point to not make this a never ending period of time, rather roll these over and use new URLs at regular intervals to keep them secret and secure) and you see the URL that will be created at the bottom there. Also note the security message at the top of the window there - the URL is never again shown anywhere in the portal and can't be retrieved again from here (again, for security purposes) so it's important to copy/paste the URL somewhere safe at this point so you don't lose it before you click the OK button to save the new webhook.

Build a new applet in IFTTT

Now things are set up on the Azure side of things, we need to look at how we can create an applet in IFTTT. To start sign in and go to the "my applets" screen and select "new applet". Next we click the "this" link and then need to search for the "do button" trigger, this allows us to tell IFTTT that our applet will be triggered whenever we press the specific "do" button in the mobile app on either an iOS or Android device that I've signed in to. It's worth noting that there are dozens and dozens of other ways to trigger things in IFTTT, the do button is the one that suits the specific type of function I need this time around, but you should also consider exploring some of their other recipes for applets and get a feel for other ways it can be triggered as well. Select "button press" as the trigger and then we can select the "that" link and search for a task called "maker". Maker is designed to allow applets to be triggered by web requests, or to send our web requests in response to a trigger (which is exactly what we want this time around). Once we are at the maker configuration screen select "make a web request" and then we can craft the type of request we want to send. We start by pasting the URL in we created earlier for our webhook and then setting the method to "POST". Now in my example runbook for this scenario there is no need to craft a body as I don't have any parameters to pass to it, however if you adapt this scenario and need to pass parameters to a runbook, go and have a read of the Azure Automation Webhooks documentation to get a feel for how that should be structured and how to use the variables in your runbooks. Click create action and after this you'll be all set!

Triggering the applet

I have an android device so these steps will vary a little for someone on iOS, but basically once you install the "do button" app on iOS, or the IFTTT app on android you can then trigger the do button. In my case I add a widget to the homescreen of my android that I can now simply press the button on, and this will trigger my action! You can tell if it's being triggered in a couple of places. Firstly if you head to the IFTTT activity screen you should see where the action was triggered and if you allow GPS access to the IFTTT app it'll show you where it was triggered from, in this case you can see I ran it from the Microsoft office in Canberra. You can also go back to the runbook in the Azure portal and see that the run was completed by going in to the "jobs" section of the runbook. And that's it! Now when I remember that I haven't shut any of my VMs down it's a simple matter of unlocking my phone and pressing a single button - super straightforward to do and it leverages my existing runbook to do it! Now you can take this basic example and look at all the other ways you might want to trigger runbooks in Azure Automation using webhooks and extend it to better support your use of the cloud - Enjoy!

xSharePoint is now SharePointDsc - what you need to know!

Brian Farnhill — Wed, 08 Jun 2016 08:58:02 GMT

For just over 12 months now we have been working hard to grow the xSharePoint DSC module to let SharePoint 2013 and 2016 administrators use PowerShell Desired State Configuration to manage their SharePoint deployments. We've come a long way in the last year, and now with the help of my core team we are making an important transition - we are renaming from "xSharePoint" to "SharePointDsc". This is important for a number of reasons for this - the most important of which is removing the "x" element. If you have ever had a read of the home page on GitHub for xSharePoint (and other "x" resources as well) we describe this as being a flag that the resource is "experimental". This was something that made sense when we first created the resources were first built - we needed to test and refine them, collect feedback from sources both internal and external to Microsoft, and add more functionality to make the module something much more than just an experiment. Now the time has come to move forward with a new name that indicates the "Production ready" state of our resources, and that is the main driver behind the change. There is an open RFC from the PowerShell team that touches on some of these issues in terms of how we approach versioning going forward with the PowerShell modules that is also worth a read for more information on what is happening in this space.

What specifically is changing in SharePointDsc

The items in the module that are changing moving forward are:

The name will change from xSharePoint to SharePointDSC. This will mean that xSharePoint will no longer have new functionality published to the PowerShell gallery, version 0.12 will be the last version available under the old name [see note below on hotfixes]
All SharePoint DSC resource names will be renamed to begin with just "SP" instead of "xSP". For example, xSPCreateFarm will become SPCreateFarm. This means updating your configurations to rename the resource types to the new name format. The parameters for each resource remain the same (with the exception of changes to schemas that were made after the 0.12 release - see the release notes for a list of changes in 1.0 to understand these changes)
Other internal name changes will take place to ensure that all internal function names go from [verb]-xSharePoint[noun] to [verb]-SPDSC[noun]. These are not designed to be called directly though, but in the event that you have written scripts that do use these, you will need to use the new function names

Hotfixes for xSharePoint

As version 0.12 of xSharePoint is the last version that will be published with that name, we wanted to ensure that we had an approach that would mean we could provide support and hotfixes to customers who are using xSharePoint currently who are unable (for whatever reason) to move to SharePointDsc. For that reason, a separate branch will be maintained with the code from the 0.12 release that we will be able to push specific hotfixes to in the event that a customer requires it. These will be published at increments to 0.12 (so from 0.12.1.0 to 0.12.2.0, 0.12.3.0 and so on). No new functionality will be added to this branch, SharePointDSC will be the module that receives all the new development effort - so customers should begin planning now for how to transition to the new module.

The release strategy for SharePointDsc

The next steps forward on how SharePointDsc is released are pretty simple. The next release (which is already available on the PowerShell gallery) will be numbered 1.0. Moving forward we will be doing releases every month and will be following the final version number strategy that is decided upon when the RFC from the PowerShell team is closed and formalised. Releases will usually be done at the start of the month, with the next scheduled release to be 1.1 in early July.

How to prepare for the module rename to SharePointDsc

There are a number of steps to be taken when the updated module becomes available. The below list is a high level walkthrough of the primary considerations.

Distribution of the module

Firstly you need to consider how you will deploy the module to your servers. The good news here is that because the names of all of the DSC resources and cmdlets have been changed, there is no reason that you can't have xSharePoint and SharePointDsc on the same server as you transition. So the usual options for deploying these modules are available - such as deploying through PowerShellGet, adding them to a pull server (or Azure Automation if you are using it as your pull server), or through manually deploying the module to nodes you are pushing configurations to.

Updating configurations

Once you have the module available you can begin to update your configurations to use the new resource names. This will firstly mean changing the "Import-DscResource" cmdlet at the top of your config to use the "SharePointDsc" module and not "xSharePoint". After this begin to change the names of each resource from the module to remove the x off the front (so as described above, "xSPCreateFarm" becomes "SPCreateFarm").

Republish your new configurations

Once you have updated the configurations you can republish them to your existing SharePoint servers. The new resources behave exactly the same as the old resources, so this should not trigger any changes as the same test and set methods will be used - its just the names that have changed. So a configuration element that was in a compliant state before the change will continue to be compliant with the new name.

The future of SharePointDsc

We aren't finished with SharePointDsc yet, not by a long shot. We keep our backlog of features, fixes and enhancements on GitHub - here you can see what we are working on, expected timelines for releases and you can even raise new issues for us to make any changes to the module here as well. We will be continuing to release updates with changes once a month and we will be constantly listening to feedback from the wider community. So raise an issue on GitHub, or post a comment here, and go out and do great things with SharePointDsc!

Consuming preview builds of xSharePoint through PowerShellGet

Brian Farnhill — Mon, 18 Apr 2016 13:59:39 GMT

PowerShellGet is a new module that is installed as part of PowerShell 5 (in Windows Management Framework 5.0) which allows you to easily connect to remote repositories to install PowerShell modules from. When you install WMF5 you'll get a repository configured to point to the PowerShell Gallery, where you can download the release versions of all of the PowerShell teams DSC resources. However if you want to use the preview (in development but not yet released) builds, you have the option to connect to a secondary repository where the dev builds are created and install those directly to your machine.

Where are the dev builds for xSharePoint?

All of the DSC resources that are published by the PowerShell team on GitHub make use of AppVeyor to do the automated testing and build of the modules. For example, you can see the latest artifacts that have been built at https://ci.appveyor.com/project/PowerShell/xsharepoint/build/artifacts. AppVeyor can also publish these as a Nuget feed, which has been configured for xSharePoint, with the feed URL being https://ci.appveyor.com/nuget/xsharepoint.

Adding a new repository to your local machine

To consume the preview builds we need to first connect the local machine with WMF5 installed on it to our remote repository. That can easily be done through using the Register-PSRepository cmdlet. Once the repository has been added you can easily request a list of the versions that are available there using the Find-Module cmdlet. Here you can see I've requested all the available versions, but only want it to show the latest 10 versions it has found (keeping in mind that the preview branch here has many versions in it, so looking at the full list may be 100 or so, potentially more, versions). The specific command that is being used here to register the repository is:

Register-PSRepository -Name xSharePointDev -SourceLocation https://ci.appveyor.com/nuget/xsharepoint

The repository name can be whatever you like, you use this to uniquely identify the source. The URL though is the Nuget feed URL we mentioned earlier.

Installing from the preview build feed

Installing a specific version from the preview feed is very straightforward. After using the Find-Module cmdlet you can pipe a specific version to Install-Module to tell PowerShell to download and install that version. Below you can see the installation, and then I verify the version that is installed with Get-Module.

Updating to a newer version

After you have installed a specific version, you can install a new version in exactly the same way as when you installed the previous version. If you don't specify a version it will automatically get the latest build available. Here you can see the upgrade taking place, noting that if you do not use the "-Force" switch on the install cmdlet you will be presented an error. Once you do this you will now have two versions installed, the latest version as well as the previously installed version. That's all there is to it! Now the same processes can be used if you want to stick to the released versions instead of the developer builds, you just don't need to connect to the custom repository as the PowerShell gallery has these builds and that is automatically configured. But if you want the latest and greatest which may come with a few bugs from time to time, then you can use this to get these builds just as easily. As always, for more information about xSharePoint or to raise issues or changes with it head over to the xSharePoint repository on GitHub.

Configuring SQL Server AlwaysOn Availability Groups in Azure RM Virtual Machines

Brian Farnhill — Thu, 03 Mar 2016 02:48:52 GMT

This week on a project I came up against the need to set up some AlwaysOn Availability Groups (AG's) for SQL Server 2014 in an Azure IaaS environment, using v2 (or Resource Manager/ARM) based VMs as opposed to the v1 (or Service Manager/ASM) based ones. I came across varying bits of documentation to do with this, but it either didn't have the ARM PowerShell cmdlets or it was a mix and match of scripts and UI actions which didn't help me scripting the deployment, so after working through this, there are a few things that I learned.

The challenges

For the most part, the process of actually setting up the availability groups within the VMs was more or less the same as doing it on-premises so I wont go in to that. The issue I came across was that after I have provisioned my AGs and created listeners for them I found that I couldn't open SQL connections to the servers through the listener, but I could if I opened connections directly to each server. Name resolution was working fine and I could see that the DNS was in place to resolve to the listeners IP address, but the host was unreachable. After a bit of digging it turns out that to use AGs in Azure IaaS you need to put an internal load balancer in front of them, which will create an IP address on the virtual network which will allow for the Azure virtual network to know which VM to route traffic to correctly (more or less, I'm a little sketchy on the inner workings of the networking in Azure - but this is documented as the solution to AAGs in Azure).

Creating the internal load balancer

For the purposes of keeping this post brief and focussed on the ILB setup, lets assume that you already have your two (or more) SQL servers provisioned and you have configured the availability groups the same as you would on-prem. Below is the script that I used to create the load balancer.

$ResourceGroupName = "My-ResourceGroup"
 $NetworkName = "VirtualNetwork01"
 $SubnetName = "Subnet1"
 $LoadBalancerName = "My-New-Loadbalancer"
 $FrontEndIpName = "My-New-Loadbalancer-FrontEnd"
 $FrontEndLocalIpAddress = "192.168.0.70"
 $BackEndPoolName = "My-New-LoadBalancer-Backend"
 
 $VirtualMachines = @("SQL-01", "SQL-02")
 
 
 $network = Get-AzureRmVirtualNetwork -Name $NetworkName -ResourceGroupName $ResourceGroupName
 $subnet = $network.Subnets | Where-Object { $_.Name -eq $SubnetName } | Select -First 1
 
 # Create the front end IP address for the load balancer
 $frontendIP = New-AzureRmLoadBalancerFrontendIpConfig -Name $FrontEndIpName -PrivateIpAddress $FrontEndLocalIpAddress -SubnetId $subnet.Id
 
 # Create the backend pool
 $beAddressPool = New-AzureRmLoadBalancerBackendAddressPoolConfig -Name $BackEndPoolName
 
 # Health probe
 $healthProbe = New-AzureRmLoadBalancerProbeConfig -Name "HealthProbe" -Protocol Tcp -Port 59999 -IntervalInSeconds 15 -ProbeCount 2
 
 # Load balancing rule config
 $lbrule = New-AzureRmLoadBalancerRuleConfig -Name "SQL" -FrontendIpConfiguration $frontendIP -BackendAddressPool $beAddressPool -Probe $healthProbe -Protocol Tcp -FrontendPort 1433 -BackendPort 1433 -EnableFloatingIP
 
 # Create the load balancer
 $NRPLB = New-AzureRmLoadBalancer -ResourceGroupName $ResourceGroupName -Name $LoadBalancerName -Location $network.Location -FrontendIpConfiguration $frontendIP -BackendAddressPool $beAddressPool -LoadBalancingRule $lbrule -Probe $healthProbe
 
 
 #Reload to get the IDs of what was created
 $beAddressPool = Get-AzureRmLoadBalancerBackendAddressPoolConfig -name $BackEndPoolName -LoadBalancer $NRPLB
 
 # For each VM add the back end pool to the IP configurations
 foreach($vmName in $VirtualMachines) {
 $vm = Get-AzureRmVm -ResourceGroupName $ResourceGroupName -Name $vmName
 $nicName = ($vm.NetworkInterfaceIDs[0].Split('/') | Select -Last 1)
 $nic = Get-AzureRmNetworkInterface -Name $nicName -ResourceGroupName $ResourceGroupName
 $nic.IpConfigurations[0].LoadBalancerBackendAddressPools = $beAddressPool
 Set-AzureRmNetworkInterface -NetworkInterface $nic
 
 Restart-AzureRmVM -Name $vmName -ResourceGroupName $ResourceGroupName
 }

The basic flow of this script is to do the following:

Create a front end IP address for the load balancer. This should be the same IP address that you use for your listener (this makes the assumption that you are working on a single subnet, I'll get to multi-subnet in a bit)
Creates a "pool" to put the servers in that the load balancer will refer to. This should be every server in the availability group that shares the same subnet as the above IP address
Creates a probe to check what VMs are currently responding, so that the network can direct traffic appropriately
Defines a load balancer rule which specifies the ports to handle traffic on
Takes all of the above objects and then creates the load balancer (nothing actually gets created in your tenant up to this point)
For each of the specified VMs, it gets their first network adaptor and puts it in the backend pool that was created earlier
Restart each VM so that the new config can apply

There is one thing that I want to highlight from the above script - the "EnableFloatingIP" switch on the New-AzureRmLoadBalancerRuleConfig cmdlet. Without this turned on for your rule you'll find that all traffic hitting your availability group will just time out. By enabling floating IPs and letting Azure move the IP address around based on it detecting that servers are down you'll see that traffic begins to actually flow correctly. Next we need to make a couple of changes to the Windows Failover Cluster so that it plays nice with the load balancer that we just created. Here is the script that you should run on the active node in your cluster:

 Import-Module FailoverClusters
 Get-ClusterResource "IPAddressResource" | Set-ClusterParameter -Name overrideaddressmatch -Value 1
 Get-ClusterResource "IPAddressResource" | Set-ClusterParameter -Name probeport -Value 59999
 Get-ClusterResource "IPAddressResource" | Set-ClusterParameter -Name SubnetMask -Value 255.255.255.255

Just swap in the name of the IP address resource in your cluster here and you're good to go (look it up using Get-ClusterResource with no parameters to see a full list of the resources in your cluster). The thing that threw me a little here was the subnet mask - the subnet for my lab in this case was 255.255.255.224, so I originally tested with that in there, but I wasn't able to fail over as all the traffic was still being routed to the old primary. This is because the ILB created earlier was not able to poll correctly. Once this subnet mask was switched over I was able to see successful failover take place with the ILB routing traffic to the new primary within 15 seconds of me triggering the manual failover in SQL. So once you've got this sorted out you are ready to go. Failing over the AG works just the same as it always did, and your traffic should flow to the new primary from there.

Multi-subnet considerations

Now everything I have done so far is all well and good for running your AG on the one subnet, but what happens when there are nodes in your cluster that are in a separate subnet? The whole plan goes a little bit south because the internal load balancers in Azure are basically tied to a single subnet by the front end IP and in a failover cluster for SQL that uses multiple subnets your cluster will usually have at least two IP address resources, one for each subnet, and the appropriate address resource gets brought online as the AG fail over the cluster to a node on the other subnet. This means that for this scenario, you need to create an extra internal load balancer for each subnet (in the lab I had set up I was using 4 SQL servers, 2 in subnet A and 2 in subnet B). Each ILB I created had a front end address that was for the subnet I created it in, and referred to only the VMs in that subnet. With the additional ILBs in place, I was able to start failing SQL over to the second subnet and see things come together the way I needed.

So there you have it - hopefully that will help you get going with AGs in Azure with Resource Manager cmdlets!

Retrieving the URL of an app catalog site in SharePoint 2013

Brian Farnhill — Mon, 21 Dec 2015 21:25:00 GMT

In some of my recent work with the xSharePoint resources we came up with a need to retrieve the current URL of an app catalog so that we could determine if the current settings were correct or not. The issue with this is that we found there is no out of the box cmdlet to retrieve the current app catalog URL for a specific web application, only to update the settings with Update-SPAppCatalogConfiguration. To facilitate getting the current URL we had to do a bit of digging to find where it was stored after this point, and as it turned out this was found in the properties of the app feature which is turned on within the web application object. In order to retrieve the current URL we wrote the following little script to get it:

 $WebAppUrl = "https://sharepoint1:1234"
 
 $wa = Get-SPWebApplication $WebAppUrl
 $feature = $wa.Features[[Guid]::Parse("f8bea737-255e-4758-ab82-e34bb46f5828")]
 $site = Get-SPSite $feature.Properties["__AppCatSiteId"].Value
 
 return $site.Url

There are two things to notice here:

The GUID we use here is a constant, it's the ID of the feature that is responsible for flagging the app catalogs presence in a web application
The property that stores the GUID of the site collection is called "__AppCatSiteId"

This allows us to retrieve the site collection and get the URL that is currently used. Remember if you want to update this that you should use the Update-SPAppCatalogConfiguration cmdlet I mentioned before as manually manipulating this feature and its properties will get you in an unsupported state pretty quickly - but you can interrogate the values that SharePoint puts here to find the current app catalog URL if you need to read it for something you are working on.