When developing SharePoint Framework components (web parts and extensions) you may release a single one to an environment and be done with it. Or more likely you’ll be creating multiple web parts and extensions and will need to decide how to approach SPFx packaging.
Things to consider when packaging SPFx components
How do I share my code between components?
How do I share library code between components?
How do ensure that components use the same version of the SharePoint Framework?
How do I version dependencies of the components?
How do I upgrade components?
What is the development/test environment like?
All these questions really boil down to a single question:
Do you a create a multi-component SPFx project or have a project for each component?
* SPOILER *
I have concluded that the default approach to SPFx packaging should be to include all components into a single multi-component project. Avoid creating multiple packages where possible. Depending on the scale of the development team there may be some scenarios where this is not appropriate, in which case create as few multi-component projects as are necessary. Furthermore, I recommend creating a single multi-component JS bundle file for all web parts in package (a multi-component bundle), rather than the default approach of having a JS file for each component.
Multi-component project/package: SPFx packaging such that a single sppkg file is produced which deploys multiple SPFx web parts or extensions. Multi-component bundle: Only available within the context of a multi-component project, a multi-component bundle includes the JS required for all components as a single file rather than a file for each component.
Or perhaps you’d like me to explain my rationale, the benefits, and where this approach may not meet your needs. In which case, please read on..
What you sacrifice by having a single project
Firstly, let’s discuss what is sacrificed by packaging SPFx components into a single sppkg package?
You can no longer install or upgrade components individually. (However, the new site collection scoped app catalog may assist with this.)
Depending on your development environment, it may be easier to govern source code and DevOps processes during development and test. For example if you have different teams working different web parts.
During development you can build and deploy individual components which may lead to time savings if/when the volume of components becomes large. (In these cases the gulp tool chain could be modified to meet requirements.)
What you gain by having a single project
If the above list of sacrifices aren’t deal breakers then there are many benefits to be had by taking this approach.
Deployment and upgrade is trivial especially with tenant-scoped deployment – just deploy a single package to the app catalogue and you are done.
The risk of having multiple web parts using different versions of the SharePoint Framework is avoided.
The risk of having multiple versions of third partly libraries loaded is greatly reduced.
Total payload of components will be much smaller due to reduced duplication of shared code, library code (especially Office UI Fabric), and the framework itself due to multi-component bundling. Sub-optimal usage of external references, static vs dynamic import statements, and the bloat that some recommended frameworks currently inflict (Office UI Fabric React…) can lead to very substantial page weight increases. By using a multi-component bundle the worst case scenarios are avoided as in most cases these issues will impact a solution once for each bundle.
Versioning of shared code is trivial because you don’t have to it. Internal dependencies are including the bundle and external dependencies are referenced to only once. The framework itself handles the component versioning for you.
I’d be particularly interested to hear from people who have found strong reasons to package components individually because currently I believe that the benefits of multi-component SPFx packaging outweighs the benefits in nearly all scenarios.
I recently joined Jeremy Thake of Hyperfish and my colleague David Bowman to host a webinar focussed mainly on some our favourite announcements that came out of Ignite 2017. I have a list of my recommended viewing from the conference at the end of this post.
The webinar was to have primarily a non-technical audience so it doesn’t get deep into many particularly technical topics but it does give a good overview of some of more important announcements of Ignite 2017, in my humble opinion.
I recently wrote a post for my employer about the recent history of SharePoint extensibility models. It also touches on how we as company settled on the model with which we are currently delivering our Intranet/Digital-Workplace solution. I discuss the Feature Framework, Farm and Sandboxed Solutions, SharePoint Add-in Model, SharePoint Framework, Remote Provisioning, and more.
The Office 365 CDN (Content Delivery Networks) may be activated to host SharePoint Online files in a more globally accessible manner. The general premise behind this is that static assets can be served to users from a location more local to them than the data centre in which the Office 365 tenant is located.
I won’t go into the real benefits of this beyond to say that my limited testing at this point leads me to believe that the performance impact of using a CDN will be negligible for the vast majority of users/organisations. This is because the volume of data which can be served via the CDN is not a significant proportion of the data impacting page load speed.
Regardless, the documentation around how to get started with the Office 365 CDN is decent. A good place to start is this link.
A couple of gotchas I’ve noticed
Fetching an image rendition using the width query string parameter does NOT correctly return the image rendition as configured. It simply scales the image to the specified width (i.e. no cropping or positioning is performed).
I’ve got some sample PowerShell below showing how to activate the Office 365 CDN (there’s private and public, you can use either or both) and associate origins with it (an origin is a document library which will be replicated to the CDN).
I’ve also got a simple sample of how to remove all origins as there is not a single cmdlet for this. It is worth noting that although an enabled CDN with no origins is functionally identical to a disabled CDN (i.e. no files are being replicated) they are not the same from a configuration perspective.
Please note that these are just sample scripts and have not been parameterised as you may require.
OAuth 2.0 (and hence Azure Active Directory) provides the On-Behalf-Of flow to support obtaining a user access token for a resource with only a user access token for a different resource – and without user interaction.
This supports the scenario where a secured Web API acts as an interface to other resources (a.k.a endpoints) secured by the same identity provider and that require user context. As a practical example, a mobile client accesses some resources via a middle tier API which provides services such as data processing, caching, API simplification/optimisation, joining of datasets, etc.
The OAuth flow that achieves this is called the On-Behalf-Of flow; this makes sense as we’re facilitating the middle tier to act on behalf of the client when it accesses the resources farther down.
Authentication with an OAuth 2.0 identity provider (such as AAD) produces JWT tokens. These tokens include information such as which claims (permissions) the user should be granted and the particular resource at which the token is valid (such as graph.microsoft.com). The OAuth 2.0 framework is specified such that a given token can only ever be valid for a single resource. This means that the token received by an endpoint (such as an Azure App Service Web API) cannot be used to directly authenticate to ‘another resource’. This is because the token’s resource will be that of the Web API and not the ‘other resource’. To see this I recommend checking out jwt.io and cracking open some tokens.
For completeness, the ‘other resource’ could be accessed using app-only authentication if it supports it, and if user context is not required (i.e. the return value will be the same regardless of the user) although this may greatly increase complexity in a multi-tenant scenario.
Configuring AAD for on-behalf-of
Before we get to the code the first hurdle is configuring AAD app registrations correctly. Initially it may be tempting to consider having both the Client and Web API layers utilise a single AAD app registration. After all, they are same holistic ‘app’ and how else can we get a user to consent to the permissions required by the Web API app when there is no interactive interface at that point? The latter point is resolved by explicitly binding the app registrations so that both are consented to as one. I mention how this is done below. By having two app registrations the flexibility of configuration is improved; we can have a Native app registration for the client and a Web API app registration for the Web API, we can have implicit flow configured for one app and not the other, and generally have granular control over configuration. Most vitally, an app registration can’t issue tokens valid for its own resource so two app registrations is a requirement.
I’ll avoid stepping though the configuration of the app registrations here as this is available elsewhere including this GitHub project. I will give a high level overview of what needs to happen.
Create app registration for the Web API
Assign permissions to the downstream resources (e.g. Microsoft Graph, a custom Web API, etc)
If supporting multi-tenant authentication ensure availableToOtherTenants is set to true in the manifest
Create app registration for the Client
Assign permissions to the app registration created above for the Web API
If supporting multi-tenant authentication ensure availableToOtherTenants is set to true in the manifest
Associate app registrations
In the manifest for Web API app registration, configure knownClientApplications to reference the App ID for the app registration created for the Client. E.g. "knownClientApplications": ["9XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXc"]
This binds the app registrations such that the Web API app registration is consented to as part of a single consent dialog displayed to a user when they authenticate to the Client app registration.
I was inspired to write this post not because this information isn’t available but because the information is hard to find if you aren’t familiar with the term “On-Behalf-Of”. Hopefully this post will be found by those of you searching for terms like “trade access token for new resource”, “change token resource”, “use access token with multiple resources/endpoints”, “access Microsoft Graph via Web API”, etc.
Back in SharePoint 2010 the RSS Viewer web part (a.k.a RSS Aggregator web part, RSSAggregatorWebPart) supported the use of XSL templates which contained script tags. There were a few funny things you had to in order get it working but it did work. Bring on SharePoint Online and it is not possible to add a script tag to your XSL templates (I believe this ‘issue’ exists on SharePoint 2013 as well). More accurately, script tags can be added and will rendered to the page but the script will not be executed.
In this day and age the correct answer is very likely: “why are you using this web part?” or “XSL are you mad?”. Both very strong arguments, but regardless, for the record you can code (hack) your way around this issue.
Use the onerror handler of an image tag to instantiate your JS. Ensure that the img tag is rendered as the last element in your template if you plan on using the js to modify the DOM.
However, when doing this you may have encountered the following error:
Could not install package ‘Microsoft.IdentityModel.Clients.ActiveDirectory 3.13.9’. You are trying to install this package into a project that targets ‘.NETPortable,Version=v4.5,Profile=Profile259’, but the package does not contain any assembly references or content files that are compatible with that framework. For more information, contact the package author.
I’m using Visual Studio 2017 (VS2017) with Xamarin for Visual Studio 4.5. The Cross Platform App project template has it’s Target Framework Profile configured to Profile259 as stated in the error. This profile is an alias for the set of supported target frameworks. This profile doesn’t include Windows 10 Universal Windows Platform and does include Windows Phone 8 and 8.1 which are not supported. Profile7 represents a set of target platforms which is supported. The TargetFrameworkProfile can be seen by viewing csproj file in a text editor.
Changing the target frameworks
In order to change the set of target frameworks, right click the project, click Properties, then click Change... under Targeting.
Add Windows Universal 10.0. Adding support for UWP implicitly removes support for Windows Phone 8 and 8.1. If you don’t see Windows Universal 10.0 it may because you need to have Windows 10 installed.
Click OK. And you’ll see another error:
In order to get around this, go back to the nuget package manager and uninstall all packages installed against the PCL project. In my scenario, this is only the Xamarin.Forms package. If you’ve got others because you are working from another template, uninstall those too, but remember to note them down as you’ll likely want to re-install them once the target framework profile has been changed.
You can now go back the project properties and successfully update the target framework profile. Note that after adding Windows Universal 10.0 it may look as though it has not been added. This appears to be a UI bug but as long as there are no errors it will have worked correctly. You can confirm this by checking the TargetFrameworkProfile in the csproj file.
Now that the target framework profile has been updated, the nuget packages which were uninstalled should now be re-installed and the ADAL library should successfully install as well.
The ADAL.js library exists as an authentication solution specifically for when working against AAD as the identity provider. Unfortunately, it is currently not well maintained and is over complicated. From a user experience perspective, the implementation discussed in this post avoids the need to redirect in order to authenticate. It happens seamlessly in the background via a hidden iframe.
A great article on the OAuth grants, agnostic of implementation, can be found here.
Thanks to my colleague Paul Lawrence for writing the first iteration of this code.
This code has a dependency on jQuery, mostly just for promises. I know, old school. I expect I’ll write an es6/2016 version of this soon enough but it shouldn’t be a challenge to convert this code yourself.
As I know I’ll get comments about it if I don’t mention it, this code doesn’t send and verify a state token as part of the grant flow. This is optional as far as the OAuth specification is concerned but it should be done as an additional security measure.
Although I’m Microsoft stack developer and have only tested this with AAD as the identity provider, I believe that it should work for any identify provider that adheres to the OAuth specification for authentication. You would need to play around with the authorisation server URL as login.microsoftonline.com is specifically for authenticating to AAD. I’d love feedback on this.
By definition, the OAuth implicit flow grant does not return a refresh token. Furthermore, the access token has a short lifetime, an hour I believe, and credentials must be re-entered before additional access tokens can be obtained via the implicit flow grant. The code provided in this post handles this by returning a URL which can be used to re-authenticate when a request fails. This URL can be used behind a link or redirection could be forced to occur automatically.
The following code snippet is an example of using this implicit flow library to call into the Microsoft Graph from within the context of a SharePoint Online page.
You will need to provide an appropriate AAD app ID for your AAD app. And don’t forget that you need to enable implicit flow via the app manifest and associate the correct delegate permissions.
This code should work not only with the Microsoft Graph but also to SharePoint Online endpoints, other AAD secured resources such as Azure services or your own AAD secured and CORS enabled web API.
[See note above about identity providers other than AAD]
Here is the implicit flow library code itself.
And here is the definition of the cache functions used above. Nothing special here, this could be swapped out with any cache implementation or removed altogether if caching is truly unnecessary or a security concern.
I welcome your comments, especially from anyone who gives this a go outside of Office 365 and the Microsoft stack.
The new SharePoint Framework (SPFx) is currently in developer preview. In order to really get into it and start making great new web parts a developer needs to get a handle on TypeScript. The initial preview iteration of the SPFx shipped with very strict linting rules (tslint) and it forced (in)experienced developers to follow many best practices regarding not just typescript but es6/es2015 conventions as well. This was done by reporting linting errors as build failures as part of the Glup build chain.
Later drops of the SharePoint Framework have relaxed these linting rules but it is still less than ideal only being prompted about these issues at transpile/compile-time. The set of linting rules that is used in the build process is defined in a tslint.json file within the root config folder.
When it comes to developing SPFx web parts I have found Visual Studio Code to be great, as it is lightweight has an integrated terminal and github support and has extensions – noticeably a nice tslint extension. Unfortunately this extension does not support the JSON format nor all of the rules specified in tslint file provided by SPFx generator.
So here it is, my SPFx tslint file for use in VS Code. Just drop this file in the root of your src directory.
The following file is based on a core set of rules from SPFx Drop 2 with the incompatible rules removed and I’ve taken some liberty by adding my own preferred rules. Of course you can change these as you need, a list of the rules which the extension supports can be found here. I have also included an ‘extended’ version of the tslint file that is provided in the config folder further below.
Brag: I was invited to the SharePoint Framework Dev Kitchen last month where they held a hackathon amongst Microsoft partners in order to test an early build. I think that the SPFx is going to be excellent and I have already build a number of web parts with it. But this post isn’t really about that.
I won the hackathon with a highly configurable ‘My Documents’ style web part and received a top of the line Surface Book. Just wanted to brag about it.