XML Schemas and Data in Document-Level Customizations
Important The information set out in this topic regarding Microsoft Word is presented exclusively for the benefit and use of individuals and organizations who are located outside the United States and its territories or who are using, or developing programs that run on, Microsoft Word products that were licensed by Microsoft before January 2010, when Microsoft removed an implementation of particular functionality related to custom XML from Microsoft Word. This information regarding Microsoft Word may not be read or used by individuals or organizations in the United States or its territories who are using, or developing programs that run on, Microsoft Word products that were licensed by Microsoft after January 10, 2010; those products will not behave the same as products licensed before that date or purchased and licensed for use outside the United States.
Applies to: The information in this topic applies to document-level projects for the following applications: Excel 2013 and Excel 2010; Word 2013 and Word 2010. For more information, see Features Available by Office Application and Project Type.
Microsoft Office Excel and Microsoft Office Word provide the capability to map schemas to your documents. This feature can simplify importing and exporting XML data in and out of the document.
Visual Studio exposes mapped schema elements in document-level customizations as controls in the programming model. For Excel, Visual Studio adds support for binding the controls to data in databases, Web services, and objects. For Word and Excel, Visual Studio adds support for actions panes, which can be used with a schema-mapped document to create an enhanced end user experience for your solutions. For more information, see Actions Pane Overview.
Note
You cannot use multipart XML schemas in Excel solutions.
Objects Created when Schemas are Attached to Excel Workbooks
When you attach a schema to a workbook, Visual Studio automatically creates several objects and adds them to your project. These objects should not be deleted using Visual Studio tools, because they are managed by Excel. To delete them, remove the mapped elements from the worksheet or detach the schema by using Excel tools.
There are two main objects:
XML schema (XSD file). For every schema in the workbook, Visual Studio adds a schema to the project. This appears as a project item with an XSD extension in Solution Explorer.
A typed DataSet class. This class is created based on the schema. This dataset class is visible in Class View.
Objects Created when Schema Elements are Mapped to Excel Worksheets
When you map a schema element from the XML Source task pane to a worksheet, Visual Studio automatically creates several objects and adds them to your project:
Controls. For every mapped object in the workbook, an XmlMappedRange control (for non-repeating schema elements) or a ListObject control (for repeating schema elements) is created in the programming model. The ListObject control can be deleted only by deleting the mappings and the mapped objects from the workbook. For more information about controls, see Host Items and Host Controls Overview.
BindingSource. When you create an XmlMappedRange by mapping a non-repeating schema element to the worksheet, a BindingSource is created and the XmlMappedRange control is bound to the BindingSource. You must bind the BindingSource to an instance of the data source that matches the schema mapped to the document, such as an instance of the typed DataSet class that was created. Create the binding by setting the DataSource and DataMember properties, which are exposed in the Properties window.
Note
The BindingSource is not created for ListObject objects. You must manually bind the ListObject to the data source by setting the DataSource and DataMember properties in the Properties window.
Office Mapped Schemas and the Visual Studio Data Sources Window
Both the mapped schema functionality of Office and the Visual Studio Data Sources window can help you present data on an Excel worksheet for reporting or editing. In both cases you can drag data elements onto the Excel worksheet. Both methods create controls that are data bound through a BindingSource to a data source such as a DataSet or a Web service.
Note
When you map a repeating schema element to a worksheet, Visual Studio creates a ListObject. The ListObject is not automatically bound to data through the BindingSource. You must manually bind the ListObject to the data source by setting the DataSource and DataMember properties in the Properties window.
The following table shows some of the differences between the two methods.
XML schema |
Data Sources window |
|---|---|
Uses Office interface. |
Uses Data Sources window in Visual Studio. |
Enables the built-in Office features for importing and exporting data from XML files. |
You must provide import and export functionality programmatically. |
You must write code to fill the generated controls with data. |
Controls added from the Data Sources window have code generated automatically to fill them, along with the necessary connection strings when you use database servers. |
Behavior when Schemas are Attached to Word Documents
Data objects are not created when you attach a schema to a Word document that is used in a document-level Office project. However, when you map a schema element to your document, controls are created. The type of control depends on what type of element you map; repeating elements generate XMLNodes controls, and non-repeating elements generate XMLNode controls. For more information, see XMLNodes Control and XMLNode Control.
Deployment of Solutions That Include XML Schemas
You should create an installer to deploy a solution that uses an XML schema that is mapped to a document. The installer should register the schema in the schema library on the user's computer. If you do not register the schema, the solution will still work because Word generates a temporary schema based on the elements that are in the document when the user opens it. However, the user will not be able to perform validation against or save the schema that was used to create the project. For more information about installers, see Deploying Applications and Components.
You can also add code to your project to check whether the schema is in the library and registered. If it is not, you can warn the user.
' Ensure that the schema is in the library and registered with the document.
Private Function CheckSchema() As Boolean
Const namespaceUri As String = "http://schemas.contoso.com/projects"
Dim namespaceFound As Boolean = False
Dim namespaceRegistered As Boolean = False
Dim n As Word.XMLNamespace
For Each n In Application.XMLNamespaces
If (n.URI = namespaceUri) Then
namespaceFound = True
End If
Next
If Not namespaceFound Then
MessageBox.Show("XML Schema is not in library.")
Return False
End If
Dim r As Word.XMLSchemaReference
For Each r In Me.XMLSchemaReferences
If (r.NamespaceURI = namespaceUri) Then
namespaceRegistered = True
End If
Next
If Not namespaceRegistered Then
MessageBox.Show("XML Schema is not registered for this document.")
Return False
End If
Return True
End Function
// Ensure that the schema is in the library and registered with the document.
private bool CheckSchema()
{
const string namespaceUri = "http://schemas.contoso.com/projects";
bool namespaceFound = false;
bool namespaceRegistered = false;
foreach (Word.XMLNamespace n in Application.XMLNamespaces)
{
if (n.URI == namespaceUri)
{
namespaceFound = true;
}
}
if (!namespaceFound)
{
MessageBox.Show("XML Schema is not in library.");
return false;
}
foreach (Word.XMLSchemaReference r in this.XMLSchemaReferences)
{
if (r.NamespaceURI == namespaceUri)
{
namespaceRegistered = true;
}
}
if (!namespaceRegistered)
{
MessageBox.Show("XML Schema is not registered for this document.");
return false;
}
return true;
}