Azure Functions: Add a message to a storage queue after a delay

I was looking at a specific problem today dealing with Azure Functions and adding messages to storage queues: I needed my Function to add a message to an output queue in order to trigger another function, but the challenge was, the message should not get added immediately and the second queue trigger function should not fire immediately as well.

We needed a delay between the completion of the first function and execution the second queue triggered function.

A not-so-great way of achieving this would be to add a Thread.Sleep before the message is added to the output queue but we really wanted to avoid that as it would keep the function running and would not be a truly "serverless" way of doing things.

I had a look at the visibilityTimeout setting in the host.json file but turns out it is meant for configuring the delay after which a retry is made when a function fails: https://docs.microsoft.com/en-us/azure/azure-functions/functions-host-json#queues

Fortunately, Jeff Hollan on twitter suggested a nice solution for this which utilised the initialVisibilityDelay property of the CloudQueue.AddMessage function. The great thing is this works seamlessly with Azure Function output bindings so we don't have to use the SDK ourselves.

Here is a sample of how my final code looks and it works pretty great!

Hope you find this useful!

Working with SharePoint Online Hub sites using CSOM

With SharePoint Online Hub sites launched for Targeted release tenants, here is some quick code I put together to work with them using CSOM:

1) Register a Hub site, Connect a site to a Hub site, Disconnect a site from a Hub site and Unregister a Hub site:

2) Grant and Revoke specific users rights to connect sites to a Hub site:

When a Hub site is registered, it is public by default. Any user is able to connect their site to the hub site. If you want only a specific set of users to be able to connect their site to the Hub site, you can grant "Join" rights to these users:

Hope this helps!

SharePoint Framework: Calling AAD secured Azure Function on behalf of a user

Recently, after long last, the support for easily calling Azure AD secured custom APIs was released in the latest version of the SharePoint Framework (v1.4.1). Here are the details if you want to learn more: https://docs.microsoft.com/en-us/sharepoint/dev/spfx/use-aadhttpclient

In this post, let's have a look at how to secure our custom API (Azure Function) with Azure AD and then call the custom API from within a SharePoint Framework web part on behalf of the currently logged in user. We will be able to get the current user identity/claims in the custom API to know which user made the call to the Azure Function.

So let's quickly jump into how we are going to achieve this:

1) Create an Azure AD app registration

Go to Azure AD > App registrations > New application registration and create a new app registration. I am calling my app "User Details Custom API for SPFx"

By default the app registration will have the Sign in and read user profile scope on the Windows Azure Active Directory API. For the purpose of this post, those permissions are enough for us. We don't need to modify anything here right now.

Make a note of the Application ID of the app registration. This is the Client ID which we will use later.

As a subscription admin, Grant permissions to the App registration for all users so that each user does not have to do this individually:

2) Create an Azure Function App and configure it

Go to App Services > Add > Function App and create a new Azure Function App which we will use to host our Azure Function

Once the Function App is created, we need to secure it with our Azure AD app registration.

Go to Function App > Platform Features > Authentication / Authorization

In the Authentication / Authorization pane, for "Action to take when request is not authenticated" select "Log in with Azure Active Directory".

For Authentication Provider, click on Azure AD > Advanced and for Client ID, paste the Client ID (Application ID) of our Azure AD app registration we created earlier.

Click Ok and Save the Configuration.

Go to Function App > Platform Features > CORS and add the SharePoint Online domain from which your SPFx webpart will make a call to the Azure Function.

Click on Save.

3) Create the Azure Function

Now let's actually create the Azure Function which we will deploy to the Function App as our custom API.

Using Visual Studio 2017, I have created a precompiled .NET Framework Azure Function project. As we are going to use this function as an API, I have selected an Http Triggered function:

Notice that the Authorization level for the function itself is set to Anonymous. This is because we are using Azure AD at the Function App level to secure it.

All this function does is returns the claims of the current authenticated user in JSON format.

