Category Archives: Random Whatnot

Task Runner Explorer is the Best Visual Studio Feature You Probably Aren’t Using

TL;DR – There is a handy feature in VS 2015 called Task Runner Explorer that you can use to run PowerShell or batch commands to do just about anything. You can also bind these to build events.

A task runner is a program that runs tasks. If you’ve been doing much web development these past couple of years you are probably familiar with this concept and popular task runners like Grunt and Gulp. In fact one or both of these might be essential to your development workflow. And, since many web developers consider these to be essential tools, the Visual Studio team released the Task Runner Explorer extension for Visual Studio 2013 and later made Task Runner Explorer an out of box feature in Visual Studio 2015.

If you aren’t aware that this feature exists, you aren’t alone! I took a poll on twitter.

<sarcasm>I was a bit surprised by this as the feature is prominently available by going to View | Other Windows | Task Runner Explorer.</sarcasm>

JavaScript Task Runner? No Thanks!

If your work isn’t mostly JavaScript, using a JavaScript based task runner probably sounds pretty unappealing. Happily there is an extension that supports .exe, .cmd, .bat, .ps1 and .psm1 files called Command Task Runner.

We use this in the Azure Functions for SharePoint project to automate deployment at build time by binding the script to the build event.

The deploy script is complicated, but there are a couple others that are pretty simple and are not bound to any events. We run them manually and I think they illustrate best why this tool is something that belongs in your everyday toolkit.

For example, each Azure Function for SharePoint relies on a config.json file. It would be an error-prone pain to create them by hand or by copying an existing configuration and so we have a script that creates a new config and puts it on the clipboard:

$scriptdir = $PSScriptRoot
[Reflection.Assembly]::LoadFrom("$scriptdir\AzureFunctionsForSharePoint.Core\bin\Debug\AzureFunctionsForSharePoint.Core.dll")
$config = New-Object AzureFunctionsForSharePoint.Core.ClientConfiguration

#Pretty print output to the PowerShell host window
ConvertTo-Json -InputObject $config -Depth 4

#Send to clipboard
ConvertTo-Json -InputObject $config -Depth 4 -Compress | clip
														

When a new client config.json is needed, all one must do is run the command from Task Runner Explorer.

Pretty cool eh?

–Doug Ware

Comparing InstantQuick SharePoint Provisioning and OfficeDev PnP

The purpose of this post is to help you understand when to use InstantQuick SharePoint Provisioning and when to use OfficeDev PnP-PowerShell by contrasting the two. At the outset I will admit I am biased as I created the former, but I also use the latter. And, not to put the conclusion before the comparison, I think both have a place in your toolbox. Each PowerShell module gets its functionality by wrapping a set of class libraries that you can use independently of the module in your own solutions, and so a comparison of the PowerShell modules is also a comparison of the class libraries they wrap which are also open source and located in GitHub.

Where InstantQuick SharePoint Provisioning Shines – Templated Provisioning

PnP and IQ each offers the ability to create provisioning templates by reading from an existing site and the ability to deploy the resulting templates to other SharePoint sites. PnP has a number of other very useful and granular features. At the time of this writing PnP offers 170! individual PowerShell commands. Most of these are not for creating provisioning templates or application of provisioning templates, but are instead for administration and manipulation of individual elements of a SharePoint tenant or site. Examples include such diverse commands Send-SPOMail, Enable-SPOFeature, and Get-SPOTimeZoneId. Most of the commands wrap types from the SharePoint Client Object Model which are extended by OfficeDevPnP.Core.dll.

I’ll talk about these PnP commands in general in the next section. In this section I’m comparing the primary PnP commands dedicated to templating and template provisioning. These are:

PnP has two different package formats and there are a few other commands in PnP for the management and conversion of the templates themselves that are outside the scope of this comparison as they don’t affect the actual provisioning functionality.

In contrast IQ has only 24 PowerShell commands, is considerably less granular, and is more or less focused on creating, installing, and uninstalling provisioning templates. IQ offers two types of templates: AppManifest and SiteDefinition. An AppManifest describes fields, content types, lists, etc. and a SiteDefinition defines a hierarchy of one or more Webs each with a corresponding AppManifest. To keep this comparison simple, I’ll focus on only the two commands that most closely match PnP:

For a more detailed look at the IQ commands in action see the samples on GitHub. For this comparison I am using the Board of Directors Site sample. If you’d like to play along at home, use IQ to create a site for this samples, use PnP to create a template from the sample site, and then apply the PnP template to another site for comparison – do not use the same site collections or the items will collide!

Get-SPOProvisioningTemplate Versus Get-WebCreator

Each of these commands creates a template by reading from a site that contains customizations. Get-SPOProvisioning determines what to include by comparing the site to an XML document embedded in the PnP stack whereas Get-WebCreator compares the site with the customizations with another site to produce a delta. Here at InstantQuick we prefer the latter because we don’t have to maintain a static template as Microsoft changes SharePoint between versions but primarily because we treat AppManifests as modules we combine to produce larger customizations. For example, our Practice Manger apps are composed of many different manifests, some of which are shared making customizations and maintenance much easier. To create a custom solution for a client we can install a base solution to a site, modify it, and extract the delta as a new package. To deploy it, we install the AppManifests in order so that the delta takes precedence over the original.

Big Difference #1 – Support for Pages with Web Parts

