Export (0) Print
Expand All

How to: Update app web components in SharePoint 2013

apps for SharePoint

Learn how to update pages, lists, content types, and other app web components in an app for SharePoint.

Be familiar with How to: Update apps for SharePoint and the prerequisites and core concepts included in it.

All of the SharePoint components that are deployed to the app web are contained in a single Web-scoped Feature in the app package. For that reason, updating these components is a matter of updating the Feature. This process has not changed since SharePoint 2010 and is documented in How to: Add Elements to an Existing Feature in the SharePoint 2010 SDK. Other articles in the Upgrading Features node may be helpful also, but consider that apps must not include custom code on the SharePoint server, so some aspects of Feature upgrading in SharePoint 2010 are not relevant to updating apps. For example, you can't use the CustomUpgradeAction element when you upgrade the Feature of an app for SharePoint.

Update the app web for the first time

The procedures in this section explain how to update content types, lists, files, and other SharePoint components in the app web.

Some of the edits you have to make to the app web Feature cannot be made with the Feature designer in Office Developer Tools for Visual Studio 2012, so you have to work with the XML file directly. Follow these steps.

To edit the Feature XML

  1. In Solution Explorer, open the FeatureName.features file. It opens in the Feature designer.

  2. Open the Manifest tab and expand Edit Options.

  3. Choose Overwrite generated XML and edit manifest in the XML editor.

  4. Choose Yes to the prompt to disable the designer.

  5. On the view that opens, choose Edit manifest in the XML editor. The FeatureName.Template.xml file opens.

Figure 1 shows these steps.

Figure 1. Opening the Feature XML editor

Steps to open the Feature XML editor
Caution note Caution

Do not add "<!-- -->" comments to the FeatureName.features file. Comments are not supported by the upgrade infrastructure and the upgrade will fail if comments are in the file. They are used in the code examples of this article only to indicate to you where your code should go.

Use the following steps to update the app web Feature.

To update the app web Feature the first time

  1. Add any new components to the Feature exactly as you would if you were creating a new app for SharePoint project.

  2. Change existing files as needed.

  3. Open the Feature XML for editing as described in the procedure To edit the Feature XML earlier in this article.

  4. Increment the Version attribute of the Feature element. We recommend that you use the same version number that you use for the app. You should even consider raising the Feature version when other components of the app are being updated, but not the app web Feature itself. The logic of the VersionRange element (which is discussed in the section Subsequent updates of the app web) is easier to manage when the app version and the Feature version are always in sync.

    Tip Tip

    Consider adding the Feature's version to the end of the Title attribute value. Doing so makes it easier to verify that the correct version is installed after a test update. See step 3 of the procedure To verify the provisioning of the app web.

  5. Don’t make any changes in the ElementManifests section of the file. This section never changes. The components referenced in this section are deployed when the Feature is activated, but the section is ignored when the Feature is updated. In later steps of this procedure, you copy some elements from this section to another section when the components referenced by the elements have changed.

  6. If they are not already present, add the following elements to the file:

    • An UpgradeActions child element in the Feature element. Do not add ReceiverAssembly or ReceiverClass attributes to the element. These have no use when you are updating an app for SharePoint. (These attributes refer to a custom assembly, which is not supported in apps for SharePoint. If you include a custom assembly in an app, SharePoint will not install the app.)

    • A VersionRange child element in the UpgradedActions element. Do not add BeginVersion or EndVersion attributes to the element. These serve no purpose when an app is being updated for the first time. Their use is discussed in the section Subsequent updates of the app web.

    • An ApplyElementManifests child element in the VersionRange element.

    At this point the file should resemble the following example.

    Important note Important

    The Office Developer Tools for Visual Studio may have copied some elements from the ElementManifests section to the ApplyElementManifests section as an illustration. Delete these. Although you may end up putting some of them back in later steps, it is easier and safer to start with an empty ApplyElementManifests section. Redundant entries for components that have not changed can have bad consequences, including possibly lengthening the update process enough that it times-out and fails.

    <Feature <!-- Some attributes omitted --> 
                   Version="2.0.0.0">
      <ElementManifests>
        <!-- ElementManifest elements omitted -->
      </ElementManifests>
      <UpgradeActions>
       <VersionRange>
         <ApplyElementManifests>
           
         </ApplyElementManifests>
       </VersionRange>
      </UpgradeActions>
    </Feature>
    
  7. For each new component that you have added to the Feature, add an ElementManifest element, as a child of the ApplyElementManifests element. Set its Location attribute to point to the element manifest file in the project (usually called Elements.xml).

  8. If the new component includes new files, such as a new JavaScript file, CSS file, or page file, add an ElementFile element for each new file as a child of the ApplyElementManifests element. Set its Location attribute to the path of the file in the project.

  9. If you have changed any components (that were in the previous version of the Feature) in a way that changes the contents of the element manifest file (usually called Elements.xml) for the component, you have to reapply this element manifest file. To do this, copy the ElementManifest element for the component that is already in the ElementManifests section of the file and paste it into the ApplyElementManifests section.

  10. If you have added a new file to an existing component, create an ElementFile element for it in the ApplyElementManifests section.

  11. If you have changed a file that is referenced in an elements manifest file, such as a Default.aspx file, but not its name or path, you still have to copy the ElementManifest element for the component from the ElementManifests section to the ApplyElementManifests section, even though the elements manifest file itself may not have changed at all. This ensures that the old version of the file is overwritten by the new version.

    Note Note
    • Do not copy any ElementFile elements from the ElementManifests section to the ApplyElementManifests section even if the file that is referenced in the ElementFile has been changed. When an element manifest is reapplied in an upgrade action, the files that it references in the app package overwrite the previous installed versions when the Feature is upgraded.

    • There is one scenario in which you may want to replace a file with a new file that has a different name or path, instead of changing the old file. See the section Replace a file in the Feature for more information.

    The following is an example of an ApplyElementManifests section. The updated app in this example includes a modified Default.aspx file that is referenced in the Pages\Elements.xml file, and it deploys three new jQuery files, each of which is referenced in the Scripts\Elements.xml file.

    <ApplyElementManifests>
      <ElementManifest Location="Pages\Elements.xml" />
      <ElementManifest Location="Scripts\Elements.xml" />
      <ElementFile Location="Scripts\jquery-3.0.0.intellisense.js" />
      <ElementFile Location="Scripts\jquery-3.0.0.js" />
      <ElementFile Location="Scripts\jquery-3.0.0.min.js" />
    </ApplyElementManifests>
    
  12. If you added a field to a content type in the Feature, add an AddContentTypeField element to the VersionRange section. Be sure to assign the correct values to the ContentTypeId and FieldId attributes. Optionally, use the PushDown attribute to specify whether the new field should be added to any derived content types. The following is an example.

    <AddContentTypeField 
      ContentTypeId="0x0101000728167cd9c94899925ba69c4af6743e"
      FieldId="{CCDD361F-A3FB-40D8-A272-3A3C858F4116}"
      PushDown="TRUE" />
    
  13. Open every element manifest file that is referenced in the ApplyElementManifests section and ensure that any File elements have a ReplaceContents attribute and that it is set to TRUE. The following is an example.

    <Module Name="Pages">
      <File Path="Pages\Default.aspx" Url="Pages/Default.aspx" ReplaceContent="TRUE" />
    </Module>
    

