Master Pages

General Notes

Custom master pages are a very commonly used customization in FTC solutions. However, when transforming to the add-in model it is important to question if a custom masterpage is really required or if the functionality can be provided through other means.

In SharePoint Online, the default masterpage (for instance seattle.master or oslo.master) is an artifact that at times will be updated on the farm by Microsoft. This means that you have no real control over the file and when changes are being implemented. In effect you will be playing entering a game of catch-up as a developer and it is strongly recommended to not modify the out of the box masterpages.

You can decide to implement a custom masterpage, but while this is a technically valid choice one has to be aware of the implications. A custom masterpage references controls (for instance the suitebar) that can be, and most likely, will be updated by Microsoft. This means that a control change can affect your functionality, regardless if you are using a custom masterpage or not. For instance, removing the suitebar might affect the fact that Microsoft can introduce new functionlity through the suitebar, resulting in a degraded experience for your users.

A better and more sustainable approach would be to implement your required changes using the add-in model, utilizing artifacts like CSS files and JavaScript files to modify the out of the box masterpages. Those artifacts can be added to the site through Custom Actions.

Readiness

Analyze your solution for masterpages and consider carefully if the functionality they provide is really needed. Consider going for other means of provisioning branding changes, by using CSS and JavaScript files.

Transformation

The code examples do not set the MasterPage url property of the masterpage; the files are just uploaded to the correct location and properties are set on the file to designate it as a masterpage.