One side-effect of the PnP approach is that they have different installers for different versions of SharePoint. At present there are three, SP2013, SP2016, and SharePoint Online. This can be a pain if you work with more than one version of SharePoint. The core PnP solution uses build configurations and conditional compilation to deal with the differences between versions whereas IQ has one build configuration with conditional logic and heuristics to decide how to behave at runtime based on the server’s version.

If you are using a version of PnP compiled for a version where the Client Object Model doesn’t support a particular operation, for example reading a Web Part definition from a page in SharePoint 2013, PnP will simply skip those steps. Among IQ’s conditional logic is code that will fall back to older SOAP based API’s as necessary to read Web Parts and 2010 style workflows.

PnP therefore doesn’t support Web Part, Wiki, or Publishing Pages that contain Web Parts for anything but the newest versions of SharePoint and (as far as I can tell) doesn’t support SharePoint 2010 workflows at all.

Big Difference #2 – Site Specific Fixups

Both Get-SPOProvisioningTemplate and Get-WebCreator will include the source site’s home page in the template by default. The screen shots below are from sites created by IQ and PnP respectively. The PnP version was created from a template produced by using Get-SPOProvisioningTemplate against the IQ version and then applying the template to a web in a different site collection.

The second site’s home page looks pretty good, but unfortunately all of the URLs in the template point to the original site. This includes the navigation links, the image’s source URL, etc.

Get-WebCreator tokenizes a variety of things including URLs, list IDs, and group IDs in links, filed, web parts, and files. Install-IQAppManifest substitutes the correct values during provisioning and does things in the proper order when necessary. Both Get-SPOProvisioningTemplate and Apply-SPOProvisioningTemplate simply read the values and reproduce them on the target without modification.

Example one from IQ

Example two from PnP

 

Big Difference #3 – Creation of Complete Templates

If you are following along at home, there are a number of other differences you will quickly notice. Among them are the fact that the Board Events list has a workflow that is missing in the PnP site, that the Meeting Minutes library has a custom document template that is missing in the PnP version, and that several of the lists have custom view pages that are missing in the PnP version. To be fair, Get-WebCreator won’t include all of these files by default as part of the differencing process, but it will if you use the -Options switch to specify the lists and libraries with items you wish to include. You can also extend a created template using IQ commands such as Get-FileCreatorAndFolders and Get-ListCreatorListItems.

PnP has the ability to extend the provider with custom handlers for such situations, and the Office PnP samples repository has samples for just about anything you might want to do, but to get a complete template generally means you will have to understand PnP at a fairly deep level and be willing to write a bunch of code.

Where OfficeDev PnP-PowerShell Shines – Formal and AdHoc Admin Scripting

If you are responsible for a SharePoint environment and you use PowerShell, I have no reservations saying that you should be using OfficeDev PnP-PowerShell.

You need to add a file to 1000 sites? Add-SPOFile
You need to clean up some dodgy Custom Action that’s breaking a site? Remove-SPOCustomAction
You need to ….? I could go on all day because PnP has 170 really useful commands!

I could wax poetic all day about the good things in PnP, but it isn’t my project. J

–Doug Ware

 

 

The InstantQuick SharePoint Provisioning Engine is Now Open Source and on GitHub

The InstantQuick SharePoint Provisioning stack is the easiest to use and most complete SharePoint provisioning library currently available. It is the core engine used in the InstantQuick line of products and can read from and provision to SharePoint 2013, SharePoint 2016, and SharePoint Online.

This repository includes the .NET class libraries we use at InstantQuick and a companion PowerShell module.

Minimal Path to Awesome

  1. Download and Install the PowerShell Module – Setup
  2. Visit the wiki
  3. Pick one of the three samples and follow the instructions

About the Project

InstantQuick SharePoint Provisioning predates Office PnPCore by a couple of years and differs in that it is designed to be a complete and turnkey provisioning engine that is easy to use with minimal setup as opposed to being an extensible demonstration project of the SharePoint Client Object Model and CSOM development patterns. It offers more features out of the box for provisioning including the ability to read and provision Web Part Pages, Wiki Pages, Publishing Pages, and 2010 style workflows against versions of SharePoint that do not support the latest SharePoint Client Object Model API’s by falling back to older API’s as needed.

If it sounds like we are bashing the PnPCore stuff, we aren’t. This project even includes some of its (properly attributed) code! If you are looking for a great library to extend, it might well be a better choice. But we think this one is likely to satisfy most scenarios with less setup and without the need to extend the base functionality (or even understand how it uses the API’s).

As with the Microsoft Patterns and Practices library, InstantQuick SharePoint Provisioning can generate templates by comparing a customized site to a base site. Unlike the PnP engine you can easily include any file in the site (including publishing pages and page layouts) without writing code or otherwise extending the library. It also has the capabilty to provision site hierarchies and to both install and/or remove multiple template manifests as a single operation.

Features

InstantQuick SharePoint Provisioning can read and recreate the following out of the box

  • Webs and subwebs
  • Fields
  • Content Types
  • Lists and Libraries with or without custom views
  • List items
  • Documents
  • Folders
  • Web Part Pages
  • Wiki Pages
  • Publishing Pages
  • Master Pages
  • Page layouts
  • Display templates
  • Composed looks and themes
  • Other arbitrary file types with or without document properties
  • Feature activation and deactivation
  • Permission levels
  • Groups
  • Role assignments (item permissions)
  • Top and left navigation
  • Document templates
  • 2010 Workflows
  • Managed metadata fields and list item values
  • Site, Web, and List custom actions
  • AppWeb navigation surfaces
  • Remote Event Receivers
  • …and more

