Few years ago, I have posted master list of SharePoint 2010 custom development best practices which was focused on the full trust and sandbox SharePoint customization models. To date, it’s been one of the most popular articles on this site.
Over the last year, as I have been leading few SharePoint intranet implementations, I have compiled list of best practices for modern SharePoint development which would be applicable to SharePoint 2013 on-premises, SharePoint 2016 on-premises, and SharePoint Online. This article lists various best practices I have applied and can be enforced in the team based SharePoint custom development.
- Customize for Cloud in Mind – Plan to write customization for future upgrade to SharePoint Online even though you have invested in SharePoint On-premises as of now. Be cloud-ready even though you are on on-premises.
- Avoid Full Trust Model – Avoid Full trust code model (aka features and solutions framework). No code should be deployed to the SharePoint servers. Avoid IISReset and deployment downtime. Plan to use add-ins model remote provisioning approach rather than features and solutions framework.
- Avoid Sandbox Model – Avoid both declarative and code based sandbox solutions model even though declarative model is supported by Microsoft as of now. You never know when Microsoft shuts down Sandbox code service in the Office 365. Plan to use add-ins model remote provisioning approach rather than features and solutions framework.
- Use Office 365 Patterns and Practices – You must have heard about this unless you live under the rock. Plan to use Office 365 PnP Github project for source code and Nuget packages to reference from your projects to use Office 365 patterns and practices framework which contains open source patterns to replace existing full trust model functionalities. It is important to note that even though PnP is focused on Office 365, it can be tweaked to use for SharePoint On-Premises. This is must have in SharePoint developer’s armory.
- SharePoint Artifacts Provisioning Approach – Provider hosted add-ins vs Console Applications vs PowerShell – Plan to use provider hosted add-ins or console applications remote provisioning approach to deploy common SharePoint artifacts like custom columns, content types, list instances, web parts, master pages, or page layouts which we used to deploy using Full Trust or Sandbox feature schema model. This is code based approach to deploy SharePoint artifacts from remote server using CSOM APIs. As far as either using Provider hosted add-ins model vs console applications, my personal preference would be console applications to deploy artifacts which would lessen the overhead of Provider hosted add-in infrastructure. Additionally, Office 365 PnP team has additional approaches like PowerShell to deploy artifacts remotely.
- Site Provisioning Approach – Plan to avoid any provisioning approaches introduced during SharePoint 2010 and earlier including Save as Site Template, Site Definitions, Web Templates, or full trust code based models. Best way to approach site provisioning is using remote provisioning code based model (provider hosted add-in or console applications) which would allow you select any OOB or predefined site templates for base site creation and apply additional features or provision artifacts as necessary to flush out fully functional sites.
- SharePoint Hosted vs Provider Hosted Add-ins Model – My main criteria here is whether you will require server side code or not. If you won’t and can get away with HTML, JS, CSS, REST/JSOM client side approach, plan to use SharePoint hosted model. There are many patterns introduced in Office 365 PnP for remote provisioning will require provider hosted add-in model.
- Provider Hosted Add-in Model vs ASP.NET standalone applications for SharePoint On-premises – For the full blown custom applications like timesheet or dashboard, it would make sense to avoid SharePoint as container for application entry point. Depending on your need, it may make sense to have standalone ASP.NET application if you can get away with complex certificate based High trust infrastructure to have SharePoint access token to access SharePoint APIs. Otherwise, plan to use Provider hosted Add-in model approach for the standalone applications to use the benefits of SharePoint security model and high trust authorization tokens. My personal preference here to use Provider Hosted Model to make security configuration easier.
- Provider Hosted Add-in Model vs Office 365 Apps/ASP.NET standalone applications for SharePoint Online – For the full blown custom applications like timesheet or dashboard, it would make sense to avoid SharePoint as container for application entry point. Depending on your need, it may make sense to have standalone ASP.NET applications/Office 365 Apps hosted in Azure using ADAL API to authenticate against SharePoint online and Office 365 APIs to build custom standalone applications rather than provider hosted model. Additionally, you can make Office 365 Apps available through Office 365 App Launcher. My personal preference here to use Azure Standalone applications with ADAL APIs.
- High Trust vs Low Trust Provider Hosted Add-in Model – If you have 100% full investment on the on-premises, you have no other choice but apply High Trust provider hosted add-in model for the remote provisioning, custom widgets or stand-alone application. If you have invested or planning to invest in cloud and afford hosting customization in Azure, it would make sense to start with Low Trust provider hosted model for both SharePoint on-premises and SharePoint online.
- Custom Master Pages in SharePoint On-Premises vs SharePoint Online – This is extremely controversial guideline from the Office365 PnP team. PnP best practices are around avoiding custom master pages where Microsoft may push out future upgrades to OOB master pages which may not exist in your custom master pages which further break the application customization. I am not in 100% agreement with one law to rule them all. My take here is it depends. Unfortunately there are many scenarios like publishing intranets may require branding where you can’t avoid custom master pages. If you are branding in SharePoint Online, plan to avoid custom master pages if you can get away with themes or other UI approaches where you can alter the page layouts on fly. If you can’t avoid custom master pages, plan to document what changes have made in custom master pages and be ready to make future changes in master pages applied by Microsoft. If you have SharePoint On-premises, you have full control over the upgrade and testing any new funtionalities introduced by the Microsoft. Having custom master pages in the SharePoint on-premises don’t have same risk or urgency as SharePoint Online where you have no control over upgraded features pushed out without validation.
- SharePoint HTML Tag IDs References in SharePoint On-Premises vs SharePoint Online – This is much similar as Master Pages. Plan to avoid referencing HTML Tags with IDs in your client side code especially in the SharePoint Online. Due to any future update in SharePoint Online may change HTML IDs, it’s safe to avoid them all together. SharePoint On-premises story is little bit different since organizations have full control over their upgrade timeline and enough time to test in the staging environment. Even though risk is lower especially if you document them, I would still avoid referencing HTML IDs on the on-premises as well.
- REST vs CSOM – Plan to use REST over CSOM while retrieving SharePoint data from custom applications or web parts. REST is lightweight even if its chatty and provides faster performance in most cases especially when you are waiting for sp.js to load to make SharePoint calls.
- REST Query best practices – This is classic SQL days best practice. Query only what you need. Specify only fields you would need in your REST and CSOM calls.
- App Script Part Pattern for Responsive Sites – This is best of both worlds mentioned above. Plan to use App Script Part pattern rather than standard Add-in model App Parts for responsive sites. App Script Part is nothing but script editor web part deployed by Add-in model. Since App Script part is based on HTML, CSS, and JS, it’s easy to make it responsive rather than App Parts which are relying on unresponsive IFrame technologies. You can learn further here.
- JS Link to Alter Lists UI – This feature introduced in the SharePoint 2013 to alter how list data or list forms displayed without any server side code changes. This is must have in developers armory. Look out for Wes Preston’s blog or Office 365 PnP for detailed samples.
- Avoid Suite Bar customization in SharePoint Online – This is part of hard lessons learned by many organizations over the last few years. As Microsoft slowly and slowly standardized the Office 365 suite bar, it’s increasingly isolated from SharePoint Online codebase. Plan to avoid any customization to avoid runtime errors due to any future Microsoft design changes, rather use Office 365 themes to customize.
- Standardize Provider Hosted High-Trust Certs and Registered Add-in IDs in a Team Based Development – Standardize Apps cert location, password, app ids in multi-developer team environment to avoid overwriting web.config while checking in and out from the source control envrionment. In a team based development, it is common to have developers with their individual SharePoint VM instances. Since High-trust code base requires certificate location and password for add-in tokens, plan to have all developer high trust certs with same name, same password, and same location to avoid multiple AppWeb web.config files for each developers. In addition, plan to have same add-in registration IDs (App Secret can be different since it’s not used by TokenHelper class) to avoid different AppWeb web.config files for each developers. Usually best practice should be first developer generates AppIDs and pass that information to the other developers to ensure web.config files are same for all developers.
- Use High Trust Certificate Serial Number for the Production Environment – Plan to use certificate serial number for the production high trust token helper rather than visual studio generated certificate location and password information. It isn’t a good idea to have a certificate downloaded to the servers and password stored in the web.config in the production environment. It’s OK to be dependent on VS tokenhelper class for certificate location based authorization in the development or staging environment. You should rather change your TokenHelper code to look up high trust certificate using serial number for the SharePoint access tokens in the production release. Plan to use Technet article for the code and how to publish provider hosted high-trust add-ins in the production with the best practice.
- Avoid Collaboration and OneDrive for Business Sites Branding – Avoid applying custom master pages and branding on collaboration and OneDrive for Business sites. Major use case for these sites are real-time file collaboration and usually there are no need for file collaboration branding. You may apply organization logo or custom theme to personalize environment but there are no need for full blown branding which usually requires for the intranets or publishing sites.
- Must have CodePlex Tools
- SharePoint Manager 2013 – Plan to install SharePoint Manager 2013 from the codeplex on your SharePoint developer VM. It is a SharePoint object model explorer and enables you to browse every site properties on the local farm by browsing through SharePoint Server Side Internals.(http://spm.codeplex.com/)
- SharePoint Client Browser for SharePoint Online and SharePoint On-premises – Plan to install SharePoint client browser on your machine to browse site properties without having dependent on the SharePoint VM. This tool can be installed on any machine and allows you to learn SharerPoint internals using client APIs. (https://spcb.codeplex.com/)
- SharePoint 2013 Search Query Tool – Allows you to validate and debug search queries against the SharePoint 2013 Search REST API. This is incresingly important as we build custom rollup applications using Content Search Web Parts. (https://sp2013searchtool.codeplex.com/)
I will continue update this article based on lessons I will learn and new guidelines recommended by Microsoft and Community. In addition to this, please plan to follow Office 365 Patterns and Practices and brilliant Vesa for latest guidelines.
Last but not least, please let me know if I have missed any of your best practices or if you aren’t agree on any of these best practices especially my take on custom master pages. Enjoy!!!