XML schemas and data in document-level customizations

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

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.

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:

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