SPFx packaging: Sharing code between many web parts or extensions

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.

SPFx config.json, multiple web parts will be packaged as a single bundle as part of a single package

Terminology

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.

Just do it

So take my word for it, add all your SPFx components to a single package and create multi-component bundles. To add additional web parts to an existing project just run the Yeoman generator again in the same folder location. Elio Struyf has a post about multi-component bundles and I’m sure that there will be official guidance release very shortly.

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?

  1. You can no longer install or upgrade components individually. (However, the new site collection scoped app catalog may assist with this.)
  2. 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.
  3. 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.

  • Sharing code between SPFx components is trivial. Sharing code between packages is hard.
  • 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.

And finally…

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.

Paul.

Ignite 2017 Updates Webinar

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.

Ignite 2017 banner image

You can view the webinar here: Harness the power of Office 365

I discuss

  • Required information fields
  • Files that need attention view
  • Bulk update of file metadata
  • Metadata prompt on file upload
  • Filter panel updates
  • Improving support for large lists and libraries
  • Column formatters
  • Hub sites
  • New Yammer web part
  • Custom modern themes
  • Site designs
  • Multi-geo
  • Groupify – create Office 365 groups from existing team sites
  • Group naming policies and management
  • Microsoft Teams Admin Centre
  • Microsoft Teams data storage and information protection

Ignite 2017: Recommend viewing:

Hope this helps you get up to date in record time!

Paul.

A history of extensibility in SharePoint and how to choose a model

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.

Check it out here: A history of extensibility in SharePoint and how Fresh chose a model

SharePoint extensibility model, Generic image

Office 365 CDN – Some Notes and Sample Scripts

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.

Private CDN with auto-rewrite
Private CDN with auto-rewrite. Image credit to Microsoft (https://dev.office.com/blogs/general-availability-of-office-365-cdn)

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).
  • If all users are located in the same region as the Office 365 tenant, turning on the CDN may reduce performance due to CDN priming (replication of files to the CDN) and will complicate updates to files which are replicated (e.g. JavaScript in the Style Library).
  • Search web parts must be configured for ‘Loading Behaviour’ – ‘Sync option: Issue query from the server’ in order for the auto rewrite of CDN hosted files to occur. This is true for display templates as well as the value of the PublishingImage managed property

Office 365 CDN PowerShell Samples

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.

Calling the PowerShell functions:

$cdnType = "Private" # Private or Public
$serverRelSiteCollectionUrl = "/sites/mysite" # site collection URL or * for all site collections

Authenticate-PowerShell

Set-CdnConfiguration $serverRelSiteCollectionUrl $cdnType

#Remove-CdnConfiguration $cdnType # This removes all origins but the CDN is still enabled
#Set-SPOTenantCdnEnabled -CdnType $cdnType -Enable $false # This disables the CDN

The PowerShell functions:

Function Authenticate-PowerShell() {
	[string]$tenantUrl = "https://TENANT-admin.sharepoint.com"
	[string]$adminUsername = "USER@TENANT.onmicrosoft.com"
	[string]$adminPassword = "PASSWORD"

	# Ensure module is loaded
	if ((Get-Module Microsoft.Online.SharePoint.PowerShell).Count -eq 0) {
		Import-Module Microsoft.Online.SharePoint.PowerShell -DisableNameChecking
	}

	$secureAdminPassword = $(convertto-securestring $adminPassword -asplaintext -force)
	$cred = New-Object -TypeName System.Management.Automation.PSCredential -argumentlist $adminUsername, $secureAdminPassword
	Connect-SPOService -Url $tenantUrl -credential $cred
}

