Microsoft Office and .NET Development Tools Update

  • Article

 

Paul Cornell
Microsoft Corporation

September 5, 2002

Summary: Discusses four new Office XP development offerings including the Office XP Web Services Toolkit 2.0, the Web Service References Tool 2.0, the Fabrikam Office Web Services Integration (OWSI) Solution Sample, and the Office XP Primary Interop Assemblies (PIAs). (9 printed pages)

It has been almost a year since I first introduced you, the Microsoft® Office solutions developer, to Microsoft .NET solutions development. We have come a long way since then. Not only have I written an Office Talk article introducing .NET to Office developers, I have written:

Last month, coauthor Chris Kunicki wrote an article on working with ADO.NET datasets. Rest assured, you will continue to see stronger support for Office development using products that rely on .NET, such as Visual Studio® .NET. Microsoft has shipped even more support for Office XP and Microsoft .NET solution development in the last few months. In this month's article, I will bring you up to speed on four new Office XP development offerings:

  • The Office XP Web Services Toolkit 2.0
  • The Web Service References Tool 2.0
  • The Fabrikam Office Web Services Integration (OWSI) Solution Sample
  • The Office XP Primary Interop Assemblies (PIAs) (releasing soon)

Office XP Web Services Toolkit 2.0

In February of this year, Microsoft released the first version of the Office XP Web Services Toolkit, which allows Microsoft Office XP applications to begin integrating XML Web services in an easier way. Before the Web Services Toolkit was released, Office solution developers could only rely on the Microsoft Soap Type Library (mssoap1.dll). With only the Microsoft Soap Type Library, developers did not have a convenient, integrated way to locate or reference available XML Web services. IntelliSense® for Web methods was also not supported until the Web Services Toolkit came along.

The original Web Services Toolkit, however, lacked a few key features, including support for complex input values and return values such as arrays and enumerations.

The Office XP Web Services Toolkit 2.0 includes support for complex input values and return values, as well as support for:

  • Soap Toolkit 3.0 features such as binary attachments to XML Web service messages and user-defined data type mappers.
  • Microsoft XML Core Services (MSXL) 4.0 features such as support for the World Wide Web Consortium (W3C) final recommendations for XML Schema, the XML Document Object Model, and SAX, and substantially faster XSL Transformations (XSLT) and SAX parsers.

The Web Services Toolkit 2.0 includes the following components:

Let's take a closer look at the Web Service References Tool 2.0 and the Fabrikam Office Web Services Integration Sample.

Web Services References Tool 2.0

Included in the Office XP Web Services Toolkit 2.0, the Web Service References Tool 2.0 allows you to reference XML Web services from within the Visual Basic Editor. After you install the Web Services Toolkit 2.0 and the Web Service References Tool 2.0, here is an exercise that you can try to experience the Web Service References Tool 2.0 in action:

  1. Start Microsoft Word. A new, blank document appears.

  2. On the Tools menu, point to Macros, and click Visual Basic Editor. The Visual Basic Editor appears.

  3. On the Tools menu, click Web Service References. The Web Service References Tool 2.0 dialog box appears.

  4. Select the Web Service URL option.

  5. In the URL box, type http://services.fabrikam.com/owsisample/Supplier.asmx?wsdl, and click Search.

  6. In the Search Results list, select the SupplierData check box, and then click Add. A class module, clsws_SupplierData.cls, is added to your Visual Basic® for Applications (VBA) project. This class module encapsulates the XML Web service details so that you can call the available Web methods by using VBA objects.

  7. In the ThisDocument code module of the Word document, type the following:

    Private Sub SupplierDataToTable()

    ' Purpose: Converts supplier data from an XML
    ' Web service into a Word table in a document.

    Dim oSupplierData As clsws_SupplierData
    Dim oFullNodeList As MSXML2.IXMLDOMNodeList
    Dim oFilteredNodeList As MSXML2.IXMLDOMNodeList
    Dim oNode As MSXML2.IXMLDOMNode
    Dim oTable As Word.Table
    Dim iRow As Integer
    Dim iColumn As Integer

    Set oSupplierData = New clsws_SupplierData
    Set oFullNodeList = oSupplierData.wsm_SupplierList
    Set oFilteredNodeList = _
        oFullNodeList.Item(1).selectNodes("NewDataSet/Table")
    Set oTable = ActiveDocument.Tables.Add _
        (Application.Selection.Range, _
        oFilteredNodeList.Length, _
        oFilteredNodeList.Item(1).childNodes.Length)

    With oTable

        .Cell(1, 1).Range.Text = "Supplier ID"
        .Cell(1, 2).Range.Text = "Supplier Name"
        .Cell(1, 3).Range.Text = "Description"

        iRow = 2
        iColumn = 1

        For Each oNode In oFilteredNodeList

            .Cell(iRow, iColumn).Range.Text = _
                oNode.selectSingleNode("SupplierID").Text

            iColumn = iColumn + 1

            .Cell(iRow, iColumn).Range.Text = _
                oNode.selectSingleNode("SupplierName").Text

            iColumn = iColumn + 1

            .Cell(iRow, iColumn).Range.Text = _
                oNode.selectSingleNode("Description").Text

            iRow = iRow + 1
            iColumn = 1

        Next oNode

    End With

