Step 2: Create Cache Subscriptions (*Subscription.xml)

  • Article

A cache subscription file is an XML file (*Subscription.xml) that defines which external content types in the BDC model to cache, which queries in the model to use to populate the data in the cache, and how frequently to refresh external items in the cache.

Applies to: SharePoint Server 2010

The cache subscription file is automatically generated by Microsoft Business Connectivity Services (BCS) during deployment of a simple solution. However, for an intermediate Outlook declarative solution, you must create the Subscription.xml file. The file follows a very simple schema and is easy to create, and the SDK makes it even easier by providing a template and a tool to use.

In this scenario, there are two external content types, Customer and Order, which require you to create two subscription files, CustomerSubscription.xml and OrderHeaderSubscription.xml. You can use the template provided in the SDK or the BCS Artifact Generator Tool to create both.

Note

Because the AdventureWorks sample database contains more than 2,000 customers, the sample Web service returns only the top 1,000 customer rows to keep the amount of data coming into the client small and manageable. Therefore, in this scenario, the related orders for only these 1,000 customers are returned, instead of the entire list of orders. A subscription association in this sample is defined to populate the cache with the related orders of the 1,000 customers. You can also consider using a BulkAssociationNavigator method instance to improve performance.

Prerequisites

Step 1: Create the BDC Model (Metadata.bdcm)

Creating Cache Subscriptions

You can create the cache subscriptions either by using the BCS Artifact Generator Tool, or manually by using the Template: BasicSubscription_Subscription.xml provided in the SharePoint 2010 SDK.

To use the BCS Artifact Generator Tool to create the subscription files

To create both of the required subscription files based on the BDC model, CustomerSubscription.xml and OrderHeaderSubscription.xml, download and then run the BCS Artifact Generator Tool. For more information, see BCS Artifact Generator Tool.

To use the basic subscription template to create the subscription files

  1. Locate the Template: SubscriptionWithAssociation_Subscription.xml provided in the SharePoint 2010 SDK, copy it, and then save it in the Solution Artifacts folder as CustomerSubscription.xml.

  2. Open CustomerSubscription.xml for editing in an XML editor. If you are opening the XML file in Microsoft Visual Studio, attach the Subscription schema (Subscription.xsd). This gives you IntelliSense functionality and can help prevent you from creating entries that are not valid.

  3. Replace the values marked with EnterX in the XML with valid values. The following XML example shows how the file might look after editing.

    Note

    This is a very simple subscription. You can create more complex subscription files by adding more elements and properties to the file. For more information, see the Subscription Schema documentation.

    <?xml version="1.0" encoding="utf-8" ?> 
<Subscription LobSystemInstanceName="http://contoso/webservice.asmx?wsdl" 
              EntityNamespace="AdventureWorks" EntityName="Customer" 
              Name="CustomerSubscription" View="GetCustomerById" 
              IsCached="true" RefreshIntervalInMinutes="360" 
xmlns="https://schemas.microsoft.com/office/2006/03/BusinessDataCatalog">
  <Queries>
    <Query Name="CustomerQuery" MethodInstanceName="GetCustomers" 
           DefaultDisplayName="Customer Read List" 
           RefreshIntervalInMinutes="180" 
IsCached="true" Enabled="true" /> 
  </Queries>
  <Associations>
    <Association Name="GetOrdersForCustomer" 
                 MethodInstanceName="GetOrdersForCustomer" 
                 TargetSubscriptionName="OrderHeaderSubscription" 
TargetView="GetSalesOrderHeaderById" 
                 LobSystemInstanceName="http://contoso/webservice.asmx?wsdl" 
                 RefreshIntervalInMinutes="60" /> 
  </Associations>
</Subscription>

  4. Save the file and then close it.

  5. Create the target subscription that tells Business Connectivity Services what query to execute to populate the related orders for each customer. To do this, copy the Template: BasicSubscription_Subscription.xml, and then save it to the Solution Artifacts folder as OrderHeaderSubscription.xml.

  6. Open the OrderHeaderSubscription.xml file for editing. If you open the file in Visual Studio, attach the Subscription schema (Subscription.xsd).

  7. Replace the values that are marked with EnterX in the XML with valid values. The name you specify here for the subscription must match the name that was specified for the TargetSubscriptionName attribute in CustomerSubscription.xml. The following XML example shows how the file might look after editing.

    <?xml version="1.0" encoding="utf-8" ?>
<Subscription LobSystemInstanceName="http://contoso/webservice.asmx?wsdl"
              EntityNamespace="AdventureWorks" EntityName="Customer"
              Name="CustomerSubscription" View="GetCustomerById"
              IsCached="true" RefreshIntervalInMinutes="360"
              xmlns="https://schemas.microsoft.com/office/2006/03/BusinessDataCatalog">
  <Queries>
    <Query Name="CustomerQuery" MethodInstanceName="GetCustomers"
           DefaultDisplayName="Customer Read List"
           RefreshIntervalInMinutes="180"
IsCached="true" Enabled="true" />
  </Queries>
  <Associations>
    <Association Name="GetOrdersForCustomer"
                 MethodInstanceName="GetOrdersForCustomer"
                 TargetSubscriptionName="OrderHeaderSubscription"
TargetView="GetSalesOrderHeaderById"
                 LobSystemInstanceName="http://contoso/webservice.asmx?wsdl"
                 RefreshIntervalInMinutes="60" />
  </Associations>
</Subscription>

  8. Save the file, and then close it.

You have successfully created the cache subscriptions that you need for the intermediate declarative Outlook solution.

Next Steps

Step 3: Create the Solution Manifest File (OIR.config)