Six Things to Know About the Newly Announced SharePoint Framework

Today at The Future of SharePoint event in San Francisco Microsoft made several important announcements and released quite a bit of information. Without a doubt, the new SharePoint Framework was the biggest bombshell. As a longtime SharePoint MVP and founder of an ISV that sells SharePoint add-ins and tools, I was fortunate to be in Redmond early in the process and more recently to offer feedback. In fact, I and my associate, fellow MVP Dan Attis, actually got to spend a few days playing with the new bits at a recent Dev Kitchen in exchange for our feedback. Here are my top six big picture thoughts on the new stuff.

#1: You Are Not Screwed

One thing that was immediately noticeable in my recent interactions with the SharePoint team is that they are excited. They believe in this stuff and they want to share their new awesomeness with you. They think you’ll love it as they do! For many of us though, the most likely initial reaction is to be very disturbed. It’s the kind of feeling I imagine a homeowner gets when she receives the Notice of Eminent Domain for the road widening that will destroy her front yard.

So, the first thing you need to know is that the existing UI upon which your house stands on is not scheduled to be bulldozed. SharePoint 2016 is not shipping with the new experience. The features it does ship with reach the end of mainstream support in 2021 and extended support in 2026. Those dates represent the earliest possible end of support.

But what about SharePoint Online?

There as well, you can expect to be able to use the current experience for a long time to come. The hybrid story depends upon it, but more importantly Microsoft has huge customers that are in the process of moving to SharePoint Online from on-prem environments based on the current UI.

In fact, if you have significant investments in custom solutions based on the current UI, you should be feeling a sense of relief. Most such solutions have some level of dependency on UI things Microsoft has said should not be depended upon and we all live with some level of fear that we will wake up one day to find one of the dependencies changed and our solution is broken. Microsoft’s new approach makes this much less likely.

The only reason to be concerned is if you are an ASP.Net Web Forms developer who hasn’t made moves to learn modern web development – in which case it is well past time you hit the books. I promise that it is easier than what you are doing now which is why the rest of us have moved on.

#2: It Restores a Key Value Proposition of SharePoint for SharePoint as a Platform

A big reason for SharePoint’s success is that it is based on ASP.Net Web Forms. Ten years ago, a big chunk of enterprise web developers used ASP.Net as their primary tool. This meant that SharePoint development was pretty approachable to many enterprise developers. Since then though, times have changed. New developers aren’t learning ASP.Net Web Forms. What was a big strength has now become a big weakness and traditional SharePoint development skills are niche skills in today’s job market.

This is a problem for everyone in SharePoint land that needs developers including Microsoft. There are people working as developers on the SharePoint platform who were not old enough to use the kitchen stove when ASP.Net Web Forms came out!

The new SharePoint Framework means that SharePoint development is now in step with mainstream web development once again, except this time you have a lot more choices. It also matters less what choices you make because the framework offers a better way to isolate your solution while also being as deeply integrated as is required.

Furthermore, the new framework embraces the fact that you need the ability to participate in the page’s real DOM. It no longer forces the use of things like iframes and weird URLs. You don’t need to be clever or go against the grain as is often required now to build the types of customizations required by the business you are in.

#3: Open Processes Work Better

I’ve been focused on SharePoint for a decade and I’ve been an MVP for the last five years. For most of that time what Microsoft intended to deliver was completely set in stone by the time anyone outside the SharePoint team knew what was coming. As a stakeholder, the best you could do was complain loudly in hopes that the thing will be better in three years when the next version comes out. In some areas, the Office development teams have fully embraced open source software and open development. In this case they opened up on the core platform for the first time and got feedback at several points in the process. I think the result will be much closer to ‘good’ out of the gate than I had previously come to expect because this time around I’ve actually seen them change their minds based on feedback from outside their own team!

I admire the SharePoint team for how far they have come in this regard. Opening yourself up to criticism is not easy. Personally, I hate it.

I could sense the stress at the Dev Kitchen. It must have been terrifying for each of them. At dinner on the last night, after what was clearly a successful event I could sense the relief. They’d deliberately put themselves through the wringer and survived, but they all looked like they were going to fall asleep!

Make no mistake – it is still early. The first releases of this stuff are guaranteed to have holes and annoying flaws, but things should improve quickly because…

#4: The Biggest Issue with Modern SharePoint as a Platform is Being Fixed

In my opinion, the single biggest factor with the limited success of sandbox solutions and the first versions of the app/add-in model was not that each lacked or blocked functionality that was easily accessible in farm solutions. No, the biggest issue with modern SharePoint as a platform is that the SharePoint development team did not use either model themselves. They had no real skin in the game and no internal incentive to fix what was always somebody else’s problem.

The SharePoint Framework does not just align SharePoint development with modern web development. It also more closely aligns the SharePoint development team with the developers who are customizing SharePoint. Unless they make a habit of cheating, the really big flaws are going to get fixed.

#5: Microsoft Needs Your Help

All that said, there is still some cause for concern. The document library preview release left many scratching their heads. The fact that they dropped something like into first release that without even putting it on the roadmap was hard to understand. And the absence of support for fundamental features we and PnP rely upon such as script custom actions or jsLink was just dumb.

Please note that I know dumb when I see it. As a very experienced and well-respected software developer and business owner I work in dumb like other artists work in clay or oil.