Publish the function to the Azure Function App we created earlier.

4) Create the SharePoint Framework web part

Before going ahead with this step, make sure you have the latest version of the SharePoint Framework yeoman generator (1.4.1 at the time of this writing) This page should contain all the current versions of the generator, npm and node supported by the SharePoint Framework: https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environment

Once you have all the latest packages, create the SPFx web part with yo @microsoft/sharepoint

To keep it simple, I am making it a tenant scoped solution with no JavaScript framework.

5) Request permissions for the SPFx web part

Once the SPFx web part solution is created, navigate to the config/package-solution.json file and add the webApiPermissionRequests property:

The resource will be the name of the Azure AD app registration we used to secure our Azure Function and the scope will be user_impersonation as we want to make a call on behalf of the current user.

6) Using AadHttpClient to call the custom Azure Function

Now in your SPFx webpart, include the following imports:

and the code to use the AadHttpClient to make a request to your custom Azure Function:

To display the table properly, add the following to the .scss file of your web part:

7) Installing and running the SPFx package 

Since we are going to run the SPFx solution in debug mode, we will run the commands without the --ship or --production switch. This will enable us to debug the solution locally.

Run the following commands to build and package your solution:

gulp build

gulp bundle

gulp package-solution

Start local debugging with

gulp serve --nobrowser

Now, upload the .sppkg file from the sharepoint/solution folder to the App Catalog:

Select the checkbox and Click on Deploy.

8) Granting permissions using the SPO Admin API management page

After deploying the package to the app catalog, as a SharePoint Administrator, navigate to the new SharePoint Online Admin centre and go to the API management section. You will notice the permissions we requested from the solution package can be approved from here. 

Approve the permissions before moving to the next step

9) Add web part to page

 

Now go to any modern page and add your web part to it. Since we have deployed a tenant scoped solution, no need to install it individually on each site.

This is probably my least favourite part of the process. You will need to enable pop-ups so that SPFx and the underlying ADAL.js can authenticate the current user with the custom API.

Once you have enabled the popup and refreshed the page, the web part should start displaying correctly!

The current user identity and claims coming through will be what we have sent from the Azure Function!

Hope this helps :) As always, the code from this post is available on GitHub: https://github.com/vman/spfx-azure-function-custom-api

Use Flow HTTP Webhook to call Azure Function - Send notification email after PnP provisioning

When using Site Designs and PnP for applying provisioning templates to sites, the order of events is something like this:

1. When a Communication site or an Office 365 Group connected Team site is created, a Site Design gets applied to it.
2. The Site Design contains a triggerFlow action which starts a Microsoft Flow (configured to be triggered by an http request).
3. The flow adds an item to an Azure storage queue which triggers and Azure Function.
4. The Azure Function contains the PnP template and the code to apply the template to the newly created site.

This approach is described in the guidance here: Calling the PnP provisioning engine from a site script

Now the problem with this sequence of actions is that (as of this time) they are all Asynchronous events i.e. "fire and forget". When the Site Design executes the triggerFlow action, it does not wait for the Flow to complete before showing the success screen to the user. Similarly, after the Flow adds an item to the storage queue, quite understandably, it does not wait for the triggered Azure Function to finish executing before completing its run.

In this sequence of async events, if we want to perform an action like sending a notification email after the provisioning is complete, we have the following options:

Multiple Flows:

Use an output storage queue and in the Azure Function, add an item to it when the provisioning completes. Have another Flow triggered by the output queue, which sends the email. I am not a big fan of this approach as this means managing an output queue as well as a second Flow just for sending the email notification.

Polling:

If we want to avoid creating a second Flow, another option is to use a Do Until action and poll for when messages arrive on the queue. The main drawback of this approach is that we must keep track of different instances of the Flow. If multiple users are creating sites and there are multiple messages arriving on the queue, we want to send the email only after the message of our own site arrives. This is doable using the Flow instance id but a bit too complex for my liking :)

