List instance in the SharePoint Add-in model

The approach you take to create list instances is different in the new SharePoint Add-in model than it was with Full Trust Code. In a typical Full Trust Code (FTC) / Farm Solution scenario, list instances were created with declarative code and deployed via SharePoint Solutions.

In a SharePoint Add-in model scenario, the remote provisioning pattern is used to create list instances.

High-level guidelines

As a rule of a thumb, we would like to provide the following high-level guidelines to create list instances.

  • Use the remote provisioning pattern to create list instances.
  • Do not use declarative code (elements.xml) to create list instances.

Getting started

The following O365 PnP code sample and video demonstrates how to create a SharePoint Add-in that provides a user interface that allows end users to create new document libraries. It also demonstrates how to create a document library with specific configurations that collectively represent a template. In this sample you will find the code that creates a list instance.

The following video walks through the code sample.

Use the AddList method in the SharePoint CSOM to create a list instance via the remote provisioning pattern. The following code taken from the ECM.DocumentLibraries (O365 PnP Code Sample) illustrates how to do it.

private void CreateLibrary(ClientContext ctx, Library library, string associateContentTypeID)
    if (!ctx.Web.ListExists(library.Title))
      // Create List Instance
        ctx.Web.AddList(ListTemplateType.DocumentLibrary, library.Title, false);
        List _list = ctx.Web.GetListByTitle(library.Title);

      //Set Description
        _list.Description = library.Description;

      //Turn on versioning
        if(library.VerisioningEnabled) {
          _list.EnableVersioning = true;

    //Turn on Content Types
        _list.ContentTypesEnabled = true;

      //Add Content Type to List
        ctx.Web.AddContentTypeToListById(library.Title, associateContentTypeID, true);

        //Remove the default Document Content Type


The following code sample illustrates how to create a list instance with the SharePoint REST API. This sample comes from the Lists and list items REST API reference (MSDN Article)

  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true, 'BaseTemplate': 100,
    'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test title' }",
  headers: { "content-type": "application/json;odata=verbose" },
  success: successHandler,
  error: errorHandler

PnP samples

Applies to

  • Office 365 Multi Tenant (MT)
  • Office 365 Dedicated (D) partly
  • SharePoint 2013 on-premises – partly

Patterns for dedicated and on-premises are identical with SharePoint Add-in model techniques, but there are differences on the possible technologies that can be used.