As an outsider it’s fun to speculate where that sort of dumb comes from. Is there a powerful manager that hates PnP and the rest of us so much that they would withhold a couple key lynchpins to see it fail? That would make a great story, but still, it is hard to believe one person could generate that amount of dumb. It probably required a whole team!

I believe that, for a long time, the SharePoint team generally thought that the use of either of these missing features was a hack that should be discouraged because script injection was bad and therefore they were bad. Perhaps now that SharePoint is embracing script injection people still subconsciously want to kill those features but don’t realize their ‘flaws’ are now seen as virtues. This a sort of diffuse cloud of dumb that is common in groups with a long history even where all of the individuals are very smart.

Or maybe the dumb wasn’t dumb at all. Maybe it’s the people focused on building the new document library had a narrow focus that didn’t include any integration scenarios.

Whatever the reason, feedback is to dumb as sunshine is to nasty germs. Their development process is now built to generate lots of feedback before delivering and act upon it. You can help by getting involved and giving lots of feedback in the public Yammer network and on SharePoint’s User Voice page.

Speaking of User Voice and the missing document library features…

#6: It’s not Vaporware

The Dev Kitchen I attended had several accomplished SharePoint development experts, but it also met a good number of people from ISVs who didn’t have much, if any, experience working with SharePoint. I saw people working in OSX, Linux, and Windows. There were a number of scripted hands on labs, but we also had free time to implement our own solutions. Over the course of three days I saw several really impressive samples from this diverse bunch of people.

As for myself, I took a moderately complex sample that uses AngularJS and Bootstrap for pluggable components and wrapped it in the new stuff. It took very little time, and the end result worked in both the current UI and in the new UI. I should probably mention that I was pretty unlucky and was in pain from a kidney stone during much of the event! Even in my diminished and pitiful state I was able to work completely outside the script and it worked!

SharePoint Wiki Page with Web Parts Pattern for Custom UI

In my previous post I used a scoring system to come up with an answer to the question: What is the most ideal type of page to use when customizing SharePoint? Somewhat surprisingly, the answer based on my criteria is a SharePoint Wiki Page. A wiki page which has the advantage because all wiki pages are served from a shared template instead of being actual files. Creating a wiki page doesn’t create a custom ASPX page that requires maintenance. By relying on the central template, the structure and features of a wiki page stays up to date as SharePoint evolves.

In this post I will cover one of the patterns for custom UI based on wiki pages we use in our apps here at InstantQuick: Wiki Page with Web Parts. This pattern is best if we want to allow the owners of the target site to modify the solution after it is deployed. It does not require a provider host and works when an add-in is fully contained in SharePoint. You can see this design pattern in action in the IQParts – Cloud App Compatible Web Parts using AngularJS and Bootstrap sample framework.

Wiki Page with Web Parts Pattern

This pattern is the easiest to follow because you can implement it using nothing but SharePoint and a text editor like notepad. The pattern consists of a wiki page, the default page type in a Team site, and one or more Content Editor or Page Viewer Web Parts that load the custom solution. Logically, the pattern looks like this:

The pattern is simple, but one important rule is that a customization’s appearance and behavior should depend only on the scripts, style sheets, and other resources included in the customization – not on the parent document’s or its related resources. Following this rule gives your customization the best chance for a maintenance free future as the SharePoint platform evolves.

The easiest way to enforce this rule is to refine the pattern to contain the customization in an iframe.

The iframe creates a new document that allows the customization to work in isolation from the parent document. In this version of the pattern the app must be contained in an ASPX page. The default permissive file handling settings will cause the browser to download html files instead of rendering the html in a frame. The file extension prevents the download.

The container ASPX used in in the IQParts – Cloud App Compatible Web Parts using AngularJS and Bootstrap sample framework is shown below. As you can see it does not contain any actual server side code.

What is the most ideal type of page to use when customizing SharePoint?

Very few platforms offer the range of customization options that SharePoint offers. The menu is huge! How does one go about the task of choosing the most ideal way to do anything?

In this post I am going to tackle one of the most fundamental choices everyone faces – What is the best way to make a custom web page for a SharePoint customization?

For this contest I am including only options that do not require third-party solutions and that work on-premises and in SharePoint Online.

The Contestants

The nominees for the best way to make a custom SharePoint web page are:

  • Custom SharePoint ASPX Page
  • External / Provider Hosted UI
  • Publishing Page
  • SharePoint App-in Web Hosted UI
  • Traditional SharePoint Web Part Page
  • SharePoint Wiki Page

Evaluation Criteria

Not long ago I wrote a post describing 8 Characteristics of an Ideal SharePoint Customization. I will judge each of the options based on these ideals, but to be as objective as possible pretend that each option meets the first and last ideals: It meets the needs of the people who use it without limitations imposed by the platform and It is manageable and governable.

In other words, I will try to do this without introducing hypothetical requirements or assuming anything about the ability of an organization to support and maintain the solution. This will let me answer the question of the most ideal option in general.

In real life, with real requirements and real people, you should always evaluate whether each option meets the needs of the people who use it without limitations imposed by the platform and if you can manage and govern the result. Sometimes the actual requirements will determine or limit your options. For example, if you are building a site using SharePoint’s publishing features, you will use Publishing Pages.

Finally, because this is specifically about pages the ideal, Runtime or configuration faults in a customization can only impact the customization, generally doesn’t apply; we use different tools to break whole sites.

