Introduction to Patterns and Practices
Recently I’ve been looking into the Office Development Patterns and Practices samples (OfficeDev/PnP). Lead by Vesa Juvonen OfficeDev/PnP is an initiative by many SharePoint developers picking up all those development tasks that keep coming back.
I got into the whole PnP approach when I saw Vesa demo the Provisioning.SubSiteCreationApp at the Evolution 2015 conference in London.
All of the examples assume a need for using CSOM or the REST API.
On github there is a large amount of examples available. This is an ever growing list of examples. All of these examples can be found in the Samples folder on the github project. I looked through all of the project names and it wasn’t obvious to me what each project did so here is a quick overview
Initially I copied the readme files form the projects but I will add more personal comments later on as I get myself familiar with these projects. This page saves me having to open each separate readme file so I thought I might as well share it with all of you.
This sample shows how to use windows Azure Active directory and the groups to authorize actions in your asp.net MVC app or Office 365 Add-In
This sample shows how you can use the Azure AD Graph API to check if a given user is member of a group.
You can find a few other useful samples in the code:
- how to get all groups
- how to get all users
- how to list all groups that a user belongs to
This scenario shows how to upload CSS and site image to the host web and how to set those to be used using CSOM. These are new properties released as part of the 2014 April CU for on-premises and they are also located in the cloud. MS online CSOM will be updated to expose these additional CSOM properties for the Web object during July 2014. Notice that you can use 2014 April CU CSOM also with Office365 to set the properties accordingly to the host web.
This sample demonstrates common tasks related on the publishing features, like how to deploy page layouts and master pages. It also shows how you can use property bag entries in the Web object to control the available page layouts and available web templates settings for the publishing sites.
This sample shows how to customize a field type with Client-Side Rendering (also called CSR, JS Link) technology in SharePoint 2013.
shows how to inject custom CSS to the host web from add-in.
Note: If you are using Office 365 or 2014 April CU for on-premises, you should not be using this approach. As part of the new API versions, AlternateCSSUrl has been added to CSOM, which should be the default option. This newer technique is demonstrated in the Branding.AlternateCSSAndSiteLogo example.
This sample shows how to assign, upload and change the used theme on the host web.
The Display Templates sample demonstrates how to use Display Templates to render a hero image and content rotator in a Content By Search Web Part. Additionally, the Display Templates target mobile devices using Responsive Web Design (RWD) and Device Channels.
Demonstrate how to update out of the box seattle.master user expirience responsive without a need to modify the master page as such, but rather to take advantage of the AlternateCssUrl property in Web level. Responsive CSS design has been done by Heather Solomon and you can read more information about the CSS details from following blog post.
- Heather Solomon (SharePoint Experts, Inc) – Making Seattle master responsive
To make sure the css is rendered correctly on hardware devices a viewport html meta tag needs to be added to the master page. This can be accomplied by using the Search Engine Optimization Settings. Again the master page doesn’t need to be edited. More details on this are covered in the following blog post.
- Stefan Bauer (n8d) – How to add viewport meta without editing the master page
The JSLink sample includes sample re-usable code which demonstrate how you can use the new Client Side Rendering techniques along with JSLink hooks to modify the rendering of List Forms and Views.
The download includes a Visual Studio 2013 solution which compiles to a SharePoint 2013 WSP Package. this includes both a set of sample re-usable frameworks for JSLink display templates, as well as various lists which demo the functionality.
Specifically functionality includes
- Rendering a single-select Taxonomy field as cascading drop-downs
- Rendering two related lookup fields as cascading Drop-Downs (single-select) or checkboxes (multi-select)
- Presenting a Google Maps interface for selecting points or areas on a map
- Sample Colour Picker with formatted display, custom editing (as drop-downs) and a sample validators
This sample shows how to connect to Office 365 and set a theme for a site.
This solution shows a method for creating a chat room within a SharePoint web part. The solution uses details from the user’s profile to identify the sender of the message and uses SignalR to push messages out to each instance of the chat room.
This sample shows how to implement handlers for the AppInstalled and AppUninstalling events that:
- Incorporate rollback logic if the handler encounters an error.
- Incorporate “already done” logic to accommodate the fact that SharePoint retries the handler up to three more times if it fails or takes more than 30 seconds to complete.
- Use the handler delegation strategy to minimize calls from the handler web service to SharePoint.
- Use the CSOM classes ExceptionHandlingScope and ConditionalScope.
This sample shows how to implement handlers for the AppInstalled and AppUninstalling events that:
- Incorporate rollback logic if the handler encounters an error.
- Incorporate “already done” logic to accommodate the fact that SharePoint retries the handler up to three more times if it fails or takes more than 30 seconds to complete
This sample shows how to bulk upload documents into a target site collection within SPO using the C# REST API.
This sample shows how to bulk update user profile properties through the use of a CSV file and automate the extraction of user attributes from a given LDAP directory with authentication.
This sample shows how to inject custom CSS to the host web using SP Add-In. For more information on this sample, please see Vesa Juvonen’s thorough blog post on the concept:
This sample shows how you can create site columns, content types and add then add the site columns to the content type. It will also explain the new localization features that have been introduced for Office 365 CSOM APIs.
For more information on this sample, please see Vesa Juvonen’s thorough blog post: https://github.com/pnp/PnP/tree/master/Samples/Core.CreateContentTypes
This sample shows how you can create site collection from console application to the Office365 MT side, upload a site template to the site collection and apply the site template to the site collection.
Notice that example template does time out pretty often when applied against Office365. Shows the pattern, but it’s recommended to use remote provisioning rather than custom site templates.
The sample shows a technique for displaying secured images in provider-hosted add-in that live in a separate domain (ex: AppWeb or MySite). This can be largely problematic when the two domains are in separate security zones as the domains will not be able to share browser tokens. The technique outlined in the sample leverages a REST Service in the provider-hosted addom to “proxy” the image delivery as a base64 encoded string instead of an absolute URL. All you need is a SharePoint access token.
This provider-hosted sample application for SharePoint demonstrates the differences, advantages, and disadvantages between different data storage patterns associated with the Add-In Model and how they are built. It also illustrates limitations associated with certain data storage components that should be considered when deciding which data storage components to use when building with the Add-In Model.
The purpose of this sample is to show the advantages and disadvantages of using different types of storage models to hold information. There are 6 different scenarios in this sample. Each scenario is supported with specialized information. The diagram in the first section in this document illustrates the different data storage models associated with these scenarios.
• Customer Dashboard • Recent Orders • Customer Service Representative Survey • Notes • Support Cases • Call Queue
Sample that shows how to use REST API to retrieve calendar events and process them in order to display them using a third party component which has features SharePoint does not such as tooltip information on when hovering over an event, or multiple calendar overlays with custom styling based on event properties, etc… Encapsulates all the logic specific to sharepoint events into file: SP.Calendar.js which other people could use in their projects to achieve similar results using their preferred framework.
This sample shows how to dynamically request permissions for an add-in from any web site using an OAuth code.
This sample shows how manage add-in part properties using embedded edit controls instead of the controls provided by the OOTB add-in part editor.
This scenario shows how an add-in can use the add-in Installed event to perform additional work in the host web, such as attaching event receivers to lists in the host web.
For more information on this scenario, see the blog post: https://github.com/pnp/PnP/tree/master/Samples/Core.EventReceivers.
This sample demonstrates how to control the external sharing settings for a site collection in office 365 MT
This sample demonstrates how to upload binary files from SharePoint Hosted App to the host web. This sample project was merged from the blog post “Deploy binary files from SharePoint Hosted App to Host Web – Stefan Bauer“. The first method shows how to upload a binary file to the host web using jquery ajax. The missing support for binary files will corrupt the uploaded file. The second method extends jQuery capabilites to support binary file reading. This method makes sure that the file won’t get corrupted.
This sample will create a SharePoint list called Events on the host web. It also contains an add-in part that renders a mini calendar that can be styled to your needs using the attached css files.
This sample demonstrates how to make modifications to quick launch and top navigation nodes as well as setting navigation inheritance.
This scenario shows the right approach for uploading files to the SharePoint using client side object model. There are few different ways to achieve this task and how to avoid the 2 MB file upload limit.
Employ the ChangeQuery object to monitor list item changes.
- Accept Url, List name, User name and password arguments.
- Check every 30 seconds to see if changes have occurred.
This sample lets you enable Social features like Rating/Likes on the List/Library. The dependency is on Publishing Feature. At the time of writing there is no method avaiable on Client SDK for .NET to set the Rating Functionality. The implementation is a result of reverse engineering of Server Side Object Model
This sample demonstrates how to perform taxonomy related operations.
This sample shows how you can create MMS Based navigation for site collection
This sample demonstrates how to Synchronize Terms across multiple term stores
The Core.ManageUserCustomAction sample shows how to manage UserCustomActions Objects using a Form interface where is possible to include/edit/delete UserCustomActions. This sample app extends the Out of the Box SharePoint Object “UserCustomAction” with a basic user interface Form with pre-filled data needed to support the object that allows Power Users to manage custom actions like “Scriptlink”, “Ribbons” and “Custom Actions” in the Hosted Site.
This sample demonstrates two basic techniques for provisioning wiki pages: creating a wiki page in a wiki library and then manipulating it.
The purpose of this sample is to show how to use the $batch query option, as defined by the OData 3.0/4.0 standard, can be used with SharePoint Online’s REST APIs and the Files and Folders APIs of Office 365.
The sample shows how to combine multiple OData operations against the SharePoint REST/OData service into a single HTTP Request/Response. The sample uses HTML, C#, and the managed code OData library in Microsoft.Data.Odata.
As of the initial release of this sample, Microsoft’s support for $batch is not compliant with the OData 3.0/4.0 standard in one respect: The REST service does not support “all or nothing” transaction protection for the operations that are included in a ChangeSet, which is a set of operations that make changes on the OData source. (Purely “read” operations; that is, operations that use the GET verb, are outside of ChangeSets although they can be included in the operations of a batch request.)
This sample shows how a high-trust SharePoint add-in can use a certificate that has been stored in the Windows Certificate Store on the Windows Server that is hosting the web application.
This sample demonstrates how to access an end-user’s OneDrive for Business site and apply custom branding to it automatically.
This sample demonstrates how to migrate documents from onpremise mysite to OneDrive for Business on Office 365.
This sample shows how to pull permissions from each site collection and site
This sample applications allows you to bulk upload user profile pictures to SharePoint Online, and edit the user profile properties to point to newly uploaded picture
A set of migration console applications used to export single and multi-valued user profile properties from an on-premises deployment and write those properties to an intermediate store. Secondly, we then update SharePoint Online Tenant via that intermediate store.
This sample shows how to perform operations on-demand with Azure WebJobs as continuously running operation, which will handle incoming requests from message queue. This can be really easily achieved with only few lines of code and is extremely powerful technique for providing asynchronous operations started by end user. Comparing this to classic server side timer jobs, this equals to the model where you use SPOneTImeSchedule class for your timer job scheduling based on end user input.
Typical use cases for long lasting asynchronous operations would be for example following.
- Complex configurations installed from the add-in to the given host web
- Complex add-in Installed operations due 30 sec time out
- Self service operations for the end users, like site collection provisioning for cloud or for on-premises with service bus usage
- Route entries or information from Office 365 to on-premises systems
- Start perform complex usage calculations or other long lasting business logic cross tenant
See exact details on the model from blog post from Vesa Juvonen
Demonstrates how to add/remove a ribbon to a SharePoint host web.
This sample shows how modify SharePoint Designer Settings using CSOM
This sample shows how to access list information in a SharePoint website from your add-in by using the cross domain library in SharePoint 2013.
This sample demonstrates how to import and export operations on search settings via a CSOM console application
Demonstrates how to control auditing settings in the site collection level using CSOM
Demonstrates how to control regional and language settings in SharePoint site level using CSOM.
Demonstration of how to write WebAPI controller that acts as proxy for SPA apps to protect access tokens, yet still allow normal request construction to occur within the client.
This scenario shows how one can use sideLoading of a Provider Hosted Application to install a SharePoint Provider Hosted Application to a site collection.
Shows how to create “remote timer job”, which could be installed to be running as a WebJob to Windows Azure or scheduled to windows scheduler for on-premises deployment.
For more information on this scenario, see the blog post: http://blogs.msdn.com/b/kaevans/archive/2014/02/26/attaching-remote-event-receivers-to-lists-in-the-host-web.aspx & http://blogs.msdn.com/b/shariq/archive/2013/12/09/simulate-timer-job-solution-for-sharepoint-2013-online-using-csom.aspx
This sample is a ready-built add-in that shows information about the current site collection with a “Site Information” custom action menu item.
The interface will load in a dialog box, showing info such as: site collection admins, storage quota & usage, the Webs count, last content modified date, sharing settings, etc. It is a useful starting point if you want to build something similar for your users.
The sample also shows how to add a custom action under the Settings menu. It makes use of the add-in Installed Event Receiver to add the custom action. For this reason it requires a publicly addressable URL if installing to Office 365, or Azure ServiceBus
This sample shows an implementation of a SharePoint Taxonomy Picker control that can be used on provider hosted SharePoint apps.
This sample shows pattern on how to handle possible SharePoint Online throttling which could be applied for CSOM, REST and web service operations in the SharePoint Online.
Notice that sample contains code which could cause performance issues for your tenant, so it is not really intended to be executed as such, rather to be used as a reference code
This sample shows deploy a pre-configured Content Editor Web Part to the Web Part Gallery of the host web.
This sample shows how to read user profile properties and how to update them. This code works for all users and all properties including simple type properties as complex types.
This solution builds on top of the UserProfile.Manipulation.CSOM.Console code sample. The business problem that it solves is that not all Azure AD properties are synced to SharePoint User Profiles, so you must cater for your own sync process for any other properties (like extended) of interest.
It aims to show a working solution that:
- you can configure which properties to read and where to write them
- authenticates & pulls data from Azure AD
- authenticates and updates all user profiles with the data from Azure AD. v1 of this sample uses the SharePointOnlineCredentials object.
Key points are that it uses the new API for updating User Profiles with CSOM (not the web services) and the use of the new Graph API 2.0 recently announced here: http://blogs.msdn.com/b/aadgraphteam/archive/2014/12/12/announcing-azure-ad-graph-api-client-library-2-0.aspx
One of the interesting demonstration elements is giving access to a SharePoint add-in to read (or write) in the Azure AD instance behind an Office 365 tenant.
Many of the concepts are described in other samples and blog posts:
- Set another user’s profile properties with CSOM (http://www.vrdmn.com/2014/11/set-another-users-profile-properties.html) by Vardhaman Deshpande
- UserProfile.Manipulation.CSOM.Console (https://github.com/OfficeDev/PnP/tree/master/Samples/UserProfile.Manipulation.CSOM.Console)
- SharePoint user profile properties now writable with CSOM (http://blogs.msdn.com/b/vesku/archive/2014/11/07/sharepoint-user-profile-properties-now-writable-with-csom.aspx) by Vesa Juvonen
- AzureAD.GroupMembership (https://github.com/OfficeDev/PnP/tree/master/Samples/AzureAD.GroupMembership) (note: this sample uses the older Graph API at the time of writing of v1 of this sample)
Note that there is no SharePoint add-in, just a console application, which you can run as a scheduled task or Azure WebJob.
The purpose of this sample is to show the best way to declaratively include a Web Part on a page in the add-in web, because the best way is not the most obvious or natural way. Developers should not simply include WebPart markup in the ASPX page itself. Doing so can cause errors when the add-in is updated.
Instead, the WebPart markup should be in the element manifest file (usually called elements.xml) for the page.
This sample shows how to use tracing and error logging in SharePoint provider hosted apps. Tracing can give you additional information about errors that occur on a production environment (where debugging usually is not a option). This sample also shows how you can log a error to SharePoint, that shows up at the add-in detail page.
Demonstrates how to use DocumentSetTemplate using CSOM.
Microsoft Excel is known for being the #1 reporting tool in the world. Regardless of what format insights are delivered in, users often desire the ability to export and work with the data in Excel. For that reason, Excel plug-ins are incredibly popular for custom and proprietary data access. Unfortunately, traditional plug-ins often cripple a user’s ability to upgrade Office. PowerPivot and Power Query have made it easy to connect to a variety of data sources without custom plug-ins. However, many data sources might be too complex for an end-user to understand and others aren’t supported at all. For these scenarios, Excel-based Apps for Office can help simplify sources and get data into Excel. This sample contains patterns for using Apps for Office to accomplish complex data access and reporting tasks. Specifically, it provides patterns for generically converting JSON into an Office.TableData object that can popular Excel.
For a more thorough overview of the solution, see the blog post: http://blogs.msdn.com/b/richard_dizeregas_blog/archive/2014/09/08/using-apps-for-excel-for-custom-data-access-and-reporting.aspx
This code sample demonstrates techniques for creating a table binding, adding rows to an existing binding, applying table styles and applying cell formatting.
This sample shows how to a secondary level of navigation under the suite bar on a OneDrive or to any other site. Typical business case would be to add custom navigation links to the OneDrive sites in hybrid situation where the end user is moving from on-premises to OneDrive for Business site and needs to find easily route back to on-prem sites
This Solution shows the output of various Office 365 API calls in a console alike output format, leveraging a WPF application, as well as in an ASP.NET MVC web application. The goal of this sample is to see the new API while keeping focus on the API calls themselves and less on the UI layer they’re hosted in.
This sample shows how to consume the Office Graph API to return the colleagues with whom you most closely work with.
This sample demonstrates how to create an add-in for Outlook which extracts data from a mail message, retrieves data from an external service and formats the data for display.
This sample demonstrates some simple caching approaches using HTML5 local storage as well as HTTP Cookies.
This sample demonstrates how to create a console add-in that provisions site collections by using the CSOM and the add-in model.
Solution demonstrating how to build asynchronous self-service site collection provisioning solution using Azure Storage Queues and Azure WebJobs.
Demonstrates how to create site collections in Office 365/SharePoint asynchronously. Requests are saved in a list within the SharePoint add-in Web. The console application included in this samples is deployed to Azure or an on-premises & scheduled.
Learn how to use a workflow to provision a SharePoint site by using the remote provisioning pattern and CSOM
Learn how to use a workflow to provision a SharePoint site by using the remote provisioning pattern and CSOM
This sample demonstrates simplest possible hybrid setup with Azure storage queues, WebJobs and Service Bus relay. This is a demonstration of hosting a provider add-in in the Azure web site, which can be used to provision new custom branded site collections to on-premises farm without any add-in infrastructure requirements to on-premises
Asynchronous provisioning of site collections in on-premises using CSOM. Process and video available from following blog post
As part of the new Client Side Object Model (CSOM) assemblies released in the SharePoint Online Client Components SDK, we now have many new capabilities and improvements. One specifically is the capability to programmatically provision OneDrive for Business sites in Office 365.
There is basically two ways to provision a user’s OneDrive for Business site, the first way is user initiated that is when the user navigates to their newsfeed, site or OneDrive links that are within the suite bar, the other is by pre-provisioning leveraging CSOM. In some cases it might not be feasible to have the user initiate the provision process. Say for example, you are migrating from an on-premises SharePoint farm or other repositories, and you don’t want to wait for the user to click a link before you start your migration.
This sample shows how to create a sandbox solution for preventing site deletion and using an add-in to deploy the solution with an application. This solution combines a solution which is still partial-trust code (by using a sandbox solution) with a new provider-hosted application. One of the challenges of current remote event receivers is that they do not support a synchronous event processing. This means that when the SiteDeleting, WebDeleting, or ListDeleting events would not be preventable the event would not be able to cancel the site from being deleted before it is deleted. This samples demonstrates:
- Development of a simple sandboxed solution using an SPSiteEventReceiver to prevent site deletion.
- Deployment of a solution to the Solution Gallery.
- Activation of a solution in the Solution gallery.
- Deactivation of a solution in the Solution gallery.
- Removal of a solution from the Solution gallery.
This sample shows how to attach remote event receivers to a list in the host web and how to use that as the initiating action to create new site collections.
This sample shows how to extend on-premises farm to support site collection creation from provider hosted add-in.
This sample shows how to provision site collections in on-premises or in Office 365 Dedicated using CSOM.
Notice that after SP2013 April CU (2014), this capability is natively supported in on-premises. This example however does show how to also expose other relevant APIs from the server, which might not be exposed by using oob methods. Check following blog article for latest guidance.
Demonstrates how to create site collections using CSOM for Office 365 from provider hosted add-in.
This solution uses so called remote provisioning pattern to provide as flexible sub site template system as possible. Old models using either site definitions, web templates or feature stapling will cause challenges with the evergreen model, meaning more frequent releases of new capability to the cloud and on-premises. Using remove provisioning pattern will initially require additional code, but since sites created using it are always based on out of the box site definitions, we don’t need to perform any updates when new capabilities are stapled to out of the box templates. This will have significantly reduce the long term maintenance costs for the solution. Additional information related on the different site provisioning options can be found from following blog posts.
- Site provisioning techniques and remote provisioning in SharePoint 2013
- SharePoint 2013 site provisioning techniques presentation video recording
This sample shows how to provision workflow template (.wsp) in on-premises or in Office 365 Dedicated using CSOM. Solution gives you insight how to migrate reusable workflow across site collection and insight how to automate process of deploying and activating reusable workflow packages by investigating solution structure and SharePoint CSOM.
This sample demonstrates how the usage of the Search API in apps and personalizing search results.
This sample shows how a Tenant Administrator can manipulate user profile properties of the users in a Tenant using Client Side Object Model (CSOM). It is using the latest SharePoint Online CSOM, which is exposing APIs also to update user profile properties. You can download the latest version of the SharePoint online client SDK from following link – http://aka.ms/spocsom
This sample shows simple operations on how to manipulate user profile using Client Side Object Model (CSOM). It is using the latest SharePoint Online CSOM, which is exposing APIs also to update user profile properties. You can download the latest version of the SharePoint online client SDK from following link – http://aka.ms/spocsom
This sample shows how to create custom activities for developing workflows.
This sample demonstrates a technique to show how to associate an add-in deployed integrated workflow to the host web.
This sample shows how to create a workflow that calls a custom web service that updates SharePoint list data.
This sample shows how to create a workflow that calls a custom web service that updates SharePoint list data via a web proxy.
This sample shows how to create a workflow that supports custom events.
This sample shows how to create a workflow that supports custom task forms and custom initiation forms.
Source code of the Office Development Pattern and Practices: https://github.com/OfficeDev/PnP/