Function Set-CdnConfiguration($serverRelSiteCollectionUrl, $cdnType){
    #LogWaiting "Configuring CDN"
    #LogInfo ""

    $fileTypes = "GIF,ICO,JPEG,JPG,JS,PNG,CSS,EOT,SCG,TTF,WOFF"
    $cdnOrigins = @(
        "$serverRelSiteCollectionUrl/_catalogs/masterpage", 
        "$serverRelSiteCollectionUrl/style library",  
        "$serverRelSiteCollectionUrl/sitecollectionimages",
        "$serverRelSiteCollectionUrl/publishingimages"#,
        #"$serverRelSiteCollectionUrl/news/publishingimages"
    )

    # Enable cdn WITHOUT default origins
    $supressOutput = Set-SPOTenantCdnEnabled -CdnType $cdnType -Enable $true -NoDefaultOrigins -Confirm:$false

    # Configure cdn origins (incl ensure default origins)
    Ensure-CdnOrigin $cdnType $cdnOrigins

    # Extend list of file types
    $supressOutput = Set-SPOTenantCdnPolicy -CdnType $cdnType -PolicyType IncludeFileExtensions -PolicyValue $fileTypes

    #LogSuccess "done"

    # Print status
    Get-SPOTenantCdnOrigins -CdnType $cdnType
}

Function Ensure-CdnOrigin($cdnType, $originUrls){
  $originUrls | ForEach {
    $oUrl = $_
    try {
      #LogWaiting "Adding origin: $oUrl"
      $supressOutput = Add-SPOTenantCdnOrigin -CdnType $cdnType -OriginUrl $oUrl -Confirm:$false
    }
    catch {
      if($Error[0].Exception.ToString().Contains("The library is already registered as a CDN origin")) {
        # aleady present, do nothing
      }
      else {
        #LogError $Error[0]
        Exit
      }
    }
    #LogSuccess "done"
  }
}

Function Remove-CdnConfiguration($cdnType){
	(Get-SPOTenantCdnOrigins -CdnType $cdnType)	| ForEach { $_ | ForEach { $supress = Remove-SPOTenantCdnOrigin -CdnType $cdnType -OriginUrl $_ -Confirm:$false }}
}

Paul.

OAuth On-Behalf-Of Flow: Getting a user access token without user interaction. Includes ADAL sample.

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.

Using the on-behalf-of flow to access a resource via a middle tier API

Some background

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.

    1. 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
    2. 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
    3. 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.
Before and after the app registrations are associated. Note how ‘Access Mobile App Backend’ is no longer present and instead is expanded to show the individual permissions required by that app.

Access Token Broker code

The following code is a .NET example of how to use the Active Directory Authentication Library (ADAL) to achieve the On-Behalf-Of flow.

Credits and further reading

This GitHub project was a very useful resource and a recommended starting point:
https://github.com/Azure-Samples/active-directory-dotnet-webapi-onbehalfof-ca

Microsoft docs OAuth 2.0 On-Behalf-Of flow
https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-on-behalf-of

OAuth 2.0 specification
https://tools.ietf.org/html/rfc6749

Redis Token Cache example
https://blogs.msdn.microsoft.com/mrochon/2016/09/19/using-redis-as-adal-token-cache/

Vardhaman Deshpande – always helpful
http://www.vrdmn.com/

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.

Paul.

Excuting JS in an RSS Viewer web part in SharePoint

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.

<img style='display:none' src='#' onerror='console.log("boo!")' />

If you are using SharePoint 2010 check this out:
https://sharepoint.stackexchange.com/questions/9720/calling-javascript-within-xsl-after-transformation-in-rss-web-part

Paul.

Xamarin and ADAL: Could not install package Microsoft.IdentityModel. Clients.ActiveDirectory

When starting a new Cross Platform App with Xamarin.Forms you may find yourself needing to integrate the Active Directory Authentication Library (ADAL) with your Portable Class Library (PCL). This is most easily done using nuget.

Using nuget to add the ADAL package
Using nuget to add the ADAL package

The error

However, when doing this you may have encountered the following error:

Failing to add the ADAL package
Failing to add the ADAL package

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.

Changing the target frameworks for a PCL
Changing the target frameworks for a PCL

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:

Exisitng nuget packages prevent changing the target framework profile
Exisitng nuget packages prevent changing the target framework profile

The resolution

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.

Unistall any nuget packages on the PCL
Unistall any nuget packages on the PCL

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.

ADAL Package has installed successfully
ADAL Package has installed successfully!

Paul.

OAuth Implicit Flow in JS without ADAL.js

This post provides a lightweight implementation of the OAuth implicit flow grant for obtaining an access token. Implicit flow is appropriate when the current user is authenticated to a common identity provider (e.g. Azure Active Directory a.k.a AAD) and the client (the environment requesting the token) is not secure. A great example of this is making a call to the Microsoft Graph from a page in SharePoint Online using only JavaScript.

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. EDIT: ADAL.js has been updated multiple times since this post was first written and I would recommend using it. 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.

Azure Active Directory
Azure Active Directory
  • 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]

var aadAppClientId = "8BE5AA0E-F900-4BDF-A7CF-71B3CC53B78E";
var resource = "https://graph.microsoft.com"
var query = "/v1.0/me/events";
var tokenFactory = new CC.CORE.Adal.AppTokenFactory(aadAppClientId, resource);
tokenFactory.ExecuteQuery(query)
.done(function (response) {
	// Success!
})
.fail(function (response) {
	// NOTE: Provide a link to renew an expired or yet to be approved session:
	// "Sorry, your session has expired or requires your approval. 
	// <div><a href='" + response.authorizeUrl + "'>Click here to sign in</a></div>";
});

Here is the implicit flow library code itself.

var CC = CC || {};
CC.CORE = CC.CORE || {};

CC.CORE.Log = function (errMsg) {
    // console.log is undefined in IE10 and earlier unless in debug mode, so must check for it
    if (typeof window.console === "object" && typeof console.log === "function") {
        console.log(errMsg);
    }
};