That leaves five remaining ideals we can use to weigh the options.

  1. It doesn’t interfere with the operation of the underlying platform
  2. It uses SharePoint functionality as much as possible
  3. It depends on things other than SharePoint as little as possible
  4. It cedes runtime control to SharePoint as little as possible
  5. The other things it depends on are provided via supported mechanisms other than directly editing SharePoint Master Pages or ASP.NET files

Scoring

Here is a place where my ideals could use some refining, because ‘as little as possible’ is subjective. However, I am comparing each option to each ideal and saying ‘true’ or ‘false’ without giving partial credit. The one with the most true’s wins the prize.

Summary

 

A

B

C

D

E

Custom SharePoint ASPX Page

 

X

X

   

External / Provider Hosted UI

X

   

X

X

Publishing Page

 

X

X

   

SharePoint App-in Web Hosted UI

   

X

   

Traditional SharePoint Web Part Page

 

X

X

   

SharePoint Wiki Page

X

X

X

 

X

 

Custom SharePoint ASPX Page

Custom SharePoint ASPX pages are often created by modifying a Web Part page in SharePoint Designer.

Ideal Aspects

  • It uses SharePoint functionality as much as possible
  • It depends on things other than SharePoint as little as possible

Non-ideal Aspects

  • It interferes with the operation of the underlying platform
  • It relies on SharePoint for runtime behavior
  • It is a direct edit to an ASP.NET file

The way a custom ASPX page interferes with the underlying platform is by creating a custom page that is subject to safe mode parsing and be compiled. As a unique object it will diverge from non-customized pages over time.

External / Provider Hosted UI

External / Provider Hosted UI serves the user interface from a provider outside of SharePoint. The custom UI consumes SharePoint services via one or more client API’s.

Ideal Aspects

  • It doesn’t interfere with the operation of the underlying platform
  • It cedes runtime control to SharePoint as little as possible
  • The other things it depends on are provided via supported mechanisms other than directly editing SharePoint Master Pages or ASP.NET files

Non-ideal Aspects

  • Typically recreates functionality that could be provide by SharePoint
  • It is completely dependent on the external host

Publishing Page and Traditional SharePoint Web Part Page

These types of pages are examples of Custom SharePoint ASPX Pages and are ideal and non-ideal in the same says for the same reasons. Publishing Pages typically rely on custom master pages and page layouts. Client API’s create traditional SharePoint web part pages by copying the ASPX from an out-of-box page into a new file.

SharePoint App-in Web Hosted UI

SharePoint App-in Web Hosted UI is hosted in a special web in a domain outside of the containing site’s domain.

Ideal Aspects

  • It depends on things other than SharePoint as little as possible

Non-ideal Aspects

  • It interferes with the operation of the underlying platform
  • Typically recreates functionality that could be provide by SharePoint
  • It relies on SharePoint for runtime behavior
  • It is a direct edit to an ASP.NET file

Pages in SharePoint App-in Webs are Custom SharePoint ASPX Pages with less access to SharePoint functionality than the other types of custom pages in this competition.

SharePoint Wiki Page

SharePoint Wiki Pages are superficially similar to traditional SharePoint Web Part pages with one important difference – they are not custom ASPX pages. A wiki page is served from a shared template that changes over time.

Ideal Aspects

  • It doesn’t interfere with the operation of the underlying platform
  • It uses SharePoint functionality as much as possible
  • It depends on things other than SharePoint as little as possible
  • The other things it depends on are provided via supported mechanisms other than directly editing SharePoint Master Pages or ASP.NET files

Non-ideal Aspects

  • It relies on SharePoint for runtime behavior

The Winner!

In general, a SharePoint Wiki Page is the best type of page to use when customizing SharePoint. You can see one of our preferred design patterns in action in the IQParts – Cloud App Compatible Web Parts using AngularJS and Bootstrap sample framework. I will be covering our favorite design patterns and how they are constructed in a future post.

–Doug Ware

Architects: SharePoint is a Platform, Treating it as only a Service is a Mistake

Last week my friend Andrew Connell wrote a rather provocative post titled Developers: SharePoint isn’t a Platform, SharePoint is a Service. In it he makes some persuasive points and advises people to move their front end development out of SharePoint. In this post I’d like to deconstruct a few of his points and explain why I think his advice in this regard is not very good.

The Past Product Engineering Failures at Microsoft Happened

A large portion of his post concerns the undeniable fact that Microsoft has offered a series of customization models for SharePoint over the years with varying degrees of success. I agree with just about everything in this section.

There has been a series of models from the SharePoint team, and, in some respects, Microsoft has shown a shocking lack of integrity as a vendor and business partner in the way they cavalierly advised customers to do things certain ways only to later say ‘whoops! We changed our minds’. Taken from a certain angle it’s almost unforgiveable.

On the Other Hand

I think everyone can agree that web technologies changed greatly between the births of 2003 and 2013. Office 365 was impossible in 2003 simply based internet speeds. Over the span of a decade, the medium (web) changed quickly and often in surprising ways. To that, add Microsoft’s adventures in rich internet applications (Silverlight) and the emergence of cloud technologies enabled by practically ubiquitous and fast internet connections. Is it surprising that Microsoft has tried to change SharePoint development to account for these things? Is it surprising that some of these were failures?

