Building your own extension for SPSD

SharePoint Solution Deployer (SPSD) has grown to a quite big script and even though it supported custom targets/events from the beginning, it was fairly difficult to update SPSD and also re-use your custom PowerShell commands without intensive testing.

The new extension system introduced with the recently released SPSD5 solves these problems.

What is an extension?

Basically everything that SPSD does not out of the box during the deployment process.

An extension could be for example:

  • a simple script to change some farm settings
  • creating webapplications or site structures
  • activate features
  • set permissions
  • create/import demo content
  • create service applications
  • configure the farm
  • import managed metadata
  • etc….

Extensions can be registered with different functions for multiple events i.e. Initialize, BeforeDeploy, AfterRetract etc.

Following extensions are already work in progress and will be released in the next couple of weeks:

  • SiteStructure: Create Site Collections (optional with custom ContentDB), subsites, assign permissions
  • ContentTypeHub: Create/Remove and configure ContentTypeHub
  • ManagedMetadata: Backup and Restore Managed Metadata Termsets and MMS configuration, including custom properties and multilingual lables/descriptions
  • LoggingConfiguration: Creates/Removes logging areas and categories based on SP Guidance logging
  • several more simple extensions like “SetMaximumFileSize”, “SetBlockedFileExtensions” etc.

So stay tuned :)

The big advantage about the extensions is that they can be updated independently of SPSD.

Additionally this allows you  to re-use the extension in several projects.

I plan to add the extensions to the Technet galleries with the tag “SPSD” so that people can vote and comment on them. If you like to publish your own extension then it would be great if you do the same to make them easy findable.

You are also welcome to modify and re-publish extensions if you have improved them or found a better approach.

How to create an extension?

Extensions are very easy to create.

They consist of

  • extension folder in the Scripts/Extensions folder which
    • must have a manifest.xml file, letting SPSD know that the extension exists
    • a .ps1 file with your custom PowerShell commands (see Example.ps1)
  • extension configuration file in the SPSD/Environments folder
    or a section in an existing environment file (see Environments/Example.xml) which tells SPSD which custom PS function it should run during which deployment step.

Manifest

The manifest file is stored in the folder /Scripts/Extensions/<extensionname>  and defines

  • the extension type (a unique type to identify the extensions),
  • the version
  • the associated script file and
  • if the extension is currently enabled or disabled

By specifying the manifest, SPSD can automatically pick up your extension and register it for deployment actions.
The extension will be loaded inline, which means that functions and variables of the extension script are not available after the extension is done.

This means that your extension cannot harm the rest of the execution of SPSD, but also that you cannot (and should not) pass information from one extension to another.

Also all disposable objects allocated in the extensions script will be automatically disposed  by SPSD when the extension is finished.

Script

To implement an extension script you just create a .ps1 file in the /Scripts/Extensions/<extensionname> folder and define a function with following parameters

  • $parameters : a collection of all named parameters defined in the extension configuration file
  • $data : the <Data></Data> node of the extension configuration file (see next section)
  • $extId : the extension Id as defined in the extension configuration file (manifest.xml)
  • $extensionPath : the path to this file, in case you require to load from other files in the extensions script folder

This could look like the following

Note that this example is using the SPSD logging function. This assures that your extension output is not only printed out to the console but also is saved into the SPSD log file.

Environment Configuration

Although SPSD is now already picking up the extension and reading the manifest, you have to tell it on which deployment commands you like which function to be executed.

If you have used SPSD before, you know already about the environment files in the /Environments folder, which allow you to configure SPSD to your liking.

The following XML describes how an extension is configured.

You can register your PowerShell function(s) to one ore multiple events and SPSD will pass the parameters and your custom xml data to them.

Available events are:

  • BeforeDeploy : Execute before the deployment tasks are started
  • AfterDeploy : Execute after the deployment tasks have finished
  • BeforeRetract : Execute before the retraction tasks are started
  • AfterRetract : Execute after the retraction tasks have finished
  • BeforeUpdate  : Execute before the update tasks are started (only when running “Update-SPSolution”)
  • AfterUpdate : Execute after the update tasks have finished (only when running “Update-SPSolution”)
  • Initialize : Executed after SPSD has initialized
  • Preconditions : Executed after SPSD has checked all pre-conditions. You can break the whole deployment by throwing a exception if your custom condition is not met.
  • Finalize : Executed after SPSD is done
  • ProcessSolution : Executed on every action happening to a specific solution (runs on deploy, retract and update for each WSP)

Tip: SPSD Environments files have also the ability to load any XML node from a separate file. So in order to keep your environment configuration nice and clean (and maybe re-use the extensions configuration for different environments) you should put it into a separate file and reference it.
A reference would look like this

The complete example extension is included in the current release and can also be downloaded separately from CodePlex.

How to test your extensions?

SPSD now has an additional batch file which starts the main script with the

  • DeploymentType = “Extensions” and the
  • DeploymentCommand = “Ask”

This means that when executing this batch, SPSD runs, but skips the actual deployment of the WSPs to speed up the process.

The “Ask” command results in SPSD asking you which deployment command you want to perform (Deploy, Retract, Redeploy, Update) before the script runs.

Summary

The new SPSD extension system allows you to build and re-use your custom scripts and integrate them with no effort into SPSD.
Migrating existing scripts is very easy by just providing a caller function which meets the extension requirements.

If you have new ideas for extensions please don’t hesitate to leave a comment here or on CodePlex!

In future posts I will explain how the extension system is actually built and also show off the extensions I have already built.

Until then feel free to check out the source code yourself :)

  • Sola Noah

    How do i invoke the functions in my extension?

    • Matthias Einig

      In the environment xml file for your extension (third code snippet) you specify which function should be executed in for which event. e.g. Execute-ExampleExtension
      In this case “Execute-ExampleExtension” is the function in your extension .ps1 file.
      The available events are described in the sample extension provided with SPSD.