CC.CORE.Adal = (function () {
    "use strict";

    var appTokenFactory = function (aadAppClientId, resource) {
        // redirectUrl is the URL which the iframe will redirect to once auth occurs.
        // we use blank.gif as it is a very low payload
        var redirectUrl = _spPageContextInfo.webAbsoluteUrl + "/_layouts/images/blank.gif";

        // NOTE on security: include the userId in the cache key to prevent the case where a user logs out but
        // leaves the tab open and a new user logs in on the same tab. The first user's calender
        // would be returned if we didn't associate the cache key with the current user.
        var cacheKey = "candc_cache_adal_" + _spPageContextInfo.userId + "_" + aadAppClientId + "_" + resource;

        this.params = {
            clientId: aadAppClientId,
            redirectUrl: redirectUrl,
            resource: resource,
            cacheKey: cacheKey
        };

        var getAuthorizeUri = function (params, redirectUrl) {
            var authUri = "https://login.microsoftonline.com/common/oauth2/authorize" +
                            "?client_id=" + params.clientId +
                            "&response_type=token" +
                            "&redirect_uri=" + encodeURIComponent(redirectUrl) +
                            "&resource=" + encodeURIComponent(params.resource);
            return authUri;
        };

		var getQueryStringParameterByName = function (name, url) {
			name = name.replace(/[\[\]]/g, "\\$&");
			var regex = new RegExp("[?&#]" + name + "(=([^&#]*)|&|#|$)");
			var results = regex.exec(url);
			if (!results) return null;
			if (!results[2]) return '';
			return decodeURIComponent(results[2].replace(/\+/g, " "));
		};
		
        // create iframe, set its href, set listener for when loaded
        // to parse the query string. Deferred returns upon parse of query string in iframe.
        var acquirePassiveToken = function (params) {
            var deferred = jQuery.Deferred();

            // create iframe and inject into dom
            var iframe = jQuery("<iframe />").attr({
                width: 1,
                height: 1,
                src: getAuthorizeUri(params, params.redirectUrl)
            })
            jQuery(document.body).append(iframe);

            // bind event handler to iframe for parse query string on load
            iframe.on("load", function (iframeData) {
                parseAccessTokenFromIframe(iframeData, deferred);
            });

            return deferred.promise();
        };

        // handle iframe once it has loaded
        var parseAccessTokenFromIframe = function (iframeData, deferred) {
            // read the iframe href
            var frameHref = "";
            try {
                // this will throw a cross-domain error for any issue other than success
                // as the iframe will diplay the error on the login.microsoft domain
                frameHref = iframeData.currentTarget.contentWindow.location.href;
            }
            catch (error) {
                deferred.reject(error);
                return;
            }

            // parse iframe query string parameters
            var accessToken = getQueryStringParameterByName("access_token", frameHref);
            var expiresInSeconds = getQueryStringParameterByName("expires_in", frameHref);

            // delete the iframe, and event handler.
            var iframe = jQuery(iframeData.currentTarget);
            iframe.remove();

            // resolve promise
            deferred.resolve({
                accessToken: accessToken,
                expiresInSeconds: expiresInSeconds
            });
        };

        // get the most recent token from the cache, or if not available,
        // fetch a new token via iframe
        var getToken = function (params) {
            var deferred = jQuery.Deferred();
            
            // check for cached token
            var tokenFromCache = CC.CORE.Cache.Get(params.cacheKey);
            if (!tokenFromCache) {
                // fetch token via iframe
                acquirePassiveToken(params)
                .done(function (tokenFromIframe) {
                    CC.CORE.Log("ADAL: Fetched token from iframe.");
                    // expire cache a minute before token expires to be safe
                    var cacheTimeout = (tokenFromIframe.expiresInSeconds - 60) * 1000;
                    CC.CORE.Cache.Set(params.cacheKey, tokenFromIframe, cacheTimeout);
                    // resolve the promise
                    deferred.resolve(tokenFromIframe);
                })
                .fail(function (error) {
                    // Logs when rejection is caught
                    deferred.reject(error);
                });
            }
            else {
                CC.CORE.Log("ADAL: Fetched token from cache.");
                // resolve the promise
                deferred.resolve(tokenFromCache);
            }
            return deferred.promise();
        };

        this.ExecuteQuery = function (query, additionalHeaders) {
            var deferred = jQuery.Deferred();
            var params = this.params;
            // get token from cache or via iframe
            getToken(params)
            .done(function (token) {
                // submit request with token in header
                var ajaxHeaders = {
                    'Authorization': 'Bearer ' + token.accessToken
                };
                if (typeof additionalHeaders === "object") {
                    jQuery.extend(ajaxHeaders, additionalHeaders);
                }
                jQuery.ajax({
                    type: "GET",
                    url: params.resource + query,
                    headers: ajaxHeaders
                }).done(function (response) {
                    deferred.resolve(response);
                }).fail(function (error) {
                    deferred.reject({
                        error: error
                    });
                });
            })
            .fail(function (error) {
                CC.CORE.Log('ADAL error occurred: ' + error);
                deferred.reject({
                    error: error,
                    authorizeUrl: getAuthorizeUri(params, window.location.href)
                });
            });
            return deferred.promise();
        };
    };

    return {
        AppTokenFactory: appTokenFactory
    };

})(jQuery);

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.

var CC = CC || {};
CC.CORE = CC.CORE || {};