Just the same, it is possible to migrate solutions originally created for SharePoint Server 2003 to SharePoint Server 2016. Some migrate with little effort and sometimes it is so hard that it isn’t worth it. However, consider that the vast majority of other Web platforms you could buy in 2003 no longer exist as actively developed products. Then, ask yourself: how many of them allow you to take what you did in 2003 and move it with zero effort to their current version? Do you have anything in your current Web development stack that worked in 2003? Are there any that didn’t have some disruptive breaking change between then and now?

Getting $5 of Value from your $10 Purchase

A simple truth in software development is that the less a piece of software depends on other software, the better. This is always offset by the fact that depending on other software makes it faster and cheaper to build systems. Paradoxically the development experience can be much more pleasant even if it takes longer because as a developer you get much more freedom and you don’t have to deal with the quirks or restrictions imposed by the makers of the platform.

Naturally, faster and cheaper pretty much always wins. The users of the software still expect ‘better’, but it is a ‘better’ from their perspective: better at helping themselves do what they want to do. They don’t care how it gets built.

Deliberately tying a solution to a platform makes sense when you can trust the platform to stick around long enough and when the costs of depending on the platform are offset by a sufficiently positive return on investment over the life of the solution. One of those costs is that the implementer will often be more expensive than a generalist because they have to not only understand the set of development technologies and the customer’s requirements, but also understand the design and uses of the platform. In exchange it is expected that the implementers will leverage the platform well enough that the cost of the implementation will still be lower than building a custom solution. If not, it should be true that the total cost of ownership of the system over its life will be lower by using the platform than if it was custom.

If neither of these turns out to be true then the project is a failure on a certain level.

A model where SharePoint becomes a service to custom standalone systems significantly changes SharePoint’s value proposition because it is a deliberate decision to assume the dependency on SharePoint and all of its costs while simultaneously rejecting a big chunk of the features that you can use to offset the costs of ownership. Presumably your solution will still need things, like a user interface, that you could have gotten mostly or even completely from the platform. Perhaps a less expensive web developer could build those for you, but no matter what the hourly rate is, you still built something to use in place of something for which you’ve already paid.

This is a Design Problem

One thing Andrew and I agree on is that a good customization should be as isolated as possible and that a good design should actively address this concern. I think there are times when it is appropriate to treat SharePoint as a service. IQApp Central is a standalone provider hosted solution. It exists outside of SharePoint because we thought the design was most appropriate. On the other hand, add-ins like Instant Practice Manager, the Board of Directors Site, and IQApp Parts are integrated into SharePoint sites and fully integrate the platform. The previous few posts touch on how we isolate AngularJS and Boostrap in IQApp Parts so check those out if you are interested. Keep in mind that this is by no means the only possible way to isolate integrated functionality.

A Note on Patterns and Practices

Andrew says that he thinks Office 365 Dev Patterns and Practices is an example of trying to have your cake and eat it too. I say that it is actually the first time the SharePoint team has made an effort to directly engage and meet customers’ needs with regards to real world scenarios in quite some time. I dare also say that had the program existed the sandbox model would have never been born and the initial forms of the cloud app model would probably have looked very different from what we actually got from Microsoft. I recommend that you check out this post from Vesa Juvonen and decide for yourself if they are serious or not.

This is also a Trust Issue

At the end of day this is also a trust issue. Do you trust Microsoft not to make changes that cost you time and money if you integrate with their platforms?

You shouldn’t! I can guarantee that they will do things to make your life harder at some point in the future.

The same is true of any vendor that offers platforms with a long life span. It doesn’t matter how big they are. Times change and software has to evolve. Sometimes they will make a hash of it. Sometimes the vendor will screw up so badly it will even kill the platform.

If you trust Microsoft to avoid wrecking the bus, then acknowledge the potential bumps in the road and exercise defensive design, but wring every last dollar of benefit you can get out of the platform in the meantime. Moving everything outside the platform is not the way to do it.

If you don’t trust Microsoft to avoid wrecking the bus, that’s OK too, but move on. You are building custom solutions. Surely you can do better and more cheaply than SharePoint as a data and file storage service!

–Doug Ware

Using the SharePoint Client Object Model in AngularJS Apps

A common problem for SharePoint developers new to AngularJS is using the client object model within the context of AngularJS scopes.

The Problem Explained…

If you already understand AngularJS, feel free to skip this part!

Consider a controller that displays the name of the current user.

<div ng-controller="IQAppPart">
  <div ng-if="!!UserName">
     <h1>Hello <span ng-bind="UserName"></span></h1>
  </div>
 </div>
 

If the $scope variable of the IQAppPart has a value for UserName the greeting appears.

The IQAppPart controller function looks like this:

var iqAppPartModule = angular.module(‘iqAppPartModule’, []);
var iqAppPartController = iqAppPartController || {};
iqAppPartController.IQAppPart = function ($scope) {
//Make a request for the user
var ctx = SP.ClientContext.get_current();
var user = ctx.get_web().get_currentUser();
ctx.load(user);

//Send the request to SharePoint
ctx.executeQueryAsync(function () {
    //Set the UserName
    $scope.UserName = user.get_title();
  }, function (error) {
    alert(error.get_message());
  });
};
iqAppPartModule.controller(‘IQAppPart’, [‘$scope’, iqAppPartController.IQAppPart]);

Notice the highlighted line. This sets UserName and you might expect that this would in turn cause AngularJS’s magic data binding to display the greeting, but instead nothing would happen.