The solution: HTTP Webhook

Fortunately, there is a nice way to handle this. Using the HTTP Webhook action, we can basically wait for the provisioning to complete before returning the control back to the Flow. Since we are in a serverless world here, the Flow will essentially pause here and "wake up" when we want it to.

To use this approach, we have to make a slight modification to the approach suggested in the Microsoft documentation. In this approach, instead of firing the Azure Function with a queue trigger, we will fire it using the HTTP Webhook action. The Function will be configured to execute on HTTP trigger i.e. when an HTTP request is made to an endpoint.

Here is an overview of actions for the Flow:

The Flow starts when the Site Design executes the triggerFlow action:

Now this is where the magic happens. The HTTP Webhook action makes a request to the Azure Function. It passes the call back url as a parameter and then waits. Whenever the Azure Function finishes executing, it is expected to make a request to the call back url. When a request will be received in the call back url, the HTTP Webhook action will finish and the Flow will resume with the data passed back from the Azure Function.

Here is the code for the Azure Function:


Now, it is only matter of parsing the data returned from the Azure function and sending the email:

This way, we can perform actions in the Flow after the PnP template has been successfully applied to the site.

Hope this was helpful!

SharePoint Online: Combine and reuse multiple site scripts in a site design

Site scripts and site designs were recently introduced in SharePoint Online/Office 365. They provide a great way to hook into the out of the box site creation dialog to apply customisation to the site being created. Here are some great articles if you want an overview of site scripts and site designs:

SharePoint site design and site script overview

Using Site Designs or PnP templates for SharePoint site provisioning

In the most basic sense, 

Site scripts are the JSON files used to define the artefacts to be created or the customisation to be applied after the site is created.

Site designs are site templates created by combining one or more site scripts. They can be assigned a title, description, preview image etc. which will be presented to the user in the 'Create new site' dialog.

In this post, let's have a look at how we can combine and re-use multiple site scripts to create site designs.

Here, I have a site script to create a document library on site creation:

Next, I have another site script to trigger a Microsoft Flow on site creation:

Now, here is a PowerShell script which will create 2 different Site Designs (templates). 

The first site design will only be configured to have the site script to create the document library.

The second site design will contain the same site script to create the document library. But in addition, it will also contain the site script to trigger a Microsoft Flow.

Once both site designs are successfully created, they will appear in the "Create a site" dialog on the SharePoint home in Office 365:

This way, you can combine and re-use multiple site scripts to create different site designs as per business requirements.

Troubleshooting:

1) Site scripts and site designs are in preview now and not meant to be used in production. They are also being gradually rolled out to Targeted Release tenants. I was only able to test them in 1 of my tenants. In all other tenants, I was getting the message: "The requested operation is part of an experimental feature that is not supported in the current environment."

2) You will need the latest version of the SharePoint Online Management Shell to get the site design cmdlets: https://www.microsoft.com/en-us/download/details.aspx?id=35588

Introducing spfx-extensions-cli: A command line tool to manage SPFx extensions

I have just published a CLI tool to view and manage SharePoint Framework extensions:
https://www.npmjs.com/package/spfx-extensions-cli

More details in the package README.

Code is available on GitHub. Feel free to play around and submit any feedback:
https://github.com/vman/spfx-extensions-cli

Simultaneously run multiple versions of the SPFx Yeoman generator with npx

This is a topic which has been discussed quite a lot since the launch of the SharePoint Framework. The SPFx Yeoman generator is recommended to be installed globally, but what if a new version is released and I want to try out the new version without uninstalling my globally installed generator? 

Waldek Mastykarz has a great post on the issue and suggests some solutions as well. Have a look at his post if you haven't already: Why you should consider installing the SharePoint Framework Yeoman generator locally

In this post, lets have a look at how we can use npx to provide a solution to this problem.

If you haven't heard about npx yet, it is the hot new member of the node ecosystem. Check out the introduction post by Kat Marchán:

Introducing npx: an npm package runner

In short, npx can be used to run npm packages directly from the command line without having to install them globally or locally.

From the intro post:

Calling npx <command> when <command> isn’t already in your $PATH will automatically install a package with that name from the npm registry for you, and invoke it. When it’s done, the installed package won’t be anywhere in your globals, so you won’t have to worry about pollution in the long-term.

This means that when we run the SharePoint Framework generator through npx, it will be as if it is running from a global install. After the SPFx solution is created, you will not find the generator installed either locally or globally. It has served it's purpose of generating us a solution and is no longer needed. 

Run different versions of the SPFx Yeoman generator in different folders: 

Now lets actually use npx to create two different SPFx solutions using two different versions of the SharePoint Framework Yeoman generator. We will use the latest version of the generator and the very first version of the generator which was part of SPFx Drop 1.

I am using the following command throughout the post to list the top level global packages:

I have done a global install for gulp already. This is to keep things simple as we only want to use npx for the SharePoint Framework generator. If we wanted to take things to the next level, we could use gulp through npx as well.

Now, let's go ahead and install npx globally:

After it's installed successfully, lets have a look at our global packages again:

As you can see, neither the SharePoint Framework generator, nor Yeoman itself is installed globally. This makes us free to use any version of the generator we want. Let's use the latest version, which at the time of this writing is 1.1.0

First, I am going to create a new folder named "latest" and navigate to it. Then run the following:

By specifying the -p (package) flag we run the yeoman (yo) and SPFx generator (@microsoft/generator-sharepoint) packages through npx. 

After that, we run the SharePoint Framework generator by running  -- yo @microsoft/sharepoint

 

Now let's run gulp serve to launch the workbench. As mentioned before, since we have already installed gulp globally, we don't have to install it again.

Now let's see the real power of npx. We will navigate to another folder and use Drop1 of the SharePoint Framework generator to create an SPFx solution.

I have created another folder called drop1. Lets navigate to it and run the following using npx:

As you have probably noticed already, the only difference in this and the previous npx command is that we are using the version numbered 0.0.65 of the generator and not the latest. This was the version of the generator when Drop 1 of the SharePoint Framework landed back in August 2016.

You will notice immediately that there are some differences in the wizard. It asks me whether to create a new folder for the solution or use the current folder. It also defaults to creating a web part and does not ask me whether I want to create an extension. This is obvious given that extensions were not part of the first drop. 

After running gulp serve, we can see the Drop 1 workbench running:

That's it! We have used two different versions of the generator to create two different solutions without having to install the generator on our machine!

Using a new version of the SPFx generator when an older version is already installed globally:

If you have been closely following the post, you know what's coming next. 

Let's say we already have a version of the generator installed globally. Now a newer version of the SPFx generator is released and we want to try it out immediately. All we have to do is use npx to run the latest version. We would be able to create a new SPFx solution with the latest generator and still keep our old generator installed globally!

The magic is described in the npx package description: 

If a full specifier is included, or if --package is used, npx will always use a freshly-installed, temporary version of the package. This can also be forced with the --ignore-existing flag.

This is good news because we want to have control over which generator version is used by npx to create our solution.

Here is how the process will look:

I already have the Drop 1 (0.0.65) version of the generator installed globally. Next, we are running npx and specifying it to use the latest version of the generator.

After the command is run, we are presented with the wizard which gives us the option of creation an SPFx extension. This option was not available with Drop 1 which means that the latest generator is being used to create our solution.

This is how we can use npx to explicitly specify the generator version and ignore the globally installed generator!

Where does npx store the packages?

If we navigate to our npm-cache folder, we will see that npx stores all the versions of the package in the cache. Here, we see that the @microsoft/sp-build-web package was used in both versions of the generator, hence both versions are being stored in the cache:

That's it! Hope you have enjoyed this post as much as I have enjoyed writing it :)