[O365] Provisioning: spmeta2 vs O365 PnP provisioning

Technical / May 6, 2015 / Jasper Siegmund / 2

These days, provisioning is quite a hot topic in the land of Office 365 and SharePoint. So let’s start with a simple question: what exactly is provisioning? I don’t have a clean cut definition for you, but my personal view would be something like: “Provisioning for SharePoint is the process of deploying solution components in an intelligent way.”. What I mean by intelligent is: things are not just placed and/or overwritten, but logic ensures everything is in place, linked, updated, etc. 

When it comes to Office 365, provisioning – in my opinion – is the only viable way of getting a solution deployed on the platform. Whether it’s in the form of an app, a script or more advanced solution that I’ll discuss below, it’s all provisioning of some sort.

Why provision?

So now that we’re clear on what provisioning is, let’s talk briefly about why you need it. SharePoint is very powerful in offering capabilities to create solutions on the fly. A customized list with just the fields your user needs to administer some process can be regarded as a solution. Any user can click that together, live in their production environment. Which is very nice, but comes with challenges too. The most important ones are supportability and maintainability. Users expect their IT departments to care about everything that’s IT, which in their view is also what they made themselves within SharePoint. And every SharePoint support person will know some cases where they had to trouble shoot clicked-together solutions which were… let’s say… not that well designed? And suddenly these solutions become problematic.

In order to solve this, software development usually goes through several stages (development, quality assurance, production and maybe more). To get your solution through these, you need a way to move everything from one platform to another. And that’s where provisioning comes in. By provisioning your application, you’re able to “install” the solution in any target environment. And if you do it well, you can also provision updates to your solutions, bringing in new functionality or bug fixes.

To provision things within Office 365, you have several options:

• CSOM code
• JSOM code
• Sandboxed solutions (deprecated, stay away)
• Frameworks

Apart from the sandboxed solutions, all of these methods use the client side API’s (webservices) to provision things. CSOM and JSOM are built on top of the API’s and the frameworks in turn are built on CSOM and/or JSOM.

The rest of this post will focus on two frameworks: SPMeta2 and the Patterns and Practices provisioning.

SPMeta2

I’ve been using this framework for a couple of months now in several projects. I won’t do a full description of what it is and how it works as they now have a documentation site with some good info on that. What you should know is this: the framework (open source) provides a code based, fluent way of describing artifacts and models. These models can then be deployed to any SharePoint site (2010, 2013 and Office 365), using either CSOM or SSOM.

A simple example of such a model:

public void DeploySimpleWebs()
{
    var model = SPMeta2Model.NewWebModel(web =>
    {
        web.AddWeb(DocWebs.News);
        web.AddWeb(DocWebs.AboutOurCompany);
    });
 
    DeployModel(model);
}

The above model would deploy two subwebs based on the News and AboutOurCompany web definitions.