Replace a file in the Feature

In one scenario, you may want to replace a file in an existing component with a new file that has a different name or path, instead of changing the file. Suppose that the earlier version of the Feature contained a customizable page type, such as a Web Parts page, and suppose that a user added a Web Part to the page. All later requests for that page from that user are redirected to the customized version of the page in the content database, not the uncustomized page on the file system. If you change the file as part of an update, the user who customized the old page still sees the customized version of the old page, not the new page. To prevent this, you must replace the old file with a new one. To do this, add a MapFile element to the VersionRange section. Set the FromPath attribute to the path of the file that is being replaced, and set the ToPath attribute to the path of the replacement file. The replacement file must differ in either name or path. The effect of the MapFile element is to redirect requests for the old file to the replacement file before the underlying redirection to the content database can occur. All users see the replacement file, and users have to redo their customizations. (The replacement file should also be treated as a new file as described in the procedure To update the app web Feature the first time earlier in this article.)

Subsequent updates of the app web

When you update an app for SharePoint for the second (or third, and so on) time, you have to consider that some of your customers may not have made the previous updates. So if a user responds to the "update is available" prompt after your latest update is deployed to the organization's app catalog or to the Office Store, their instance of the app may be updated through multiple versions in a single update process. For the most part, this is exactly what should occur: you want every earlier version of the app updated to the latest version. But you do not always want every update action for the app web Feature to reoccur for every instance of the app. There are some update actions that should not occur multiple times on a given app instance. For example, if you add a field to a content type in one update, you do not want that field added again in the next update. The following procedure shows how to use the VersionRange element to control which update actions occur based on the version of the Feature that is being updated.

This procedure assumes that you have developed and tested the latest version of the app as described in the Create and debug the new version as if it were a brand new app.