The code will run without error and retrieve the UserName, but that’s all. The greeting will not display. The reason for this is hard to see if you are new to AngularJS because the code sets the $scope and the line that does it is inside the controller function!

To understand the problem you must first realize that the call to SharePoint, executeQueryAsync, calls the success handler when it receives the result from SharePoint. The function call is an asynchronous operation that AngularJS knows nothing about.

The second thing you need to understand is that Angular’s model binding expects all operations of interest to start within the confines of an Angular process. When a page that is using Angular starts an Angular app via the presence of the ng-app directive on an HTML element or by calling angular.bootstrap(element), Angular starts listening for events specified element (with the attribute or passed to the bootstrap function) and all of the element’s descendants. So, it knows about clicks and other events. Whenever one happens, it reevaluates the model and then updates the HTML view.

Adding a call to $apply() as shown below fixes the problem. The call to $scope.$apply() tells Angular that something has changed and that it should do its work.

var iqAppPartModule = angular.module('iqAppPartModule', []);
var iqAppPartController = iqAppPartController || {};
iqAppPartController.IQAppPart = function ($scope) {
 //Make a request for the user
 var ctx = SP.ClientContext.get_current();
 var user = ctx.get_web().get_currentUser();
 ctx.load(user);
 //Send the request to SharePoint
 ctx.executeQueryAsync(function () {
   //Set the UserName
   $scope.UserName = user.get_title();
   $scope.$apply();
  }, function (error) {
   alert(error.get_message());
  });
};
iqAppPartModule.controller('IQAppPart', ['$scope', iqAppPartController.IQAppPart]);
 

Calling $apply() in the context of a controller is a big sign that you are doing it wrong!

Instead we need a mechanism that makes ClientContext.executeQueryAsync() work like any other service in AngularJS so that Angular will know when it is time to reevaluate the models and update the views.

The Solution

The solution is a service factory that wraps executeQueryAsync using Angular’s $q
service. $q is a service that helps you run functions asynchronously, and use their return values (or exceptions) when they are done processing.

//Angular service Wrapper for ClientContext executeQuery.
//The $q service makes it easy to wrap SharePoint's context.executeQueryAsync for use with Angular
var module = angular.module('iqPart', [])
 .factory('SharePointService', ['$q', function ($q) {
   var SharePointService = {};
   SharePointService.executeQuery = function (context) {
     var deferred = $q.defer();
     context.executeQueryAsync(deferred.resolve, function (o, args) {
       deferred.reject(args);
     });
     return deferred.promise;
  };
  return SharePointService;
}]);

To use the SharePointService we inject it into the controller and use it instead of ctx.executeQueryAsync as follows.

var iqAppPartModule = angular.module('iqAppPartModule', []);
var iqAppPartController = iqAppPartController || {};

iqAppPartController.IQAppPart = function ($scope, sharePointService) {
  //Make a request for the user
  var ctx = SP.ClientContext.get_current();
  var user = ctx.get_web().get_currentUser();
  ctx.load(user);
 sharePointService.executeQuery(ctx)
   .then(function () {
     $scope.UserName = user.get_title();
   },
   function (error) {
     alert(error.get_message());
 });
};
iqAppPartModule.controller('IQAppPart', ['$scope', 'SharePointService', iqAppPartController.IQAppPart]);
 

The end result is something like:

–Doug Ware

IQParts – Cloud App Compatible Web Parts using AngularJS and Bootstrap

We are in the process of releasing three free SharePoint Add-ins from IQApp Central: Absence and Vacation Request Management Site, Board of Directors Site, and AngularJS 1.4 and Bootstrap 3.3 Web Parts. We’ll release all three as side-loaded apps over the next couple weeks for host webs and the first two as SharePoint hosted apps will be available via the Office store. Until then, you can get all three using Free SharePoint Add-Ins page in IQApp Central.

Today I am pleased to introduce AngularJS 1.4 and Bootstrap 3.3 Web Parts. This is a sample created using IQApp Central​. It is a framework that allows for user configurable Web Parts built using SharePopint, AngularJS 1.4 and Bootstrap 3​. ​This sample contains two Web Parts, six sample apps, an extensible configuration system, a template to help you get started with your own apps, and some handy functions to make integrating with SharePoint pages and services easy.

This sample started as an exercise to attempt an ideal design based on the 8 Characteristics of an Ideal SharePoint Customization. Integrating AngularJS and Bootstrap with SharePoint while trying to maximize the 8 ideals is a great challenge because SharePoint and AngularJS are both very assertive, demanding frameworks that want total control over a page and Bootstrap wants to completely own the base styles.

For example, here is a SharePoint page.

And here is the same page with Bootstrap 3’s CSS loaded.

Most projects that use Bootstrap start with a custom master page and end with a complete theme. Naturally this is not an option when you are creating components that, like Web Parts, are expected to work on any site.

Here is one of the sample pages included in AngularJS 1.4 and Bootstrap 3.3 Web Parts. It contains three of the sample apps and has a theme applied. Note how the parts do not break the containing page or the site’s style.

Configurability

There are a few projects out there that have tackled the configurable Web Part problem including this very good one by Rachid Bouzalmat. This approach works, but it is less than ideal on a couple of counts (based on the 8 Characteristics of an Ideal SharePoint Customization). Specifically it uses jQuery to target particular elements in a SharePoint page. It also depends on the ability to hijack SharePoint’s JavaScript. In the interest of full disclosure, we have code that does both of those things for different reasons. I am just as guilty, just not in the case of this sample!