End Sub

  8. Run the SupplierDataToTable subroutine. A table, containing the list of suppliers, is inserted in the active Word document. The table should look like Figure 1 below.

    Figure 1. Results of running the SupplierDataToTable subroutine

    Here's how the code works:

  9. Objects are declared, representing the XML Web service, the XML data that the XML Web service returns, the individual elements (or nodes) of the XML data, a Word table, and counters to keep track of the table's rows and columns.

  10. A call is made to the XML Web service by using the wsm_SupplierList Web method, which returns an XML data document. Since we only need a portion of the XML data document, the selectNodes method is used to return just the data we need from the XML data document.

  11. The Tables collection's Add method adds a table to the active document at the insertion point. The table will contain one row per XML data record, and one column per XML data field.

  12. The Cell object's Range property returns a Range object. In turn, the Range object's Text property is used to insert table column headers in the table's first row.

  13. For each XML data record, data is added to the Word table, one XML data field at a time, again by using the Range object's Text property. After each table cell has data in it, the row counter resets and the next XML data record is fetched.

Compare the data in this table to the data at http://services.fabrikam.com/owsisample/Supplier.asmx/SupplierList? (the original XML data document), and you will see how valuable the Web Service References Tool 2.0 and a little VBA implementation code can be when calling XML Web services and parsing return values.

For more information about the Web Service References Tool 2.0, see the following resources:

Fabrikam Office Web Services Integration Solution Sample

Microsoft created Fabrikam, a fictional furniture manufacturing organization, to showcase how XML Web services can be integrated into real-world Office XP business solutions. Building off of the highly successful Office XP Developer Fabrikam Solution and Fabrikam 2.0, the Fabrikam Office Web Services Integration (OWSI) Solution Sample was created and is included with the Office XP Web Services Toolkit 2.0.

After you have installed the FabOWSI.msi file from the Office XP Web Services Toolkit 2.0, you can do one of two things:

  1. You can install and run the complete Fabrikam OWSI Solution Sample client applications and server infrastructure on a single computer. This provides you the most control over the solution sample and ensures the highest application performance. Provided that your testing computer meets the minimum system requirements, on the Start menu, point to All Programs, point to Office XP Web Services Toolkit, point to Fabrikam Office Web Services Integration Sample, click Fabrkiam OWSI Setup Utility.exe, and follow the on-screen directions.

    OR

  2. You can install and run only the client portion of the Fabrikam OWSI Solution Sample on a single computer and interact with the live Fabrikam OWSI Solution Sample XML Web services over the Internet. Although this results in fewer installation steps, you may encounter a slight performance loss and cannot modify the XML Web service back-end code in any way. To install and run only the client portion of the solution sample:

    1. Quit any running instances of Word and Excel.

    2. Locate and open the owsico.config file with Notepad. In a default installation, this file is located in the C:\Program Files\Microsoft Office XP Web Services Toolkit 2.0\Fabrikam OWSI Sample\Source\Client Objects\ folder.

    3. Change the BaseServerPath attribute value to http://services.fabrkiam.com/owsisample/ in the following line of code in the owsico.config file:

      <FabrikamOWSIConfig 
BaseServerPath="https://localhost/fabrikamowsisamples/" 
LoggingMode="None">

    4. Save and close the owsico.config file.