To change the app web Feature on later updates

  1. Open the FeatureName.Template.xml file for editing as described in the procedure To edit the Feature XML earlier in this article, and increment the Version attribute of the Feature element. We recommend that you use the same version number for the Feature as you used for the app.

    For purposes of a continuing example, let's suppose that you previously updated the app from version 1.0.0.0 to version 2.0.0.0, and now you are updating it to version 3.0.0.0. So set the Version attribute to 3.0.0.0.

  2. Add a new VersionRange element under all existing VersionRange elements. Do not add a BeginRange or EndRange attribute to this element.

  3. Populate the VersionRange element as described in the procedure To update the app web Feature the first time earlier in this article to account for the changes that you have made in this updated version of the Feature.

  4. Now go to the previous  VersionRange element—the one you added the last time you updated the app (from 1.0.0.0 to 2.0.0.0 in the continuing example)—and add an EndRange attribute to it. You want the upgrade actions in this VersionRange to be applied to any versions of the app to which they haven't already been applied (version 1.0.0.0), but you don't want them to be reapplied to versions to which they were already applied (version 2.0.0.0). The EndRange value is exclusive, so you set it to the lowest version to which you do not want the upgrade actions applied. In the continuing example, you set it to 2.0.0.0. Your file should now resemble the following.

    <Feature <!-- Some attributes omitted --> 
                   Version="3.0.0.0">
      <ElementManifests>
        <!-- ElementManifest elements omitted -->
      </ElementManifests>
      <UpgradeActions>
        <VersionRange EndRange="2.0.0.0">
          <!--  Child elements for upgrade from 1.0.0.0 to 2.0.0.0 go here. -->
        </VersionRange>
       <VersionRange>
          <!--  Child elements for upgrade from 2.0.0.0 to 3.0.0.0 go here. -->
       </VersionRange>
      </UpgradeActions>
    </Feature>
    

    Each time that you upgrade the Feature, follow the same pattern. Add a new VersionRange for the latest update actions. Then add an EndRange element to the previous VersionRange element and set it to the previous version number. In the continuing example, the file would resemble the following for the update from 3.0.0.0 to 4.0.0.0.

    <Feature <!-- Some attributes omitted --> 
                   Version="4.0.0.0">
      <ElementManifests>
        <!-- Child elements omitted -->
      </ElementManifests>
      <UpgradeActions>
        <VersionRange EndRange="2.0.0.0">
          <!-- Child elements for upgrade from 1.0.0.0 to 2.0.0.0 go here. -->
        </VersionRange>
       <VersionRange EndRange="3.0.0.0">
          <!-- Child elements for upgrade from 2.0.0.0 to 3.0.0.0 go here. -->
       </VersionRange>
       <VersionRange>
          <!-- Child elements for upgrade from 3.0.0.0 to 4.0.0.0 go here. -->
       </VersionRange>
      </UpgradeActions>
    </Feature>
    

    Notice that the most recent VersionRange element has no BeginRange or EndRange attributes. This ensures that the upgrade actions that go into this VersionRange element are applied to all previous versions of the Feature, which is what you want because all the latest changes are referenced in this VersionRange, and none of them have already occurred for any instance of the Feature.

    Notice also that the BeginRange attribute is not used in any of the VersionRanges. This is because the default value for the BeginRange attribute is 0.0.0.0, and that is almost always the value that you want because you want all upgrade actions applied to every instance of the app that is earlier than the version that is specified in the EndRange attribute.

    Important noteImportant
    • The VersionRange element determines only which versions of the Feature the upgrades are applied to. It does not determine which versions of the app get a notification that an update is available—that is determined only by the app version number. Within 24 hours of a new version of the app being available in the organization's app catalog or the Office Store, every installed instance of the app, regardless of version, has the notification that an update is available appear on its tile in the Site Contents page.

    • The VersionRange does not affect the new version number of the newly upgraded Feature or the newly updated app. Those two numbers are always changed to the latest version number, regardless of what version range the Feature was in before the upgrade. This provides another good reason to avoid using a BeginRange attribute. The BeginRange attribute can be used to block some upgrade actions from ever occurring on some app instances. But it cannot block the Feature or app versions from being raised to the latest version. So the use of a BeginRange attribute could create a situation in which two instances of your app could have the same app version number and the same app web Feature version number, but have different components in their app webs.

Follow these steps to verify the deployment of the app web Feature and its components.

To verify the provisioning of the app web

  1. Open the Site Settings page of the host web. In the Site Collection Administration section, choose the Site hierarchy link.

  2. On the Site Hierarchy page, you see your app web listed by its URL. Do not start it. Instead, copy the URL, and use the URL in the remaining steps.

  3. Navigate to URL_of_app_web/_layouts/15/ManageFeatures.aspx and, on the Site Features page that opens, verify that the Feature is a member of the alphabetical list of Features and that its status is Active. If you added the Feature version to the Feature's title, you can also verify that the correct version is installed.

  4. If your app web Feature includes custom site columns, open URL_of_app_web/_layouts/15/mngfield.aspx and, on the Site Columns page that opens, verify that your new custom site columns are listed.

  5. If your app web Feature includes any custom content types, open URL_of_app_web/_layouts/15/mngctype.aspx and, on the Site Content Types page that opens, verify that your new content types are listed.

  6. For each custom content type, and each content type to which you have added a column, choose the link to the content type. On the Site Content Type page that opens, verify that the content type has the site columns it should have.

  7. If your app web Feature includes any list instances, open URL_of_app_web/_layouts/15/mcontent.aspx and, on the Site Libraries and Lists page that opens, verify that there is a Customize "name_of_list" link for each custom list instance.

  8. For each of these custom list instances, choose the Customize "name_of_list " link, and verify on the list settings page that the list has the expected content types and columns.

    Note Note

    If there is no Content Types section on the page, you must enable management of content types. Choose the Advanced Settings link and, on the Advanced Settings page, enable management of content types, and then choose OK. You are returned to the previous page, and there is now a list of Content Types section.

  9. Near the top of the page is the web address of the list. If you included sample items in your list instance definition, copy the address and paste it into the address bar of your browser, and then navigate to the list. Verify that the list has the sample items that you created.

Show:
© 2014 Microsoft