XML schemas and data in document-level customizations

Applies to: Visual Studio Visual Studio for Mac

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.

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.

The following table shows some of the differences between the two methods.

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 Deploy 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

// 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;
}

See also

• How to: Map schemas to Word documents inside Visual Studio
• How to: Map schemas to worksheets inside Visual Studio