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 Excel and Word. 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.
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.
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.
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.
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.|
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.
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, Services, 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