To use the Fabrikam Web Service Connector add-in:

  1. Start Microsoft Word or Microsoft Excel.
  2. In Excel, if the Fabrkiam Web Service Connector button is not visible on the Standard toolbar:
    • On the Tools menu, click Add-Ins. The Add-Ins dialog box appears.
    • Click Browse. The Browse dialog box appears.
    • Locate and click the Fabrkiam Web Services Connector.xla file (in a default installation, this file is located in the C:\Program Files\Microsoft Office XP Web Services Toolkit 2.0\Fabrikam OWSI Sample\Source\Office Addins\ folder).
    • Click OK to close the Browse dialog box and reference the Fabrikam Web Services Connector.xla file.
    • Click OK again to close the Add-Ins dialog box and display the Fabrikam Web Services Connector button on the Standard toolbar.
  3. In Word, if the Fabrikam Web Service Connector button is not visible on the Standard toolbar:
    • On the Tools menu, click Templates and Add-Ins. The Templates and Add-Ins dialog box appears.
    • Click Add. The Add Template dialog box appears.
    • Locate and click the Fabrikam Web Service Connector.dot file (in a default installation, this file is located in the C:\Program Files\Microsoft Office XP Web Services Toolkit 2.0\Fabrikam OWSI Sample\Source\Office Addins\ folder).
    • Click OK to close the Add Template dialog box and reference the Fabrikam Web Service Connector.dot file.
    • Click OK again to close the Templates and Add-Ins dialog box and display the Fabrikam Web Service Connector button on the Standard toolbar.
  4. Click the Fabrikam Web Service Connector button on the Standard toolbar. The Fabrikam Web Service Connector dialog box appears.
  5. Double-click one the entries in the TreeView control and follow the on-screen directions.

To get a feel for how the sample solution works, here's an example of one of the Fabrikam Web Service Connector actions that you can run:

  1. Start Excel.

  2. Click the Fabrikam Web Service Connector button on the Standard toolbar. The Fabrikam Web Service Connector dialog box appears.

  3. Double-click the Orders node to display the list of Orders subcategories.

  4. Double-click the Customer Order History node to display the list of Customer Order History actions.

  5. Double-click the Chart entry. The Customer Order History (Chart) dialog box appears.

  6. On the Parameters tab, in the Company list, select Alpine Ski House.

  7. Click OK to close the Customer Order History (Chart) dialog box and display the chart.

    The chart looks like Figure 2 below.

    Figure 2. Results of running the Customer Order History Chart action.

Office XP Primary Interop Assemblies

COM interop assemblies allow managed (.NET) code components, such as solutions developed with Microsoft Visual Studio® .NET, to use unmanaged (COM) code components, such as the Office XP type libraries.

Whenever a Visual Studio .NET developer references a COM code component, Visual Studio .NET creates a COM interop assembly to enable the Visual Studio .NET solution to interoperate with the COM code component. For each Visual Studio .NET solution that references a COM component, even if the same COM code component is referenced in multiple solutions, a new COM interop assembly is created. To reduce the number of duplicate COM interop assemblies, as well as address specific interop issues between Office XP COM technology and Microsoft .NET technology, Microsoft is creating several primary interop assemblies (PIAs) that contain the official description of commonly-used Microsoft Office XP type libraries for products such as Microsoft Access 2002, Microsoft Excel 2002, Microsoft FrontPage® 2002, and so on. This group of PIAs is known as the Office XP Primary Interop Assemblies. Microsoft is customizing the Office XP PIAs to make them easier for managed code to interoperate with the Office XP COM type libraries. Office XP solution developers should use the upcoming Office XP PIAs whenever possible. Any Office XP COM interop assembly that is not provided as part of the Office XP PIAs, or any generic Office XP COM interop assembly that is generated by Microsoft Visual Studio .NET at design time, should be considered unofficial and their use should be avoided.

The Office XP PIAs are now available from the MSDN Downloads site. Download the Office XP PIAs. Over the next several months, the MSDN Office Developer Center will provide examples of how to incorporate Office XP and the Office XP PIAs into your Visual Studio .NET solutions.

Paul Cornell works for the MSDN Online Office Developer Center and the Office developer documentation team. Paul also contributes to the Office Power User Corner column for the Office Assistance Center. He spends his free time with his wife and two daughters.