Such a model is hierarchical, which provides a cool way of modelling fields, content types, fields used in content types and content types used in lists. The thing I like best about this approach is that the definitions that you create are POCO (plain old C# objects). These are objects that you can use in other parts of your code as well. For example:

 public static FieldDefinition CustomTextField = new FieldDefinition
 {
    Title = "Custom Text Field",
    Group = "Custom Fields",
    InternalName = "CustomTextField",
    Id = new Guid("F4A44795-EABF-4E4A-9343-44D47157FEA2"),
    FieldType = BuiltInFieldTypes.Text,
    Required = true
 };

Suppose you have code which generates items, or queries items using this field. Now you can get the internal name or ID from this definition object, without the need to store it in a new string variable which you would need to do when you’re using an XML or similar way of provisioning. This ensures there’s a single point of truth and prevents a lot of easily made mistakes when updating parts of your solution. Referencing the above object will support refactoring to ensure your entire solution is updated. Very cool!

Patterns and Practices provisioning

This is the new kid on the block, released April 2015 and made by the guys behind the Office 365 patterns and practices library. For those who do not know this library, it’s a set of helper methods and extensions to the client side libraries which simplifies certain commonly used API calls.

The provisioning framework can be regarded as a subset of these extensions. To deploy complete models, it uses a somewhat more familiar way of provisioning when you’re used to old-fashioned style provisioning in SharePoint: XML files. This XML model is basically a serialization of the creation information objects you would pass to these extension methods. So you create an XML model and use the code to apply that model to a site. In that regard, the two frameworks work in a similar way, using the CSOM code to provision a model. Here’s an example of old fashioned XML vs the PnP model:

<Field ID="{7B2B1712-A73D-4ad7-A9D0-662F0291713D}" Name="HealthRuleCheckEnabled" 
  Type="Boolean" Group="_Hidden" AllowDeletion="FALSE" DisplayName="Aktiverad"  
  SourceID="http://schemas.microsoft.com/sharepoint/v3/fields" 
  StaticName="HealthRuleCheckEnabled"  />

<p:Fields>
  <Field 
    xmlns="http://github.com/OfficeDev/PnP-Provisioning-Schema/0.5"
    ID="{7B2B1712-A73D-4ad7-A9D0-662F0291713D}" Name="HealthRuleCheckEnabled" 
    Type="Boolean" Group="_Hidden" AllowDeletion="FALSE" DisplayName="Aktiverad"  
    SourceID="http://schemas.microsoft.com/sharepoint/v3/fields" 
    StaticName="HealthRuleCheckEnabled"
    ProvisioningAction="Provision" />
</p:Fields>

The cool thing about this framework, is that it’s capable of generating a model based on an existing site. That means that you’re able to create your solution by clicking things together in SharePoint, extract the model and then apply that same model a different site. The code to do this is very  simple:

using (ClientContext clientContext = ConnectionHelper.GetClientContext(url, username, password))
{
    var web = clientContext.Web;
  
    ProvisioningTemplate template = web.GetProvisioningTemplate();
    XMLFileSystemTemplateProvider provider = new XMLFileSystemTemplateProvider("C:\\temp\\", "");
    string templatename = "template.xml";
    provider.SaveAs(template, templatename);

    ProvisioningTemplate loadedTemplate = provider.GetTemplate(templatename);
    web.ApplyProvisioningTemplate(loadedTemplate);
}

That’s pretty powerful, it saves you a lot of coding and you can have functional guys creating a solution without having to go into Visual Studio.

SPMeta2 vs PnP Provisioning

You’ve had an overview of provisioning methods, I showed some examples and we talked about the two frameworks which in my opinion are best suitable for the job. But which one to choose? Well, there are some pro’s and con’s.

• SPMeta2 is, at the moment of writing, more complete in terms of stuff it can deploy. The PnP framework has been released April 2015, so those guys are still including more and more API’s to fit into their models.
• PnP is the only one that does template generation, which is a very powerful feature. I can only imagine it won’t take long for the first apps to arrive in the store which include this functionality allowing you to copy structures from one site another.
• SPMeta2 uses a fluent code model to describe the objects to be provisioned and their relations. In PnP this model would be the above mentioned XML file. From a developer point of view, I like the fluent code approach better because you can reuse stuff easily within the model or in other parts of your solution. An XML model does not provide the same re-usability at design time.
• SPMeta2 has the ability to easily switch from CSOM to SSOM (server side object model) without having to redo any of your definitions or models. Even in an existing project, switching is a matter of changing a single line of code. Good in terms of dependencies, especially for those who have not yet switched everything to CSOM (which is perfectly fine in my opinion).
• Both are open source. SPMeta2 is made and supported by SubPointSolutions, a company. Not necessarily a bad thing but companies come and go and that might be a risk. Same can be said about PnP though, since that’s basically coming from Microsoft although there is some community effort involved too as Paolo justly noted in the comments.
• I’m not familiar with the support of the PnP team. I can only say that the SPMeta2 guys have been very helpful and quick in fixing things. Some bug fixes were available in a NuGet beta build in a matter of hours, which is awesome. Update: Eric noted that the support of the PnP group is pretty good as well, thanks Eric.
• The SPMeta2 framework allows updating, to some extent. It will try to match your site with your model, even if certain things have already been deployed. So for instance changing the name of a field works. It will locate the existing field and update it. I deliberately said ‘to some extent’ because there are limitations to what you can and cannot update, mainly due to the fact that the API’s don’t allow you to update everything. But then again, it wouldn’t be considered good practice to change a TaxonomyField to being a NumberField overnight 😉
• John reported in the comments below that for him, SPMeta2 is the faster framework. I haven’t tested nor validated this. But if performance is of importance to you, you’d might want to check.

So both have their shortcomings and strengths. Which one you use is up to you, I would be grateful if you’d leave a comment letting us know your choice and why you picked that one. Me personally, I’m sticking with spmeta for the moment. The fluent code model being the main reason (and I’ve got some existing projects using it, obviously). Also, the templates made by the PnP code contain everything in your SharePoint site. It’s like the functionality we had in Visual Studio before where you ended up manually stripping a bunch of stuff that you really didn’t want in there. Might not apply here, but I don’t have good experiences with that.

Either way, it’s good to see that provisioning via CSOM has matured a lot and now almost supports everything we could do on-premises. This makes it easier to build and support SharePoint solutions for Office 365, which is beneficial to the end users as well. So IT departments out there: start deploying your solutions in an organized way today!

Update 08-05-2015: I’ve updated the post to reflect the comments below by Eric and Paolo. Thanks for the information guys!

Update 04-06-2015: Added two more pro’s thanks to John Liu’s comment.

#o365dev, in, spmeta2

Jasper Siegmund