MatchPoint Powershell Essentials

Date: 22. Mar 2017

One of the most common tasks when installing and setting up SharePoint and MatchPoint, are one-time efforts for migrating content and/or configs. This is where Powershell scripts shine.

In this blog post, we show some of the basic MatchPoint Powershell tricks. The script examples will work on both SP2013 and SP2016 using the current MatchPoint versions. We will not cover basic SharePoint Powershell functionalities (e.g. for bulk-importing lists, creating site collections, etc.), since this is already well covered elsewhere.

Instantiating the MatchPoint Instance Scope in Powershell

To use MatchPoint objects and functions in Powershell, a MatchPoint specific instance scope must first be created. The following three lines will enhance your Powershell session with MatchPoint powers:

$web = Get-SPWeb -Identity $url
$mpInstance = New-Object -TypeName Colygon.MatchPoint.Core.MPInstance $web
$mpInstanceScope = New-Object -TypeName Colygon.MatchPoint.Core.MPInstanceScope $mpInstance

Using a standard SharePoint SPWeb object (Get-SPWeb), we first create an MPInstance object. We then need to create an instance scope by creating an MPInstanceScope object.

For the sake of code clarity, we did neither dispose the MPInstanceScope or SPWeb objects in the above sample. Disposing SharePoint objects in Powershell is an entire topic on its own and quite well explained here.

Basic example

The following - fully functional script - shows a basic usage by simply echoing the admin site in your PowerShell window.

param (
[Parameter(Mandatory = $true, HelpMessage = "The absolute URL is required.")][ValidateNotNullOrEmpty()][string]$TargetInstanceUrl
)

Add-PSSnapin Microsoft.Sharepoint.Powershell

# Start MatchPoint Scope Init
$web = Get-SPWeb -Identity $TargetInstanceUrl
$mpInstance = New-Object -TypeName Colygon.MatchPoint.Core.MPInstance $web
$mpInstanceScope = New-Object -TypeName Colygon.MatchPoint.Core.MPInstanceScope $mpInstance
# End MatchPoint Scope Init

# Example using the $mpInstance object
$mpInstance.GetAdminSite($true)

$mpInstance.Dispose()

Noteworthy: To see the definition of the $true parameter in the GetAdminSite method, simply omit the parantheses after the method name: This shows us not only the type expected, but also hints its purpose. In this example, whether the GetAdminSite method should run in elevated (privileged) context or not.

From the MatchPoint expression console to Powershell:

To follow this example, we assume that you still have your Powershell console open from the previous example, so that your MatchPoint Instance Scope is ready and available.

Here, we explain how to use a familiar MatchPoint expression console statement from Powershell:

To use the above expression in powershell, simply reference the assembly by using the full namespace and method name. The example below matches the expression from the above screenshot:

# Using an expression console statement in Powershell
[Colygon.MatchPoint.Core.MPUtility]::GetMatchPointVersion()

This will return the same version number as in the Expression console:

Noteworthy: The full assembly name for the MPUtility class can be seen in the MatchPoint expression console

Caveats: There is no HTTP context in Powershell (or: there is no easy way to fake the HTTP context). Therefore, expression console statements using "Self", "DataItem" and the like need some rework and tweaks before they can be used in Powershell.

Retrieving data from MatchPoint configuration files

Again, we assume that you have your MatchPoint Instance Scope ready and available from the above examples. If not, then add the three lines necessary to get the MatchPoint Instance Scope (clue: all you need are the three lines of code in the first code window of this post).

Another real world example might be the requirement to extract data from MatchPoint configuration files into a JSON file (for whatever reason ;)). You could go the "old" way, using the "Toggle" view in the MatchPoint configuration console to extract the XML structure into your favourite editor - then jump through hoops to search and replace the XML structure until it has a JSON structure.

Or you might just use two lines of Powershell code:

# Generating JSON output from all the icon mappings in the MatchPoint configuration file
$configFile = [Colygon.MatchPoint.Core.Administration.ConfigurationFile]::OpenElevated("MatchPointConfiguration#MatchPointConfiguration.xml", $mpInstance)
$configFile.Configuration.IconMappings | ConvertTo-Json

The above example will extract all icon entries from the MatchPoint configuration to a JSON structure, which will result in something like this:

Writing a MatchPoint configuration file from Powershell

Please make sure you have your MatchPoint Instance Scope ready and available. By reading through this post, you should know by now which three lines of code achieve this.

In this example, we will create a new MatchPoint StringResourceConfiguration file named "HelloWorld.xml" from Powershell.

The OpenElevated method below will create a file, if it does not already exist. The two arguments of that method are "[MatchPointConfigurationType]#[FileName]" and MPInstance object.

# Creating a new StringResourcesConfiguration file from Powershell
$newConfig = [Colygon.MatchPoint.Core.Administration.ConfigurationFile]::OpenElevated("StringResourcesConfiguration#HelloWorld.xml", $mpInstance) 
$newConfig.Configuration.Name = "My first Powershell-generated configuration file"
$newConfig.Update()

Noteworthy: All the mandatory properties and fields of a configuration file must be provided or the Update will silently fail.

Please open your MatchPoint configuration editor in the web browser. You now should see a new configuration file of type StringResourcesConfiguration named "HelloWorld.xml".

To update the Name field in this newly created configuration file, we essentially use the same code (but with a changed Name string):

# Updating an existing MatchPoint configuration file from Powershell
$existingConfig = [Colygon.MatchPoint.Core.Administration.ConfigurationFile]::OpenElevated("StringResourcesConfiguration#HelloWorld.xml", $mpInstance) 
$existingConfig.Configuration.Name = "A more meaningful name"
$existingConfig.Update()

After the completion of the update, the result should look as follows:

Important Notes:

• Make sure that your Powershell session has sufficient rights. This is one of the most common problems you might run into.
• Test your scripts on a dev system before production. Powershell makes it very, very easy to destroy or corrupt an entire working SharePoint farm in milliseconds.