CC.CORE.Cache = (function () {
    var defaultCacheExpiry = 15 * 60 * 1000; // default is 15 minutes
	var aMinuteInMs = (1000 * 60);
	var anHourInMs = aMinuteInMs * 60;
	
    var getCacheObject = function () {
        // Using session storage rather than local storage as caching benefit
        // is minimal so would rather have an easy way to reset it.
        return window.sessionStorage;
    };

    var isSupportStorage = function () {
        var cacheObj = getCacheObject();
        var supportsStorage = cacheObj && JSON && typeof JSON.parse === "function" && typeof JSON.stringify === "function";
        if (supportsStorage) {
            // Check for dodgy behaviour from iOS Safari in private browsing mode
            try {
                var testKey = "candc-cache-isSupportStorage-testKey";
                cacheObj[testKey] = "1";
                cacheObj.removeItem(testKey);
                return true;
            }
            catch (ex) {
                // Private browsing mode in iOS Safari, or possible full cache
            }
        }
        CC.CORE.Log("Browser does not support caching");
        return false;
    };

    var getExpiryKey = function (key) {
        return key + "_expiry";
    };

    var isCacheExpired = function (key) {
        var cacheExpiryString = getCacheObject()[getExpiryKey(key)];
        if (typeof cacheExpiryString === "string" && cacheExpiryString.length > 0) {
            var cacheExpiryInt = parseInt(cacheExpiryString);
            if (cacheExpiryInt > (new Date()).getTime()) {
                return false;
            }
        }
        return true;
    };

    var get = function (key) {
        if (isSupportStorage()) {
            if (!isCacheExpired(key)) {
                var valueString = getCacheObject()[key];
                if (typeof valueString === "string") {
                    CC.CORE.Log("Got from cache at key: " + key);
                    if (valueString.indexOf("{") === 0 || valueString.indexOf("[") === 0) {
                        var valueObj = JSON.parse(valueString);
                        return valueObj;
                    }
                    else {
                        return valueString;
                    }
                }
            }
            else {
                // remove expired entries?
                // not required as we will almost always be refreshing the cache
                // at this time
            }
        }
        return null;
    };

    var set = function (key, valueObj, validityPeriodMs) {
        var didSetInCache = false;
        if (isSupportStorage()) {
            // Get value as a string
            var cacheValue = undefined;
            if (valueObj === null || valueObj === undefined) {
                cacheValue = null;
            }
            else if (typeof valueObj === "object") {
                cacheValue = JSON.stringify(valueObj);
            }
            else if (typeof valueObj.toString === "function") {
                cacheValue = valueObj.toString();
            }
            else {
                alert("Cannot cache type: " + typeof valueObj);
            }

            // Cache value if it is valid
            if (cacheValue !== undefined) {
                // Cache value
                getCacheObject()[key] = cacheValue;
                // Ensure valid expiry period
                if (typeof validityPeriodMs !== "number" || validityPeriodMs < 1) {
                    validityPeriodMs = defaultCacheExpiry;
                }
                // Cache expiry
                getCacheObject()[getExpiryKey(key)] = ((new Date()).getTime() + validityPeriodMs).toString();
                CC.CORE.Log("Set in cache at key: " + key);
                didSetInCache = true;
            }
        }
        return didSetInCache;
    };

    var clear = function (key) {
        var cache = getCacheObject();
        cache.removeItem(key);
        cache.removeItem(getExpiryKey(key));
    };

    return {
        Get: get,
        Set: set,
        Clear: clear,
        IsSupportStorage: isSupportStorage,
        Timeout: {
            VeryShort: (aMinuteInMs * 1),
            Default: (anHourInMs * 2),
            VeryLong: (anHourInMs * 72),
        }
    };
})();

I welcome your comments, especially from anyone who gives this a go outside of Office 365 and the Microsoft stack.

Paul.

tslint, VS Code, and the SharePoint Framework

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.

The tslint file that is provided by the SPFx generator
The tslint file that is provided by the SPFx generator

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.

The TSLint VS Code extension
The TSLint VS Code extension

So here it is, my SPFx tslint file for use in VS Code. Just drop this file in the root of your src directory.

Add this tslint file to the root of the src folder
Add this tslint file to the root of the src folder

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.

tslint.json in the src folder:

tslint.json in the config folder:

Paul.

SharePoint Framework Dev Kitchen Winner

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.

That's me getting awarded a Surface Book by Dan Kogan of MSFT.
That’s me getting awarded a Surface Book by Dan Kogan of MSFT.

Paul.

Office 365 and Azure, still working on it …