I will write more about how we implemented our Web Part containers and the configuration system in a future post. In the meantime you can see for yourself how it works by installing the sample. Until then here is a shot of the sample page in design mode.

–Doug Ware

8 Characteristics of an Ideal SharePoint Customization

I’ve been working with SharePoint for the last eight years. In that time I’ve built many SharePoint solutions using nearly every available approach. Eight years is a long time. It’s long enough to give, hear, and read a ton of ‘best practices’ advice. It’s long enough to learn from the lifetime of too many design choices to count.

This post is my attempt to enumerate the qualities of an ideal SharePoint customization based on what I’ve learned. Keep in mind that these are ideals and the real world involves trade-offs. What do you think?

  1. It meets the needs of the people who use it without limitations imposed by the platform
  2. It doesn’t interfere with the operation of the underlying platform
  3. It uses SharePoint functionality as much as possible
  4. It depends on things other than SharePoint as little as possible
  5. It cedes runtime control to SharePoint as little as possible
  6. The other things it depends on are provided only by using supported mechanisms other than directly editing SharePoint Master Page or ASP.NET files
  7. Runtime or configuration faults in a customization can only impact the customization
  8. It is manageable and governable

Ideal #1: It meets the needs of the people who use it without limitations imposed by the platform

This is the most important thing. Does it do what people need it to do? If someone asks if the system can be made to do something is the answer ‘yes, it will cost x‘ or ‘we can’t do that because…’? Is it available when they need it?

Sometimes what people need will be the underlying factor that drives decisions that result in successful but far from ideal customizations.

Ideal #2: It doesn’t interfere with the operation of the underlying platform

SharePoint is built to be a shared resource. It’s in the name. Customizations should be polite and let the shared services do their work unhindered by external customizations. Customizations that integrate directly with runtime processes have the potential to cause general denial of service conditions for an entire SharePoint property. Customizations that directly integrate with the platform might not cause issues in the present, but are later discovered to be significant obstacles to moving or upgrading a farm or site.

Ideal #3: It uses SharePoint functionality as much as possible

This may seem to go without saying, but often people recreate the wheel. Creating custom functions for out of the box features directly affects a system’s ROI by increasing the investment required and potentially its ongoing cost. SharePoint is a rich resource. Ideal customizations marshal the available resources to full effect.

Ideal #4: It depends on things other than SharePoint as little as possible

Sometimes people try to fit a square peg into a round hole. The more a customization requires things other than SharePoint the more likely a customization is a square peg. Of course it is often necessary in the real world to integrate with other systems and it is even more common to use third party components. Just the same, a customization that meets Ideal #1 by using nothing but out of the box functionality is, by definition, an ideal SharePoint customization.

Ideal #5: It cedes runtime control to SharePoint as little as possible

While an ideal customization makes deft use of SharePoint’s functionality it should do so in a way that works independently of SharePoint. For example a customization that fully controls an area of a page is better than one that consists of many hooks into SharePoint by depending on particulars of the HTML generated by SharePoint. The former can function as an atomic unit, the later can break any time the details of the page deviate from the original. It is better to provide an entire form than to hook into a button’s click event based on the ID of the element or a class name on the day the customizer did View Source on a page.

Ideal #6: The other things it depends on are provided via supported mechanisms other than directly editing SharePoint Master Pages or ASP.NET files

Meeting Ideal #1 may require you to directly edit SharePoint master pages or ASP.NET files. Doing so has a cost and it potentially requires ongoing maintenance. At times it might violate Ideal #2 if the customization lacks as of yet un-invented elements that later will come to be expected. As it stands, SharePoint provides a large number of supported integration options out of the box including Web Parts, custom actions, and a wide variety of API’s. Be aware that some supported mechanisms are counter to Ideal #5.

Ideal #7: Runtime or configuration faults in a customization can only impact the customization

This one is simple. If your app breaks for a user does it break SharePoint? Breaking SharePoint includes denial of service conditions at the server as well as client side problems that prevent pages from rendering or operating as intended. It is possible to meet Ideal #2 but not this ideal. For example, introducing a syntax error into JavaScript in the body of the default master page will not interfere in any way with the underlying platform but will still break a site.

Ideal #8: It is manageable and governable

Once created or deployed, an ideal customization is manageable and governable. It offers appropriate configuration surfaces and respects SharePoint’s policies, throttles, and security. It isn’t obscure, but rather easily discoverable. It is possible for it to be known and accounted for to the degree that is required. One example of a customization that is not ideal in this regard is a user custom action created by hand. At present out of the box there is no way other than interrogating the SharePoint object model via one of many APIs to determine a user custom action is present or modify the user custom actions associated with given object. Conversely, a customization that includes the same user custom action can be ideal if it includes the same custom action as long as the customization provides appropriate management features such as the ability to remove the action if the customization is removed or disabled.

Why is this important?

We have more options available for creating SharePoint customizations today than we’ve ever had before. We need a framework to help evaluate these approaches to make good design choices. Over time I will be writing about our designs here at InstantQuick. IQApp Central supports a number of different design approaches. I designed it to be respectful of people’s decisions by playing well with SharePoint. Still, there are some designs I encourage that I’d like to teach you about. When I say that something is better I’d like to do so in the context of concrete criteria. That way, when someone disagrees it is easier to engage in productive dialog!

–Doug Ware