XML for ASP.NET Developers (Kaleidoscope)

XML for ASP.NET Developers Dan Wahlin 201 West 103rd St., Indianapolis, Indiana, 46290 USA XML for ASP.NET Developer...

212 downloads 859 Views 2MB Size Report

This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!

Report copyright / DMCA form

DOWNLOAD PDF

XML for ASP.NET Developers Dan Wahlin

201 West 103rd St., Indianapolis, Indiana, 46290 USA

XML for ASP.NET Developers

ASSOCIATE PUBLISHER

Copyright © 2002 by Sams

ACQUISITIONS EDITOR

All rights reserved. No part of this book shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from the publisher. No patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions. Nor is any liability assumed for damages resulting from the use of the information contained herein.

Neil Rowe

International Standard Book Number: 0-672-32039-8 Library of Congress Catalog Card Number: 00-105164 Printed in the United States of America First Printing: August 2001 04

03

02

01

4

3

2

1

Trademarks All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Sams cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.

Warning and Disclaimer Every effort has been made to make this book as complete and as accurate as possible, but no warranty or fitness is implied. The information provided is on an “as is” basis. The author and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book.

Jeff Koch

DEVELOPMENT EDITOR Kevin Howard

MANAGING EDITOR Matt Purcell

PROJECT EDITOR Natalie Harris

COPY EDITOR Karen Gill Kim Cofer Barbara Hacha

INDEXER Cheryl Landes

PROOFREADER Marcia Deboy

TECHNICAL EDITOR Lamar Kirby Mingyong Yang

TEAM COORDINATOR Vicki Harding

MEDIA DEVELOPER Dan Scherf

INTERIOR DESIGNER Dan Armstrong

COVER DESIGNER Aren Howell

PAGE LAYOUT Susan Geiselman

Contents at a Glance Introduction

1

1

XML and ASP.NET Development

2

XML for ASP.NET Basics

3

XPath, XPointer, and XLink

4

Understanding DTDs and XML Schemas

5

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET

6

Programming the Document Object Model (DOM) with ASP.NET

7

Transforming XML with XSLT and ASP.NET

8

Leveraging ADO.NET’s XML Features Using ASP.NET

9

SQL Server 2000, XML, and ASP.NET

10

3

13 51 89

233

349

Working with ASP.NET, XML, SOAP, and Web Services Index

451

293

399

175

133

Table of Contents Introduction

1

1

XML and ASP.NET Development 3 XML’s Ancestor—SGML ......................................................................4 Why Do We Need XML? ......................................................................5 X Is for eXtensible ..................................................................................7 Differences Between XML and HTML ................................................8 Presentation Versus Description ........................................................8 Closing Tags ......................................................................................9 Element Nesting ..............................................................................10 Quoted Attributes ............................................................................10 Case Sensitivity ..............................................................................10 MSXML3 Versus the .NET Platform’s System.Xml Assembly ..........10 How Can XML Be Used by an ASP.NET Developer? ........................................................................................11 Summary ..............................................................................................12

2

XML for ASP.NET Basics 13 What’s in an XML Document? ............................................................14 Well-Formed XML Documents ............................................................16 The Root Element ............................................................................17 Versus ............................................................................18 Nesting No-No’s ..............................................................................19 Other Rules ......................................................................................20 Valid XML Documents ........................................................................20 The XML Declaration ..........................................................................21 The xml Keyword ............................................................................22 The XML Document Version ..........................................................22 The Encoding Type ........................................................................22 The standalone Keyword ................................................................23 XML Elements ......................................................................................24 XML Attributes ....................................................................................25 XML Namespaces ................................................................................27 Namespace Structure ......................................................................29 Default Namespaces ........................................................................29 Qualified Namespaces ....................................................................31 XML Processing Instructions ..........................................................34 XML Comments ..............................................................................34 XML Entities ..................................................................................35 Standard Entities ..............................................................................36 Using ASP.NET Objects to Generate XML ..........................................44 Character Entities ............................................................................37 Internal, External, and Parameter Entities ......................................38 CDATA Sections ..................................................................................40 Dealing with Whitespace ......................................................................41 The Relationship of XML to XHTML ................................................42

vi

XML

FOR

ASP.NET DEVELOPERS Using ASP.NET Objects to Generate XML ..........................................44 Application Specifics ......................................................................45 Application Summary ......................................................................50 Summary ..............................................................................................50

3

XPath, XPointer, and XLink 51 Meet a Few of XML’s Relatives ..........................................................52 XPath—The SQL of XML ..................................................................53 XPath Basics ....................................................................................54 XPath Functions ..............................................................................60 XPath Abbreviation Examples ........................................................66 XPointer—Accessing XML Document Fragments ..............................69 XPointer Basics ..............................................................................70 XPointer Examples ..........................................................................75 XLink—Resource Relationship Management ......................................76 XLink Basics ..................................................................................77 XLink Keyword Definitions ............................................................79 XLink Attributes ..............................................................................80 The XLink Simple Link ........................................................................82 XLink Extended Links ..........................................................................83 Linkbases and External Linksets ....................................................86 Putting XLink Together ........................................................................87 Summary ..............................................................................................88

4

Understanding DTDs and XML Schemas 89 Why Use DTDs or Schemas? ..............................................................90 Do I Really Need to Validate? ..............................................................91 DTD Basics ..........................................................................................93 The DTD DOCTYPE ......................................................................94 DTD Elements ................................................................................95 DTD Attributes ................................................................................97 DTD Entities ....................................................................................99 DTD Notations ..............................................................................101 Summing Up DTDs ......................................................................101 XML Schemas—Looks a Lot Like XML! ........................................101 A Sample XML-DR Schema and Its DTD Counterpart ..............102 Using the Schema Keyword with Namespaces in XMLDR Schemas ................................................................................105 XML-DR Elements, Groups and Attributes ..................................106 XML Data Types ..........................................................................111 XML-DR Description Element ....................................................113 XML-DR Summary ......................................................................113 The W3C XML Schema ....................................................................114 W3C Schma Elements and Attributes ............................................116 Data Type Definitions ....................................................................116 Creating Unique Fields, Keys, and Relationships..........................124 Namespace Support in XML Schemas ........................................128 Referencing XML Schemas from Within XML Documents ........129 XML Schema Summary ................................................................130 Summary ............................................................................................130

CONTENTS

5

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET 133 Introducing the System.Xml Assembly ..............................................134 In Memory Versus Forward-Only Parsing ..........................................135 Pull Versus Push Models......................................................................137 Using the XmlTextReader Class to parse XML ..................................138 Building a SAX-Style Push Model Using the XmlTextReader ..........145 Step 1: Referencing Assemblies ....................................................152 Step 2: Setting the Handlers ..........................................................153 Step 3: Declaring the XmlTextReader Class ................................153 Step 4: Instantiating the XmlTextReader Class ............................153 Step 5: Reading from the Stream ..................................................154 Step 6: Checking for Element Nodes ............................................154 Step 7: Checking for End Element Nodes ....................................156 Step 8: Reading Text Nodes ..........................................................156 Step 9: Handling Processing Instructions, Whitespace, and Entities ..................................................................................157 Step 10: Ending the Parsing Process and Catching Errors ..........157 Step 11: Calling the SAX Parser from an ASP.NET Page ............158 Validating XML Documents Using the XmlTextReader and XMLValidatingReader ......................................................................159 Instantiating the XmlValidatingReader ........................................160 Setting the ValidationType ............................................................160 Using the XmlSchemaCollection Class ........................................161 Attaching Event Handlers ............................................................161 Creating a Generic Validation Class ..............................................162 Passing Authentication Credentials with the XmlTextReader Class ..................................................................................................166 Using the XMmlTextWriter Class to Create XML Documents ..........166 Converting EDI or Legacy Data to XML ......................................169 Summary ............................................................................................173

6

Programming the Document Object Model (DOM) with ASP.NET 175 Welcome to the DOM ........................................................................176 In-Memory Versus Forward-Only Parsing ..........................................178 Working with MSXML3 via Interop ..................................................179 DOM Classes in the System.xml Namespace and Assembly ............182 The XmlNode Class ............................................................................183 The XmlDocument Class ....................................................................189 XmlDocument Object Properties and Methods ............................189 Loading an XML Document using the XmlDocument Class........194 Creating Nodes Using the XmlDocument Class ..........................196 The XmlNodeList Class ....................................................................200 The XmlNamedNodeMap Class ........................................................201 Selecting Nodes Within the DOM Using Xpath ................................204 Putting it All Together ........................................................................205 The XmlNodeReader Class ................................................................209 XMLHTTPRequest Object ................................................................211

vii

viii

XML

FOR

ASP.NET DEVELOPERS Sample Applications-Client Server-Side Hierarchical XML Menus ................................................................................................219 Chapter 2 Sample Application Revisited ............................................225 Summary ............................................................................................232

7

Transforming XML with XSLT and ASP.NET 233 What Is XSLT? ..................................................................................234 The Transformation Process ..............................................................235 XSLT Templates ............................................................................236 Getting Your Feet Wet with XSLT ......................................................237 The XSLT Language ..........................................................................242 The XSLT Document Root Element ............................................242 XSLT Elements ............................................................................243 Transforming XML into Another Form of XML Using XSLT Elements............................................................................258 XSLT Functions ..................................................................................267 The XPathDocument Class ..........................................................273 .NET Classes Involved in Transforming XML....................................272 The XslTransform Class ................................................................275 The XsltArgumentList Class ........................................................276 Putting it All Together ....................................................................278 Using Extension Objects with XSLT ............................................282 Creating a Reusable XSLT Class ........................................................287 The Asp:Xml Web Control ............................................................289 Summary ............................................................................................291

8

Leveraging ADO.NET’s XML Features Using ASP.NET 293 Introducing ADO.NET ......................................................................294 Comparing Classic ADO with ADO.NET ..........................................294 XML Integration ............................................................................294 What Happened to the RecordSet Object? ....................................294 Disconnected Versus Connected ....................................................295 ADO.NET Basics ..............................................................................295 ADO.NET Managed Providers ....................................................296 The Command Class ....................................................................298 The SqlDataAdapter and OleDbDataAdapter Classes ..................306 The DataSet Class ..............................................................................308 Viewing DataSets as XML ............................................................311 Loading DataSets with XML ........................................................318 Saving DataSets as XML ..............................................................320 Working with the DataSet and XmlDataDocument Classes ..............324 XmlDataDocument Properties and Methods ................................328 Shaping DataSet Columns with the MappingType Enumeration ................................................................................338 Mapping XSD Schemas to a DataSet ..........................................341 Creating DataSet Mappings Using XML ......................................343 Using DataSets to Work with Hierarchical XML Data and XSLT ....................................................................................345 Summary ............................................................................................348

CONTENTS

9

SQL Server 2000, XML, and ASP.NET 349 XML Features in SQL Server 2000 ..................................................350 Querying SQL Server 2000 Using HTTP ..........................................351 Configuring SQL Server Virtual Directories in IIS........................351 Querying SQL Server 2000 Through HTTP Using the FOR XML Keywords ................................................................353 Using HTTP Queries to Return Elements and Schemas ..............362 Querying SQL Server 2000 Through HTTP with XML Templates ....................................................................................363 Querying SQL Server 2000 through HTTP Using Templates, XPath, and XDR Schemas ................................................................368 SQL Server 2000 Schemas and Annotations ................................369 Using XPath Queries and Schemas in a URL ..............................374 Using XPath Queries, Schemas, and Templates ..........................375 Using EXPLICIT Mode Queries ........................................................377 Using Directives in EXPLICIT Mode Queries ............................381 Using OPENXML to Manipulate X ....................................................385 XML Updategrams—Update, Inserts, and Delete Database Records with XML Using ASP.NET ................................................389 Using ADO.NET with SQL Server 2000 ..........................................394 The XmlParserContext Class ........................................................396 Summary ............................................................................................398

10

Working with ASP.NET, XML, SOAP, and Web Services 399 Understanding SOAP ..........................................................................400 Alternatives to SOAP ....................................................................400 What Is SOAP? ............................................................................402 Analyzing SOAP’s Structure ........................................................404 The SOAP Envelope ......................................................................407 The SOAP Header ........................................................................408 The SOAP Body ............................................................................410 SOAP Encoding and Data Types ..................................................414 SOAP HTTP Headers ....................................................................419 Understanding Web Services ..............................................................421 Web Service Protocols (SOAP, HTTP-GET, HTTP-POST) ........422 Web Service Architecture ..............................................................424 Introducing Web Service Attributes ............................................425 Consuming a Web Service from an ASP.NET File ......................439 Retrieving Customer Orders Through a Web Service ........................444 Web Service Description ..............................................................444 Creating the ACME Distribution, Inc. Web Service ....................445 Consuming the ACME Distribution, Inc. Web Service ................447 Summary ............................................................................................450 Index

451

ix

About the Author Dan Wahlin is an independent consultant for Wahlin Consulting and also founded the XML for ASP.NET website (http://www.XMLforASP.NET) which focuses on using XML and Web Services in Microsoft’s .NET platform. He also works as a corporate trainer for Global Knowledge. Previously, Dan worked as an enterprise Web site manager, director of Internet/wireless development, and as senior consultant for a global systems integrator. Dan enjoys writing technical articles on XML-related topics for Visual Studio Magazine, ASPToday.com, and is a regular columnist in XML Magazine. Dan co-authored Professional Windows DNA (WROX Press) and ASP.NET Tips and Tricks (Sams). You can contact Dan at [email protected].

Dedication To my wife Heedy, our two boys (my best buddies) Danny and Jeffery, and my parents.

Acknowledgments I would like to thank my wife and children for their extreme patience as I spent evening after evening and weekend after weekend working on this book. Heedy, I know you’re happy I finally finished this book! I’d also like to thank my mom and dad (Elaine and Danny) for bringing me up in such a pleasant environment and pushing me to succeed in life. I couldn’t have asked for better parents. To Paul Allsing and Lin Thatcher, thanks for giving me my first shot at working in the technology industry. Had it not been for your confidence in me, I wouldn’t have had the opportunity to write this book. I’d also like to thank Chris Lovett and Mark Fussell of Microsoft for answering so many questions for me over the past year. Without their help and samples, the book would not have turned out as well as it did. Finally, I’d like to thank Neil Rowe of Sams for being such a fun editor to work with. His patience and understanding when code had to be rewritten from build to build made the process much more enjoyable.

Tell Us What You Think! As the reader of this book, you are our most important critic and commentator. We value your opinion and want to know what we’re doing right, what we could do better, what areas you’d like to see us publish in, and any other words of wisdom you’re willing to pass our way. As an Associate Publisher for Sams, I welcome your comments. You can fax, e-mail, or write me directly to let me know what you did or didn’t like about this book—as well as what we can do to make our books stronger. Please note that I cannot help you with technical problems related to the topic of this book, and that because of the high volume of mail I receive, I might not be able to reply to every message. When you write, please be sure to include this book’s title and author as well as your name and phone or fax number. I will carefully review your comments and share them with the author and editors who worked on the book. Fax:

317-581-4770

Email:

[email protected]

Mail:

Jeff Koch Sams Publishing 201 West 103rd Street Indianapolis, IN 46290 USA

Introduction Product vendors, CEOs, journalists, and technology evangelists alike have proclaimed that XML is the next big programming paradigm shift that will revolutionize computing. Although some of this hype is certainly not justified, much of it has been realized by early prototype applications developed to simplify document management, data exchange, and application integration issues. These applications have shown that XML can play a powerful role in making applications more flexible, maintainable, and accessible in today’s distributed world. Microsoft has been supportive of XML for many years now and has taken advantage of its benefits in different applications, including BizTalk Server, Internet Explorer, and SQL Server 2000 (to name a few). With Microsoft’s introduction of the .NET platform, a new revolution in application programming has started that features XML as the focal point. From Web Services to XML document parsing and creation, the .NET platform supports a wide range of XML features that ease application integration and allow programmers to write more efficient, distributed, and maintainable applications. This book focuses on many aspects of XML and shows how it can be used by ASP.NET programmers to increase application efficiency and reach. This includes discussing the rules associated with the XML Meta-Data Language, Document Type Definitions (DTDs) and XML schemas, the XPath language, and upcoming technologies to watch for—including XPointer and XLink. After the basics are covered, the book delves into the different ways that XML documents can be created, parsed, transformed, and transmitted to other systems using ASP.NET. This includes an in-depth look at the following topics: • Using the XmlTextReader’s Pull Model to parse XML • Creating XML with the XmlTextWriter • Validating XML documents against schemas and DTDs with the XmlValidatingReader and XmlTextReader • Working with the Document Object Model • Transforming XML with XSLT • XML support in ADO.NET • Integrating SQL Server 2000’s XML features into ASP.NET applications • Understanding the Simple Object Access Protocol (SOAP) • Creating Web services

2

XML for ASP.NET Developers

My goal was to make this book a useful reference for ASP.NET developers needing to know the ins and outs of working with XML in their applications. I also wanted developers to see a variety of ways that XML could be used in application development. Reading about a particular concept is not enough; a code sample often has more value than several pages of text. As a result, you’ll find that each chapter contains a large number of samples to reinforce concepts discussed throughout the chapter. Happy XMLing!

CHAPTER

XML and ASP.NET Development

1

IN THIS CHAPTER • XML’s Ancestor—SGML • Why Do We Need XML? • X Is for eXtensible

4 5

7

• Differences Between XML and HTML • MSXML3 Versus the .NET Platform’s System.Xml Assembly 10 • How Can XML Be Used by an ASP.NET Developer? 1177

8

4

XML for ASP.NET Developers

Unless you’ve been vacationing for a few years on a secluded island, it would be hard to miss all the hype surrounding XML. Newspapers, magazines, and Web sites throughout the world portray XML as the solution to many of our existing technological problems. This global attention has pushed XML into the limelight and resulted in a barrage of vendor applications claiming XML support. But is XML really as good as everyone seems to think it is? Although it’s not going to bring world peace or decrease ozone levels, it is certainly a power-packed technology that has a lot to offer after you learn how it works and when it can be applied. You’re probably keenly aware that XML provides a platform-independent way of describing data that can be used in many applications. We’ll get into plenty of details concerning this a little later, but before doing that, it’s important to first answer a few questions. To start with, where did XML come from and why is it needed in today’s technologically oriented world? More importantly, how can you as an ASP.NET developer leverage its power? This chapter discusses the answers to these questions and compares XML to another language you’re already familiar with. The chapters that follow will provide you with example after example of how XML can be used with ASP.NET to add useful functionality to your development projects. Before going too much further, let’s go ahead and answer the question of where XML came from.

XML’s Ancestor—SGML XML is a relatively new language in the world of markup languages. You’re probably quite familiar with XML’s cousin language named Hypertext Markup Language, or simply HTML. Markup languages are typically used to provide metadata about data. In the case of XML and HTML, this is done through special tags such as the tag in HTML. SQL Server’s system tables are another example of metadata. They provide information about the structure of data within the database itself. XML serves this same purpose except that it describes textbased data. Whereas the World Wide Web Consortium’s (W3C) XML 1.0 recommendation has only been around since February of 1998, XML’s parent language, Standard Generalized Markup Language (SGML), has been around as a standard since 1986. SGML is a complex language standard used extensively by many industries, including the technical-publication industry, to mark up data. It uses a syntax defined by SGML known as a Document Type Definition (DTD) to specify the structure of a given SGML document. Although XML is much easier to work with, many of its features and rules were derived from the SGML language. When the W3C first began formulating what is now the XML 1.0 recommendation back in 1996, they borrowed many concepts from SGML, including the DTD. To make XML easier to work with and more Web-oriented, many of SGML’s complexities were

XML and ASP.NET Development CHAPTER 1

left out. If you’re interested in reading a comparison of XML and SGML, take a look at http://www.w3.org/TR/NOTE-sgml-xml-971215.

Why Do We Need XML? With all the different programming languages available today, you may wonder why we need another one just to mark up data. Although many languages allow for programming different interfaces and interacting with remote computers, few provide a platform-neutral way to share data between disparate systems. Fewer yet allow this exchange to pass through firewalls or other security-related mechanisms or provide a format that is easy to work with for individuals with varying levels of technical skill. That’s where XML comes into the picture. The W3C XML working group knew that a simple language needed to be created that would be straightforward to use, make exchange of data between different systems more efficient, and work well in a Web environment. Because SGML was already successful in marking up data, many pieces of it were used to develop the XML subset, as mentioned earlier. This resulted in a language that can be both highly flexible and strictly structured at the same time, depending on the needs of the individual or system working with it. To get a good feel for one of the reasons why XML is needed, take a look at the following comma-delimited file: Elbow Joint,12930430,6,25,06/28/2000,1238 Van Buren,B2B ➥Supply,1111236894,Walters Valve,39405938,3,40,06/20/2000,4568 Arizona Ave.,A+ Supply,2221236894,Tammy PVC,234954048,6,20,06/14/2000,49032 S. 51,A+ Supply,2221236894,Walters

Although some assumptions can be made about what some of the data elements are within the file, many of the elements provide no way for you to know what they represent. For example, does the field 06/28/2000 shown in the first line represent a date? If so, what type of date? How about the 234954048 field in the third line? Is it a part number, a customer number, or something totally unrelated? Listing 1.1 shows this same file converted into XML. Listing 1.1

Marking Up a Comma-Delimited File Using XML

1: 2: 3: 4: Elbow Joint 5: 12930430

1 XML AND ASP.NET DEVELOPMENT

Now that you have some background on where XML came from, let’s take a look at why we need it.

5

6

XML for ASP.NET Developers

Listing 1.1

continued

6: 6 7: 25 8: 06/28/2000 9: 10: 1238 Van Buren 11: B2B Supply 12: 1111236894 13: 14: Walters 15: 16: 17: Valve 18: 39405938 19: 3 20: 40 21: 06/20/2000 22: 23: 4568 Arizona Ave. 24: A+ Supply 25: 2221236894 26: 27: Tammy 28: 29: 30: PVC 31: 234954048 32: 6 33: 20 34: 06/14/2000 35: 36: 49032 S. 51 37: A+ Supply 38: 2221236894 39: 40: Walters 41: 42:

Each data item can easily be recognized and understood because all the data has been described using XML markup tags. Using these tags can make it easier for humans and computers to process data. Although it’s true that computers normally take care of automating many data-intensive applications, programs based on files such as the flat file shown earlier have little flexibility to

XML and ASP.NET Development CHAPTER 1

XML also presents a great opportunity to be able to share data between applications and even components within an application. By knowing an XML file’s structure in advance, a component within an application can work with data contained in the XML file and perform different tasks. In some cases, the data may represent information about a customer or business scenario. In other cases, the XML file may simply represent object property values that an ASP.NET component can use to make programming simpler and more efficient. XML also benefits from the capability to determine in advance what structure the file must follow through incorporating DTD and schema files. Defining this structure allows for companies with differing systems to exchange data without worrying about what system the data was originally stored in. As long as both companies know what the XML document’s structure will be, they can exchange data using XML syntax. Applications based on XML, such as BizTalk Server or SQL Server 2000, help to make this process even easier, and when combined with the power of ASP.NET, very advanced applications can be created. Finally, as previously mentioned, XML does not require advanced degrees in computer science to use it. Looking at the XML code in Listing 1.1, you can see that no intimidating characters or syntax are being used. In fact, the XML file could be read and understood by an individual with no technical experience at all. After the syntax, structural, and programmatic rules are learned, XML documents can be created and used both in simple and complex applications.

X Is for eXtensible One important benefit associated with XML that hasn’t been mentioned yet is its capability to be extended. XML’s extensibility allows you as a developer to choose how tags within XML documents are named and structured. In HTML, you’re limited to using specific tags that work only when used in a predefined way. For instance, to place an image in an HTML document, you must use the tag. Within this tag, you can place only certain attributes, such as the src and vspace attributes. XML allows for tags and attributes to be created at will, depending on how the application being designed needs to be structured. Therefore, if you’d rather describe a path to an image using a tag named , you’re free to do so (as long as you also include a closing tag!). At first glance, this may appear to be a step toward total anarchy. After all, if everyone can create XML documents using tags that don’t follow any specific naming convention, how can anyone else possibly use the documents? The answer is that XML’s extensibility is held in check through the use of DTD or schema documents that define what structure a given XML document must follow to be valid. Therefore, if you want to create a document using custom

1 XML AND ASP.NET DEVELOPMENT

changes in the data’s structure. On the other hand, XML enables applications to access data based on descriptive tags rather than by position. This presents a great opportunity to increase an application’s flexibility toward changes in data structure.

7

8

XML for ASP.NET Developers

tags with names such as or to describe data, you can. Anyone wanting to use your XML document can do so if you provide them with a definition of how the document is structured and what tags are used to describe the data. The key to understanding the value of XML’s extensible framework is realizing that XML doesn’t specify how to present data to an end user or system. XML as a markup language is concerned only with describing data that can be manipulated and presented using other languages. To make this more clear, let’s take a look at some of the differences between XML and HTML.

Differences Between XML and HTML Because XML and HTML are both subsets of the SGML language, they resemble each other in several ways. However, their overall purpose differs. Many of the concepts that follow will be discussed more in depth in Chapter 2, “XML for ASP.NET Basics.”

Presentation Versus Description HTML was first designed to provide a way to present text-based information to a user located at a remote location. If you’ve worked with the Web very long, you probably remember the days when Web sites contained the standard gray background with black text. If you’re really “old” as far as Web years go, you may even remember using a Lynx browser. As the Web grew in popularity and became viewed as a novel way to present information to people around the world, alternative ways of presenting the data using graphics, tables, and other elements were incorporated into the language. These additions allowed for backgrounds and a host of other presentation capabilities. You probably remember the days of bright or wild-looking backgrounds with blinking text that was virtually impossible to read. What does all this have to with XML? Very little, actually, but there’s a reason for mentioning it. The point is that HTML is a presentation markup language that is useful only when combined with an application such as a browser. It has many predefined tags and attributes that can change font colors, make text larger, or place those lovely pink cloud backgrounds onto a page. However, HTML does nothing to describe the data that is presented. A page containing the following HTML code presents no clues about the data it contains: 274943494

What does 274943494 represent in the code? Is it a bank account number, a part number, a personal identification number, or none of the above? We have no way of knowing by looking at the HTML document because HTML only displays information, it doesn’t describe it.

XML and ASP.NET Development CHAPTER 1

274943494

Now it’s easy to see exactly what the data represents—data associated with a population. The data can further be described using other tags: 274943494

Now we know that the data is a population number associated with the United States.

Closing Tags HTML provides a lot of freedom in leaving tags open and even has some tags that never have to be closed. For example, in HTML, some tags can be left open without causing problems in the browser. Here’s an example of a few of them: •

•

•

•

•

•

•

Looking through these tags, you’ll notice that HTML doesn’t require a matching end tag for them. For example, placing an image into a page by using code such as isn’t correct in the HTML language. Other tags that normally require closing tags can sometimes get by without the closing the tag, too. In newer browsers, a tag listed without a closing tag may not even pose a problem to a Web page. Both Microsoft and Netscape’s browsers have moved toward being more forgiving of improper HTML coding. XML is not nearly as forgiving. Although we’ll talk more about this in Chapter 2, all XML tags must have a matching closing tag (or use a short-cut syntax that you’ll see later). Forgetting to close a tag will result in an error message being received when the document is parsed. This rule benefits the language because XML documents that are exchanged will all

1 XML AND ASP.NET DEVELOPMENT

By comparison, XML says nothing about how to display data. Its sole purpose is to describe the data using tags, attributes, and other items. The data found within the preceding HTML code snippet could be written the following way in an XML document:

9

10

XML for ASP.NET Developers

follow the same structure, making it easier for applications to use the data in a reliable and consistent manner.

Element Nesting Although it’s not a recommended practice, HTML tags can be improperly nested and still function properly. The following HTML code illustrates this: Text

XML strictly prohibits improper nesting of tags. If a given tag starts before another tag in an XML document, the tag that is declared first must end after the child tag, as shown next: Oak

Quoted Attributes HTML is very flexible in how attributes located within tags can be written. A browser will treat the following two code segments the same:

XML requires that all attributes be quoted:

Failure to follow this rule will result in an error generated by the XML parser.

Case Sensitivity XML also differs from HTML in how strictly case sensitivity is enforced. Although the following code is acceptable in HTML:

it is not acceptable in XML because the first tag name is declared with a small t and the second with a capital T. XML requires that a tag’s starting case match its ending tag’s case.

MSXML3 Versus the .NET Platform’s System.Xml Assembly The XML parser is responsible for going through an XML document and making sure it is well formed. When the XML document has an associated DTD or schema, the parser also makes sure that the document is valid. Both concepts are covered in the next chapter.

XML and ASP.NET Development CHAPTER 1

For ASP.NET, Microsoft has built a new parser from the ground up that handles just about any XML task imaginable. It is found within a .NET assembly named System.Xml. The chapters that follow cover topics related to the System.Xml assembly and others involving well-formed documents, valid documents, accessing documents using the Document Object Model (DOM) or an XmlReader, and transforming documents using Extensible Stylesheet Language Transformations (XSLT). Many examples and details about using the System.Xml assembly are presented throughout the book.

How Can XML Be Used by an ASP.NET Developer? The architects of .NET knew that XML integration was crucial to its success. As a result, XML is integrated directly into the platform. This integration is comprehensive and includes everything from working with data found in different data stores to serializing objects for use on remote systems. ASP.NET and its related .NET technologies offer a great opportunity to separate an application’s form from its function. No longer are you constrained to intermingling code snippets used to call objects among basic HTML code tags. When combined with XML, ASP.NET allows for the creation of applications that are more flexible, more efficient, and more manageable because the presentation code and business logic/events of applications can be separated. This flexibility also applies to working with data received from any number of data sources. Although you’ve always been able to work with the DOM through using the MSXML3 parser, converting data returned from a database into XML hasn’t always been intuitive or easy— especially if a custom XML structure is desired. As you’ll see in Chapter 8, “Leveraging ADO.NET’s XML Features Using ASP.NET,” XML is the basis for a new type of data object called the DataSet and is used ubiquitously throughout the .NET platform. For an ASP.NET developer, this provides an unprecedented level of power to exchange data not only between applications, but also between different objects that may be separated by firewalls and large physical distances. As browser and wireless device support for XML continues to increase, Web-based application development using XML and ASP.NET will provide easier and less code-intensive ways of

1 XML AND ASP.NET DEVELOPMENT

Microsoft’s MSXML3 parser performs all the preceding checks and much more. However, it was designed to work with “classic” ASP rather than ASP.NET. Although you can make calls to MSXML3 from C# or VB.NET via Interop (discussed in more detail in Chapter 6, “Programming the Document Object Model (DOM) with ASP.NET”), it is not recommended that you use MSXML3 if you want to fully leverage all the XML features found in the .NET platform.

11

12

XML for ASP.NET Developers

presenting data to end users. Transformations between XML and HTML via XSLT will be moved from the server to the client. Pages targeted for different devices can be served more effectively using an XML-based repository that can be transformed to fit the appropriate device using ASP.NET and XSLT. Doing this will provide the client with more speed because sorts, filters, and other functions can be performed without the need for a round-trip back to the server. The rise of Web services will allow XML-based data published by companies around the world to be consumed and placed within your ASP.NET applications. Credit cards can be processed and user IDs validated by passing XML fragments to and from remote servers. As an ASP.NET developer, you can leverage XML in many ways to provide needed services. Many of these are discussed in the chapters that follow.

Summary The XML language provides an extensible and powerful standard for describing data that can be used within and shared between applications. Although it looks a lot like HTML, the two languages have many differences. HTML serves the purpose of presenting data through an application such as a browser, whereas XML describes data using markup tags, but does not say how it should be presented. The next chapter takes a more detailed look at XML’s rules and structure. Understanding the basics of XML is necessary to create efficient ASP.NET/XML applications.

XML for ASP.NET Basics

IN THIS CHAPTER • What’s in an XML Document? 14 • Well-Formed XML Documents 16 • Valid XML Documents 20 • The XML Declaration 21 • XML Elements 24 • XML Attributes 25 • XML Namespaces 27 • XML Processing Instructions 34 • XML Comments 34 • XML Entities 35 • CDATA Sections 40 • Dealing with Whitespace 41 • The Relationship of XML to XHTML 42 • Using ASP.NET Objects to Generate XML 44

CHAPTER

2

14

XML for ASP.NET Developers

Now that you’re familiar with how XML came into existence and some of the ways it can be used, it’s time to learn how XML documents are created. You’ll be happy to know that many of the concepts employed in HTML and ASP.NET programming are applicable to XML document creation as well. Much like HTML, XML documents use various elements and attributes that provide the document with structure. However, elements and attributes aren’t used in marking up the data for presentation in a browser. They’re used to describe the data and perform other functions, many of which are detailed in later chapters. It’s important to note that XML by itself doesn’t provide much functionality other than the capability to describe data. XML is only one language in a family of other languages and technologies. It’s only when XML is combined with other languages and technologies (such as the .NET platform) that its power is realized in building applications. Before you learn about the other supporting technologies that work together to empower XML, you should take a good look at how XML is created and what rules are involved in this creative process. If you feel that you’re already an expert in creating XML documents, feel free to skip ahead to the next chapter. The list of topics shown at the beginning of the chapter provides an overview of what you can expect to learn. Although this list may seem somewhat lengthy, rest assured that you will be provided with plenty of samples and analogies to help you gain an in-depth understanding of each topic. By the end of the chapter, you should be able to create XML documents by hand or dynamically using intrinsic ASP.NET objects. Having said that, let’s get started!

What’s in an XML Document? “XML” has become one of the biggest buzzwords used in the technology industry today. Everywhere you look, vendors both large and small are integrating XML into their applications, with .NET being no exception. Database products are making it easier to retrieve and input XML data, and many e-commerce packages come with XML capabilities already built in. Employers are scrambling to find developers with XML experience to work with the variety of product offerings on the market. Because of the international scope of the XML “buzz,” you might expect XML to be a complex language requiring years and years of programming experience to work with and program. Fortunately, this is not the case, as you saw in Chapter 1, “XML and ASP.NET Development.” The creators of the XML specification knew that to have a platform-independent standard that was useful to individuals and businesses throughout the world, they would have to throw out many of the complexities associated with other languages. To see just how simple an XML document can be, take a look at Listing 2.1. You’ll notice right away that the code is understandable by normal human beings like you and me because it is

XML for ASP.NET Basics CHAPTER 2

15

simply a combination of different XML elements and data. Although some of the elements contained in the document may be confusing to you (until you read this chapter, anyway), it’s easy to see that the code contains no cryptic characters (although it could), adheres to a particular layout standard, is regular ASCII text, and looks a lot like the HTML markup language that you’ve likely used before. LISTING 2.1

/default/default.aspx Home About Us /calendar/default.aspx Events Calendar /news/default.aspx Press Releases /contact/default.aspx Contact Numbers

The XML document in Listing 2.1 is a very simple representation of a hierarchical menu structure that could exist on a company Web site. This simple menu (similar to the Start menu in Windows) contains two parent menu items named Home and About Us. The About Us menu item contains three children menu items (Events Calendar, Press Releases, and Contact Numbers). You’ll see how this XML can be used in an ASP.NET application in Chapter 6, “Programming the Document Object Model (DOM) with ASP.NET.” Although the actual data contained in the document, such as Contact Numbers (line 21) or Events Calendar (line 13) may not mean much on their own, by looking at the document you

2 XML FOR ASP.NET BASICS

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25:

A Simple XML Document

16

XML for ASP.NET Developers

can see that the Contact Numbers data represents the name of a menu item. You’ll also notice that data entries such as /contact/default.aspx are easily identified as being hyperlinks, even to people not familiar with what a hyperlink may look like. Code such as /contact/default.aspx

is a dead giveaway that the data within the tags must be related to a hyperlink in some manner. Although the tag could have been replaced with an tag, as seen in HTML, the data is described much better by using the word “hyperLink” don’t you think? The capability to describe data within an XML document, which was discussed in Chapter 1, is referred to as being “self-describing.” The XML menu structure shown in Listing 2.1 also gives us insight into what an XML document actually contains. Other than the data, an XML document contains a range of other items including elements, attributes, processing instructions, comments, and text to name a few. These items and others are discussed in the sections that follow. Before jumping into the different items found in an XML document, however, let’s take a look at some basic XML rules.

Well-Formed XML Documents As HTML has evolved over the years, browsers in general have become more and more lenient in how they handle incorrect coding. The following code isn’t well-formed HTML because the closing tag is missing:

Hello World

Viewing this code in Internet Explorer 4 or 5 is not a problem, because simple coding mistakes such as this non–well-formed document are forgiven. As XML was developed, it was realized that well-formed documents were essential for XML to be used consistently between applications. Imagine sending a document that was not well formed to a friend who had an XML parser that blew up when documents were not well formed! Your friend wouldn’t be able to open the document and use it in the manner that you had intended. Wait, you say. . .this type of thing happens all the time with HTML or Dynamic HTML (DHTML) in different browsers today, so what’s the big deal? Because XML documents must work consistently between parsers and applications, the creators of XML required strict conformance to a few basic XML principles. These principles include the following: • An XML document may contain only one root element. • All XML elements must have a closing tag.

XML for ASP.NET Basics CHAPTER 2

17

• All attribute values must be quoted. • Although XML elements may contain child elements, all elements must be nested correctly. • XML elements are case sensitive. • An XML document with an accompanying DTD or XML schema must contain items specified within the DTD or schema to be considered valid. If you’ve ever spent several hours (or more) attempting to make a particular DHTML application work correctly in Netscape and Internet Explorer, you know that having a strictly conforming language is a very good thing. Let’s cover some of the ground rules in more detail.

The XML document shown in Listing 2.1 makes it easy to visually identify the root element of the document because it’s actually named “root.” It could have just as easily been named “startingElement” if desired, because the actual name doesn’t matter. For XML parsers to have a reference point, an XML document must contain only one root element per document. Although the following code is acceptable:

Hello World

the next section of code is not acceptable, because it doesn’t have a single root element:

Hello World

Hello World2

The incorrect code could be remedied by adding in a root element as shown:

Hello World

Hello World2

XML FOR ASP.NET BASICS

The Root Element

2

18

XML for ASP.NET Developers

If you think of XML documents in terms of a tree, the root element is the root of the tree, and all other child elements are the branches and leaves of the tree.

Versus As discussed in Chapter 1, XML looks a lot like HTML at first glance. However, to adhere to the rules of creating XML documents, a few things that you’re used to doing in HTML won’t fly when you’re creating XML documents. In HTML we are all used to using tags such as , , , and

without ever worrying about closing them. In HTML it is perfectly acceptable from the browser’s point of view to code the following:

Hello World

To show the differences between HTML and XML, try running the following XML document in Internet Explorer 5+ and see what happens. To run it, enter the following code into Notepad and save the file as test.xml. Then open the file in Internet Explorer 5+ using the File, Open menu:

Hello World

After the document opens, you’ll receive an error stating something like End tag ‘root’ This error occurs because the XML parser can’t find the ending

tag. To prove this, run the following code (which closes the

tag) in Internet Explorer 5+ and you’ll see that the document loads fine:

does not match the start tag ‘p’. Line 4, Position 3.

Hello World

NOTE It’s important to note that the

tag as shown in the preceding XML document does not serve the same function as if it were used in an HTML document. Its use in the XML document is simply to describe the data Hello World. When you open the text.xml document in Internet Explorer 5, you’ll see that the

tag is actually visible and doesn’t add any type of formatting to Hello World, as would be expected in HTML. Remember that XML doesn’t specify how to format or display data (without using other technologies such as XSLT). It only organizes and describes the data. The

tag was used to show how you must close tags in XML, not because it has any special function or purpose, as it does in HTML.

XML for ASP.NET Basics CHAPTER 2

19

In cases where an XML tag contains no data or has only attributes (which you’ll learn more about later in this chapter), XML provides us with a handy shortcut:

This code is a less verbose way of handling the following code:

At this point, you may be wondering why this section is titled “ Versus .” Although the tag doesn’t actually mean “insert a line break” if used as an element within XML, you’ll see in a later chapter that it can be used with related XML technologies, such as XSLT or XHTML, to insert a line break. When used in this context, tags such as and must be closed to avoid errors being raised. Therefore, becomes and becomes . This may be a little confusing because you haven’t learned anything about XSLT yet. If you take away nothing more from this section than a knowledge that all tags must be closed in XML and its related technologies, then you know all you need to know for now. Future chapters build on this.

Nesting No-No’s By now you certainly have no doubt that XML tags must be closed for an XML document to be parsed correctly. Another “gotcha” must be followed as well. XML tags cannot be nested like HTML tags can. In HTML it’s possible, although not recommended, to code the following: Hello World

This type of inappropriate nesting within an XML document is strictly prohibited and will cause the parser to generate an error. To make this work with XML, you would need to fix the nesting: Hello World

To get away from HTML tags you already know (because does nothing except describe data in XML), here’s another improper nesting example that follows the same pattern as shown previously: About Us

2 XML FOR ASP.NET BASICS

Although the shortcut method may seem a little strange at first, after you’re comfortable using it, you’ll find that it’s great for saving time and space when you need to include an element that has only attributes (such as itemNumber in the preceding example) or that contains no data.

20

XML for ASP.NET Developers

The following is the proper way to code this section, assuming you want to list more than one element on a line: About Us

Because you have yet to see an XML document with more than one element on a line, you may be wondering if this is okay. The answer is a resounding “Yes!” The documents you’ve seen thus far have been indented and spaced simply to make them easier to read. They do not have to be created this way to work, but good luck trying to read them in the future without spacing and indentation!

Other Rules By now you’re probably sick of learning the rules and want to move on to something new. Don’t worry—we’re almost done. Two more important points need to be mentioned concerning case sensitivity and attribute quoting. Unlike HTML, in which is the same as is the same as , XML is case sensitive. All beginning and ending tags must be the same case. To continue using our menu metaphor, About Us will cause the parser to generate an error saying, End tag ‘Name’ does not match the start tag ‘name’. Determining what case to use is completely up to you. Because the parser normally tells you what the problem is, this is an easy problem to resolve, assuming that you pick a naming convention and stick to it. One final rule exists that may or may not be more difficult to remember, depending on how you code your HTML files. All XML attributes must be quoted for the parser to be able to parse the document. This means that the following HTML code would not be acceptable if it were written in an XML document:

This is easily fixed by adding quotes around the bgcolor attribute:

Because of the recent XHTML recommendation (covered later in this chapter) and because you will be working with XML more in the near future, it is highly recommended that you get into the habit of quoting all your HTML attributes. It will make the transition to XML and its related technologies much easier.

Valid XML Documents Now that you’ve learned all the rules associated with creating well-formed documents, let’s move on to discussing valid XML documents. Until now, you’ve seen examples of documents

XML for ASP.NET Basics CHAPTER 2

21

that allow for the inclusion of basically any element. Going back to Listing 2.1, if you wanted to include an element as a child of all tags, you could do so without causing any problems in the XML document.

To prevent this exact scenario from occurring, XML documents can be checked or validated against another document to make sure that the structure of the XML document is valid. This means that you can have an XML document that follows all the XML rules (and is thus well formed) but is invalid. How can this be possible? Enter the world of Document Type Definitions (DTDs) and XML schemas. To allow for validation of XML documents, a type of “metadata” document can be created to define what elements, attributes, and other items can be contained within the XML document. By defining the structure of the XML document, the problems described in Chapter 1 with the imaginary supplier can be prevented because the application can validate the document before performing any calculations or transformations. Because DTDs and XML schemas cannot be summarized in just a few paragraphs, you’ll learn about them in greater detail in Chapter 4, “Understanding DTDs and XML Schemas.” Now it’s time to cover the specifics on items used to construct an XML document.

The XML Declaration ASP.NET provides developers with directives that can be declared at the top of each ASP.NET page. Directives allow a developer to specify what language the ASP.NET page will use, whether sessions will be used on a given page, whether the page supports transactions, and many other items. See the ASP.NET help section in the .NET SDK for information on other valid directives. The following are a few examples of some ASP.NET directives. Because it’s probable that you are already familiar with these, we won’t discuss their purpose:

2 XML FOR ASP.NET BASICS

The freedom to add any desired element to an XML document probably sounds like a pretty good feature, and it is in certain circumstances. However, imagine creating an application that manipulates an XML document received from a particular supplier. This application is programmed to work with a specific XML document that is assumed to contain a consistent set of elements and attributes. What happens if the supplier starts adding in elements that your application isn’t expecting? The supplier’s “freedom” to add in new elements may cause your application to malfunction, crash, or simply report incorrect data.

22

XML for ASP.NET Developers

XML declarations function in a manner similar to ASP.NET directives. You already saw your first XML declaration back in Listing 2.1 even though you didn’t realize it at the time. The XML declaration shown there was

An XML document can be loaded using Microsoft’s System.Xml assembly (discussed in Chapter 6), even if the declaration is omitted from the document. However, each XML document should have a declaration so that information about the document can be viewed at any time—both by humans and parsers. This will especially be true in the near future as different versions of the XML specification are released. Several key points need to be made about the XML declaration, including • The xml keyword • The version of the XML document • The document encoding type • The standalone keyword

The xml Keyword The most important point to make about using the xml keyword is that it’s reserved in the XML language and must be lowercase. You cannot use it as a name of an element or anything else you create in an XML document without an error being thrown. Also, no whitespace can exist between the first question mark and the xml keyword. If whitespace does exists, an error will be raised by the parser. Incorrect:

Correct:

The XML Document Version Aside from the xml keyword, the previous declaration also shows the version as “1.0”. As the World Wide Web Consortium (W3C—http://www.w3.org) XML recommendations continue to be issued, the version will be changed so that parsers can detect an XML document’s version. For now, however, the version is 1.0. Having access to the version of an XML document means that conditional actions can be performed on the document, depending on the version number.

The Encoding Type The XML declaration we’ve been working with also lists the encoding type of the document. The simple document lists an encoding type of “UTF-8”, which is the default encoding type if none is listed in the declaration.

XML for ASP.NET Basics CHAPTER 2

23

Before expounding on the different encoding types, it’s worth mentioning how computers store text. A computer doesn’t actually store text as text, which may sound a little confusing. Rather, it converts the text into a number or group of numbers that the computer recognizes as representing the text. Therefore, one particular computer may store a numerical representation of the text differently than the same text on another computer. To avoid problems that could potentially arise from different numeric representations of text on computers, XML documents can specify how the document text is encoded. By doing this, a computer receiving an XML document knows what encoding type to work with and can make the appropriate transformation to read the document.

Entire books have been written about Unicode and bit-shifting techniques, so this subject will be covered only from a high-level perspective. The important point to take away from this discussion is that many encoding types are available. But, the XML 1.0 Recommendation specifies that all XML parsers must support the UTF-8 and UTF-16 encoding types. Sticking to one of these types should help prevent problems that arise from exchanging XML documents between differing computer systems. An excellent article that gives an in-depth look into the subject of XML encoding was written by Microsoft. You can find it at http://msdn.microsoft.com/xml/articles/xmlencodings.asp.

The standalone Keyword We briefly touched on the subject of DTDs earlier in the chapter. As mentioned previously, you’ll learn more about these documents and XML schemas in Chapter 4. The optional standalone keyword simply tells the XML parser whether the current XML document can survive on its own or if it is dependent on another document (such as a DTD). Although the standalone type was declared in the XML document shown in Listing 2.1, the document would have defaulted to “yes” anyway had this not been specified. Although it is optional, if you had created a DTD (a document describing what your XML document can contain) that went along with this XML document, you could have used the following XML declaration:

XML FOR ASP.NET BASICS

This transformation process works because of character encodings developed by the Unicode Consortium (http://www.unicode.org). To account for some older systems not being able to read Unicode, the Unicode Transformation Formats (UTF) were developed. XML documents default to the UTF-8 character encoding that uses single-byte encoding and Character Entities. UTF-16 is a two-byte encoding standard that is needed to accommodate a large number of characters such as those found in the Japanese or Chinese languages. Several other encoding standards, including ISO-8859-1 and Shift_JIS, map to different encoding types.

2

24

XML for ASP.NET Developers

XML Elements The , , , and tags found in the HTML language are all examples of HTML elements. Each has a special meaning and function that different browsers understand. Your familiarity with HTML makes understanding XML elements very straightforward and easy, especially when you consider that an XML element is simply a container, like many of the HTML elements you’re used to working with. Listing 2.2 shows a few XML elements that you’ve seen before. LISTING 2.2

XML Elements

1: 2: 3: /default/default.aspx 4: Home 5:

The element shown in Listing 2.2 is a parent to the and elements. As described earlier in the chapter, each element tag must be closed for an XML document to be considered well formed. An XML element isn’t defined as only the tag itself. It includes all other subelements or content between the element’s starting and ending tags. This content is referred to as the “Content Model” of the element. This means that the element shown in Listing 2.2 is defined as containing the starting and ending tags as well as the and tags. The W3C XML 1.0 Recommendation allows document authors to name XML elements as they would like. However, the elements must start with a character from A–Z or a–z or may start with the ”_” character. Therefore, the following are all legal elements as defined by the W3C: red adult bike Woman’s 100.99

Whereas the following are not legal elements: red adult bike Woman’s 100.99

XML for ASP.NET Basics CHAPTER 2

Failure to follow the naming rules will result in an error similar to A

25

name was started with

an invalid character.

XML Attributes To continue with our HTML/XML comparisons, an attribute in XML is very similar to an HTML attribute: the attribute helps describe an element. In HTML you can change the color attribute to the element: Some Text

Some Text

In this XML example, itemNumber is an attribute of the element. You’ll notice that itemNumber’s value is quoted. Whereas in HTML you can get by without quoting attribute values, the XML rules require that all attribute values are quoted. Failure to follow this rule will result in an error being raised by the parser. The strict naming conventions applied to naming elements also apply to naming attributes in XML. Attribute names must start with a character from A–Z or a–z, with the exception of the “_” character. Failure to follow the naming rules will result in an error similar to A name was started with an invalid character. When to use attributes in an XML document is completely up to you. Some XML programmers use attributes rather than elements because they can take up less space and are quicker to add to an XML document. For example, Listing 2.3 shows a recordset obtained from a database converted to XML using only XML elements, whereas Listing 2.4 shows the same conversion but with attributes used where possible. LISTING 2.3

XML Recordset with Elements Only

1: 2: 3: 4: 1 5: Dan Wahlin 6: 1234 Any Street 7: 8: 9: 2 10: Aaron Horne 11: 3564 Any Street 12: 13:

2 XML FOR ASP.NET BASICS

In XML you can follow the same guidelines:

26

XML for ASP.NET Developers

LISTING 2.4

XML Recordset with Attributes and Elements

1: 2: 3: 5: 7:

As you can see from the code in Listing 2.4, using attributes to describe data can result in smaller file sizes and may be considered by some to be easier to read. Whether attributes are used is completely up to you. A good general rule to follow is that if data describes an element in XML, it may be a good candidate for an attribute (although it doesn’t have to be). For example, if you have an element named house and want to describe its color, you may want to make color an attribute. Thinking in terms of object-oriented programming, an attribute is similar to an object property. If you realize that you’ve defined an attribute in your XML document that may actually need to contain child elements of its own, the attribute should be changed to an element because attributes cannot contain child elements. For example, the following XML document contains an attribute named fname:

What if the fname attribute actually needs to describe the birth name and nickname of an individual? You could always delimit the two values with a pipe character, but this would defeat the purpose of XML. Instead of doing this, you would want to break fname out as a child element of the name element: Daniel Dan

You could make birthName and nickName attributes of fname

as well:

XML for ASP.NET Basics CHAPTER 2

27

XML Namespaces

One of the easiest ways to see why namespaces are needed in XML is to look at a more abstract example. If I asked you where the phone number 669-5835 called to, what would be your response? More than likely, you would say something like, “I have no idea because you didn’t even supply an area code!” Now, what if I asked you where the phone number (480) 669-5835 called to? Although you might not know the individual residence or business this number called, with a little research you would be able to learn that this calls a number located somewhere in the Phoenix, Arizona metropolitan area. The area code helped determine who, or in this case where, the number was associated. Now that you’ve seen a more abstract example, let’s take a look at another that ties into XML more directly. Part of XML’s inherent power lies in its capability to describe data through creating custom tags. This can present problems because of name collisions, as the following scenario illustrates. Company A sends Company B an XML document containing data about A’s customers. Company B combines its own XML document with Company A’s document and updates a database with the combined information. Both documents contain an element named customerID. Company A’s customerID element contains a unique customer identifier generated by its computer systems. This number can be stored “as is” in the database with no manipulation. Company B’s customerID element contains the customer’s Social Security number, including dashes. Before inserting this value into the database, all dashes must be stripped out. Listing 2.5 shows Company A’s XML document and Listing 2.6 shows Company B’s XML document. LISTING 2.5

Company A’s XML Document—Unique Identifier

1: 2: 3: 4: 111111111

2 XML FOR ASP.NET BASICS

Namespaces are an important part of the XML language, especially because developers can create their own element tag names in an XML document. A namespace allows tags with the same name to be distinguished based on who created the tags and what the tags are meant to describe.

28

XML for ASP.NET Developers

LISTING 2.5

continued

5: Wahlin Consulting 6: 1234 Any Street 7: 8: 9: 111111112 10: Warehouse Central 11: 3564 Any Street” 12: 13:

LISTING 2.6

Company B’s XML Document—Social Security Number

1: 2: 3: 4: 528-11-1234 5: Dan Wahlin 6: 1234 Any Street 7: 8: 9: 123-22-1234 10: Lamar Kirby 11: 3564 Any Street 12: 13:

Reading through this sample scenario, you can see how combining Company A’s and Company B’s XML documents may create a problem when the database needs to be updated. Because both companies use the customerID element in a different way for describing their data, and because Company B has a business rule stating that customer Social Security numbers must be stored without dashes in the database, it will be very difficult to distinguish from which company the customerID element came. This will make it difficult to know when to apply Company B’s business rule. To complicate this more, what if Company A’s name element was actually describing where a particular part was manufactured, whereas Company B’s name element was the actual customer name? The resulting ambiguity could make document exchange between the companies difficult and could complicate application development. To simplify this process and allow elements of an XML document to be uniquely identified and associated with the appropriate creator, the W3C recommended XML namespaces. As you will see, namespaces help to eliminate the guesswork that occurs when different companies, or

XML for ASP.NET Basics CHAPTER 2

29

even different departments within the same company, use element or attribute names that are the same but have different meanings.

Namespace Structure Namespaces are easy to implement in an XML document after their structure is known and understood. Before discussing namespaces in more detail, it’s important to know that all items within an XML document are by default part of a namespace. This is because the reserved keyword xml is associated with its own native namespace.

• Default Namespaces • Qualified Namespaces

Default Namespaces The following code shows a default namespace being applied to the element: /news/default.aspx Press Releases

The preceding default namespace starts by using the keyword xmlns, which is shorthand for “XML Namespace.” Because it is declared in the root of the XML document, it applies to all content contained between the beginning and ending tags. We can say that its scope is “global” to the XML document because it applies to everything from the root down (or the root up, if you think in terms of a tree structure). The xmlns keyword is set equal to a Universal Resource Identifier, or URI, which in this case is “http://www.anyURL.com”. The URI can be any unique identifier and does not have to be a hyperlink. I could have just as easily specified xmlns=”myBusiness” if I had wanted to. However, this wouldn’t be very efficient or unique because someone else could use “myBusiness” as the URI for a namespace in their XML document. The best bet when deciding on URI identifiers is to use your Web site URL followed by a particular path (http://www.anyURL.com/myNamespace); it is unique and therefore unlikely that someone else will use that same URL, especially because they have no ownership of it.

2 XML FOR ASP.NET BASICS

So that you gain a good understanding of namespace structure and types, let’s take a look at code samples involving the following namespaces, which comply with the W3C’s January 1999 Namespace Recommendation (http://www.w3.org/TR/1999/REC-xml-names19990114):

30

XML for ASP.NET Developers

The URL does not actually have to point to a real file. This is a difficult concept to grasp at first. After all, why list a URL for the namespace URI if it doesn’t actually point to a file? To answer this, realize that the URI is simply a unique identifier and that URLs work well in this situation because they are unique to start with. In the previous example, the root element contains the following definitions: URI = “http://www.anyURL.com” Local name = “root”

The , , and elements are associated with the following definitions, respectively: URI = “http://www.anyURL.com” Local name = “menuItem” URI = “http://www.anyURL.com” Local name = “hyperLink” URI = “http://www.anyURL.com” Local name = “name”

You can see that the default namespace’s ”scope” is everything within the XML document in this example because all elements inherited the URI of “http://www.anyURL.com”. From the preceding definitions, you can also see that each element’s name is referred to as its Local name. To better understand the scope of default namespaces, let’s run through a simple example involving a variable in ASP.NET. Let’s assume that you have an ASP.NET page with a variable named menuItem declared at the top of the page. This variable is assigned a value of “Contact Us”. The variable is not declared within a function, so it has a global scope as far as the page is concerned. Because of the global nature of the variable, we can access its value from anywhere in the page. Now let’s apply this same ASP.NET variable example to the default namespace example shown next: /news/default.aspx Press Releases

Because the default namespace declaration is “declared” at the root, all content within the XML document will inherit this default namespace. This falls in line with the global menuItem variable described in the ASP.NET example. Let’s see what happens if a default namespace is declared in the menuItem tag, as shown next:

XML for ASP.NET Basics CHAPTER 2

31

/news/default.aspx Press Releases

The default namespace will apply to everything contained within the beginning and ending tags. This says that the default namespace for the and tags is now associated with the declared URI “http://www.anyURL.com” The root tag will not be a part of this namespace because it isn’t within the beginning and ending tags.

Qualified Namespaces Although default namespaces are certainly useful when an element and all contents within it share the same namespace, situations may arise when some of the contents within an element come from a different namespace. Listing 2.7 shows an example. LISTING 2.7

Working with Different Default Namespaces

1: 2: 3: 4: 5: /news/default.aspx 6: 7: Press Releases 8: picture.jpg 9: 10:

From the preceding example, you can see that the and elements are associated with the “http://www.myCompany.com” default namespace. As you learned earlier, the scope of this namespace normally includes everything that is contained within the beginning and ending tags (remember the ASP.NET function comparison). In this example, however, the and subelements belong to the “http://www.another Company.com” default namespace. Because each of these subelements has its own default

XML FOR ASP.NET BASICS

This local scope (local to the tag) is similar to moving our menuItem variable declaration in the previous ASP.NET example into a function. Moving it within the function makes the variable’s scope local to the function. Anything outside of the function cannot see or access the variable unless a call is made to the function and the variable’s value is returned. A similar process is occurring in the previous XML code. If we treat the tag like our ASP.NET function, the same type of scope applies with respect to the default namespace: xmlns=”http://www.anyURL.com”.

2

32

XML for ASP.NET Developers

namespace defined, the namespace declared for the element that normally trickles down is overridden. Although the code shown in Listing 2.7 is one potential way of declaring the two namespaces, what would happen if 10 (or 1000, for that matter) other elements were associated with the “http://www.anotherCompany.com” namespace? If a change is made to the namespace URI, implementing the change requires that each of the 10 elements are updated. As an ASP.NET developer, this should raise some red flags. What if a specific namespace needs to be applied to the itemNumber attribute only? Default namespaces do not allow for this because they apply to all content within the element in which they are declared. To combat these problems, the qualified namespace was developed. A qualified namespace allows for namespaces to be specifically applied to individual elements (and other XML items such as attributes) rather than having the namespace trickle down as you’ve seen with default namespaces. To make this more clear, Listing 2.8 shows an example that uses a qualified namespace. LISTING 2.8

A Qualified Namespace Example

1: 2: 3: Some Text 4:

In Listing 2.8, the namespace URI (“http://www.anotherCompany.com”) is associated with a prefix named another and a local name of menuItem. Used in this manner, the prefix (another) serves as a qualifier for the namespace. This means that the namespace applies only to elements that have their name prefixed with another. Thus, the element does not belong to the qualified namespace even though the namespace was declared within the element. The element is a part of the namespace because its name is prefixed by the word “another.” What about the itemNumber attribute? Is it part of this qualified namespace? No, it is not prefixed with the another namespace prefix, so it is considered to be in “no namespace” or “locally scoped.” However, because attributes are used to describe elements, “locally scoped” when used in this context simply means that the attribute is identified by the element that it is describing, which of course does have a namespace prefix. The following code segment reworks Listing 2.7 using a combination of default and qualified namespaces: /news/default.aspx Press Releases picture.jpg

Keep in mind that because attributes are always associated with specific elements, it’s not normally necessary to associate them with a namespace, because the namespace association can be inferred from the element that they are describing.

TIP As you read through the previous namespace examples, you may have wondered how to clear a namespace after it was declared. For example, if a element declared a default namespace, how can that namespace be cleared if you don’t want it to apply to a particular subelement? Going back to our ASP.NET comparisons, namespaces can be cleared in the same manner as string variables declared in an ASP.NET page—by setting the variable equal to empty quotes: variableName = “”. To apply this same principle to clearing a default namespace, simply set the namespace URI equal to empty quotes: .

Referring back to the problem that arose when XML documents from Company A and Company B were merged, the customerID elements from each company could easily be identified correctly by prefixing them with a qualified namespace or by defining a default namespace for each XML document. The following example shows how Company B’s document could be rewritten using a qualified namespace so that naming conflicts associated with the customerID element are eliminated: 528-11-1234 Dan Wahlin

2 XML FOR ASP.NET BASICS

The default namespace (“http://www.myCompany.com”) applies to the , , and elements. The qualified namespace (“http://www.anotherCompany.com”) applies only to the and elements, which override the default namespace. If you had wanted to include the itemNumber attribute in the qualified namespace, you could have done so with the following code segment:

34

XML for ASP.NET Developers

1234 Any Street 123-22-1234 Lamar Kirby 3564 Any Street

Namespaces are not always needed in an XML document, but in situations like the preceding one shown with Company A and Company B, many problems can be alleviated by using them.

XML Processing Instructions Remember our earlier discussion on the XML declaration? You didn’t know it then, but that declaration is actually one form of an XML processing instruction (PI). PIs are useful in letting parsers know how a particular document should be processed. The following PI lets the parser know to process the document as XML version 1.0 with an encoding type of UTF-16:

PIs can also be used when you want a particular action to be taken by one parser but ignored by another. For example, assume that a parser looks for a PI that tells it to copy the current XML file to a network folder and rename it. Assuming a parser is capable of performing this functionality, the PI to accomplish this task may look like the following:

Although the exact instruction to perform this task would of course be dependent on the parser, you can see that all PIs start with the characters. PIs can be very useful when multiple parsers will parse a given document. Processing instructions allow each parser (RTF, CDF, XML, and so on) to perform specific functions without causing problems in other parsers.

XML Comments XML comments are the same as HTML comments. Although I personally prefer commenting single lines of code using the single apostrophe (‘) as in Visual Basic or the // notation found in C#, XML comments are just as easy to use when commenting out large sections of code. Back in Listing 2.1, you saw the use of XML comments:

Although this was a very simple example of adding helpful comments to an XML document, comments can also be used to comment entire sections out of an XML document, as shown in Listing 2.9.

XML for ASP.NET Basics CHAPTER 2

LISTING 2.9

Adding Comments to XML

Home About Us /calendar/default.aspx Events Calendar /news/default.aspx Press Releases /contact/default.aspx Contact Numbers -->

Line 4 of Listing 2.9 starts the comment off by using the characters signal to the parser that the comment has ended. Any XML content found between the comment tags will be ignored by the parser.

WARNING If any data within a commented section of code contains the -- characters, the parser will throw an error saying, Incorrect syntax was used in a comment. An entity should be used to represent these characters if they exist within the data found in an XML document. Entities are discussed in the next section.

XML Entities Back in the old days (you know. . .1994 or so) when I was first learning HTML, I had a hard time remembering what characters needed to be put into an HTML document when I wanted several spaces to show up in a browser. Having had many years of practice, my brain has finally remembered (hopefully permanently) that the HTML character entity represents

2 XML FOR ASP.NET BASICS

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22:

35

36

XML for ASP.NET Developers

a space to the browser. As you are aware, HTML allows for a variety of characters to be inserted into a Web page. For example, the HTML entity © represents the © character, whereas the HTML entity ® represents the ® character. XML leverages entities in a similar manner as HTML. XML uses the < and > characters to mark up an element, which can cause problems when these characters exist in the data. To see this problem in action, try loading the following XML document in Internet Explorer 5 or later: 1 < 2

You’ll see that the parser generates an error saying Whitespace is not allowed at this location. At first glance, this error doesn’t seem to relate to the insertion of the < character into the data. However, if you remember the discussion on XML element naming, you will recall that element names cannot start with a space. The error is being generated because the parser thinks that a new element is being started and the element name starts with a space. Situations such as these involve Standard Entities.

Standard Entities How can the preceding problem be solved? The answer is to take advantage of Standard Entities defined in XML. These entities have a similar structure to the ones found in HTML. Take a look at Table 2.1 to see the characters and their entity references. TABLE 2.1

XML Standard Entities

Character

Entity Reference

<

<

>

>

“

"

‘

'

&

&

Using the Standard Entity reference for the < character, we can fix the error that occurred when the previous XML document was loaded: 1 < 2

XML for ASP.NET Basics CHAPTER 2

37

Although < shows in the XML document source code, when the document is parsed, the < character appears in the output. Why does this happen? Just as the browser converts to a space, the XML parser will convert any entities that it recognizes into their appropriate character representations.

Character Entities

An interesting point about this example is that if you leave the preceding code exactly as is but substitute a physical space for the entity, Internet Explorer 5 or greater will show the following when the XML file is opened:

What happened to the space? Right-click the document, choose View Source, and you’ll see that the space is actually there. However, because it was not specified that the space within the element needed to be “preserved,” the parser treated the element as if it were empty. We’ll talk more about handling whitespace a little later in this chapter. Getting back to Character Entities—if it is necessary to insert the ® character into XML data, the ® general entity can be used. The following is an example: ®

If you’re wondering how you can know what Character Entities exist, you can easily see all the values by running the ASP.NET script shown in Listing 2.10 (increase the upper bound of i as necessary):

2 XML FOR ASP.NET BASICS

Character Entities look a lot like Standard Entities but allow for the display of characters typically not found in the 7-bit ASCII character set or on the majority of computer keyboards in the world. A little earlier you took a look at how a space could be inserted into a Web page using the entity. What happens if you want to insert a space into your XML data? You can do so easily by using a Character Entity:

38

XML for ASP.NET Developers

LISTING 2.10

Character Entity ASP.NET Script

1: 2: private void Page_Load(Object sender, EventArgs e) { 3: Response.Write(“

”); 4: Response.Write(“”); 5: for (int i=1;i syntax. Because we haven’t discussed DTDs, you’ll get your first taste of them by seeing an “internal” DTD that is used to define the companyName entity:

Running this document in Internet Explorer 5 will result in the &companyName; entity being replaced with the text Tomorrow’s Learning.

External Entities External Entities function in the same manner as Internal Entities from the XML document’s perspective. The entity name (wrapped with & and ;) is placed in the XML document and is replaced with whatever text was specified by the External Entity declaration when the document is parsed. The difference between the Internal Entity and External Entity is where the entity definition occurs. With an External Entity declaration, the entity declaration is made outside of the DTD in a separate file. Here’s an example of an External Entity declaration. The actual definition would occur within the DTD:

This declaration names the entity just like the Internal Entity did but then defines the declaration as a SYSTEM entity. This information is followed by the path to the declaration file containing the entity’s information. External Entities can even point to other XML files. This can be very useful in situations where multiple departments all make small contributions to a “master” XML document. Each department maintains its own XML document and these “mini” documents are pulled into one main XML document through the use of External Entities.

2 XML FOR ASP.NET BASICS

http://www.TomorrowsLearning.com &companyName; /location/default.aspx Location of &companyName;

40

XML for ASP.NET Developers

Parameter Entities Updating information that is located in one place makes maintenance of XML documents easier and more efficient. What if a DTD contains repeated sections, though? Wouldn’t it be nice to able to declare these sections once and then reuse them throughout the DTD? Parameter Entities accomplish this exact task through a syntax that is very similar to Internal and External Entity declarations. The declaration syntax differs from the previously discussed entities only in the use of a % character followed by a space:

This Parameter Entity declaration can then be used within the DTD by preceding the entity name with % and ending it with ;: %companyName;

Although both character and parameter entities are defined in a DTD, the parameter entity can be used only within the confines of the DTD itself. It cannot be used in an XML document like character entities can. Chapter 4 contains a more in-depth discussion of DTDs.

CDATA Sections There will invariably be times when the data you want to include within an XML document contains characters that may cause the parser to fail. Earlier you saw that when the < character was placed into the data, the parser was tricked into thinking that a new element was starting. As a result, it generated an error. Aside from using entities to prevent the parser from failing, as shown earlier, the XML language also includes the character data (CDATA) section to allow data such as the < or & characters to be included without causing problems when parsed. CDATA sections are unparsed by the XML parser and treated as text or “character data.” Their content is simply passed through the parser untouched. To gain a better understanding of how CDATA sections are handled by the parser, let’s first take a look at an ASP.NET page with embedded HTML:

Hello World

]]>

2

42

XML for ASP.NET Developers

remain in the data. Through using this alternative, you can avoid resorting to CDATA sections or entities. What is the alternative? The xml:space attribute. This special attribute can be set equal to “default” or to “preserve”, as shown next:

Hello World

By setting the xml:space attribute to “preserve”, all whitespace within the element’s data will be left untouched by the parser. Setting the attribute to “default” allows the parser to strip the data of any excess whitespace. Use of this attribute is normally reserved for data that contains whitespace that needs to be left alone, such as with a poem.

NOTE Internet Explorer 5 or later does not honor the xml:space attribute by default. When developing client-side code using MSXML (or MSXML3), you can turn this feature on by setting the preserveWhiteSpace property to true.

The Relationship of XML to XHTML On January 26, 2000 the W3C released a recommendation for ”Reformulation of HTML 4 in XML 1.0,” referred to as Extensible Hypertext Markup Language or XHTML (http:// www.w3.org/TR/xhtml1/). You’ll be happy to know that the rules associated with version 1.0 of the XML specification also apply to XHTML, so you do not have to learn a whole new markup language to use XHTML. Although neither Netscape nor Microsoft specifically supports XHTML in their browsers, you can start using it today. The XHTML specification makes the following points about the benefits of migrating from HTML to XHTML: • XHTML documents are XML conforming. As such, they are readily viewed, edited, and validated with standard XML tools. • XHTML documents can be written to operate as well or better than they did before in existing HTML 4-conforming user agents as well as in new, XHTML 1.0-conforming user agents. • XHTML documents can utilize applications (for example, scripts and applets) that rely on either the HTML DOM or the XML DOM. • As the XHTML family evolves, documents conforming to XHTML 1.0 will be more likely to interoperate within and among various XHTML environments.

XML for ASP.NET Basics CHAPTER 2

43

• Document developers and user agent designers are constantly discovering new ways to express their ideas through new markup. In XML, it is relatively easy to introduce new elements or additional element attributes. The XHTML family is designed to accommodate these extensions through XHTML modules and techniques for developing new XHTML-conforming modules (described in the forthcoming XHTML Modularization specification). These modules will permit the combination of existing and new feature sets when you’re developing content and designing new user agents.

Now that you’ve seen the benefits of XHTML, you may be wondering how it differs from HTML. Although the tags are basically the same, all XHTML tags must be closed, nested, and cased properly for the XHTML document to be well formed. Attributes must be quoted, must have an associated value, and cannot be defined more than once on the same element. For example, the selected attribute shown next is incorrect if XHTML rules are being followed: ASP.NET

To make this XHTML compliant, the selected attribute must have a value that is quoted: ASP.NET

A complete discussion of these rules and many others was given earlier in this chapter. As its name implies, XHTML is extensible. With HTML you cannot introduce a new tag unless the device that renders it understands the tag. With XHTML, modules can be created that tell the device how to work with a custom tag. This allows devices such as Internetenabled phones to work with a “down-sized” XHTML module that is geared toward lower memory consumption, and it allows more powerful applications to work with “extended” XHTML modules that may include custom tags. In general, XHTML is much more flexible, efficient, and extensible than HTML because of modularization. For more information on XHTML modules, visit: http://www.w3.org/TR/2001/REC-xhtml11-20010531/. So what does an XHTML document look like? Actually, it’s very similar to the HTML documents you’re used to working with except that it follows the XML rules. A simple XHTML document is shown next:

2 XML FOR ASP.NET BASICS

• Alternative ways of accessing the Internet are constantly being introduced. Some estimates indicate that by the year 2002, 75% of Internet document viewing will be carried out on these alternative platforms. The XHTML family is designed with general user agent interoperability in mind. Through a new user agent and document-profiling mechanism, servers, proxies, and user agents will be able to perform best-effort content transformation. Ultimately, it will be possible to develop XHTML-conforming content that is usable by any XHTML-conforming user agent.

44

XML for ASP.NET Developers

My First XHTML Document

Hello World!

This document starts with the XML declaration, which is followed by one of three possible DTDs. These include a traditional (most of the general public will use this), a strict (allows for “cleaner” markup without including layout tags), and a frameset DTD (used with frames), as shown next:

Aside from the DTD, you’ll notice that a global namespace is also included on the HTML element along with two language attributes. Because XHTML documents follow the XML rules, parsers can treat them as regular XML documents. This provides a lot of power and flexibility when different XML languages such as XLink and XPointer are used (discussed in Chapter 3, “XPath, XPointer, and XLink”) to access specific portions of an XHTML document. Because XHTML is available for implementation today, you should begin creating all HTML documents in a manner that makes them XHTML compliant.

Using ASP.NET Objects to Generate XML At this point, you’re probably anxious to put some of the XML basics that you have learned to work. Keep in mind that although the content up to this point hasn’t been what you might consider exciting, the concepts you learned are very important in building XML applications that are both functionally and programmatically correct. Having a thorough understanding of XML will help prevent many hours of debugging down the road.

XML for ASP.NET Basics CHAPTER 2

45

Because we haven’t discussed the XML parser built in to the .NET platform yet, the sample application that follows uses what you already know to construct an XML file on-the-fly, based on user input. By the end of the application, you’ll understand why a parser would make things a lot easier. Before getting too far into the application code, let’s discuss it in more detail.

Application Specifics

Let’s assume that the business requirements specify that there will be a maximum of 25 bid requests a week and that after the workflow is started, bid requests need to be stored in an XML file, which will be used throughout the workflow process. At the end of each month, this XML file will be imported into a proprietary database using a batch process already in place.

Creating the Application This application can easily be constructed using standard IO classes built into the .NET platform. Because we haven’t covered creating XML documents using an XML parser yet, these objects provide a viable solution. However, in future chapters you’ll see how to accomplish the same task more efficiently using an XML parser. To start, let’s create an ASP.NET page named default.aspx and place it within a virtual directory (any virtual directory having “write” permissions will do). In case you’re not familiar with virtual directories, they are a name alias (you can name them anything you’d like) that represents a path to a physical directory on your hard drive. To set up a virtual directory in Internet Information Server, consult the IIS documentation. The default.aspx page contains the following pieces of functionality: • Data Entry • XML Document Creation/Appending • XML Document Viewing The data entry section is basic HTML, so the specifics involved in creating it won’t be covered. We’ll assume that the various form element tags are named properly according to the application’s business rules. Listing 2.11 shows the code that processes the form after it has been submitted by the user. The entire file can be found in this chapter’s code as Listing 2.11.aspx.

2 XML FOR ASP.NET BASICS

The application’s purpose is to allow department heads to submit job bid requests for information technology contractors. Upon submitting a request, the real-world version of the application would start a workflow and provide a lot of other functionality that won’t be covered in this sample.

46

XML for ASP.NET Developers

LISTING 2.11

Code Used to Create or Append Information to an XML Document Using Standard ASP.NET Classes 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43:

string rootTag = “root”; public class CreateXmlFile { HttpRequest Request = null; public CreateXmlFile(HttpRequest ServerRequest) { //Overload Constructor when request object is needed Request = ServerRequest; } public CreateXmlFile() {} public string writeXML(string root,string node,string recordID, string version,string fileName,bool writeEndRoot,bool writeAtts){ bool blnExists = false; StreamWriter writer = null; string pathFile = getPath(fileName); //See if the XML file already exists blnExists = File.Exists(pathFile); if (!blnExists) { //Create the file since it doesn’t exist writer = new StreamWriter(File.Open(pathFile, FileMode.Create, FileAccess.Write)); writer.WriteLine(“”); writer.WriteLine(“”); } else { writer = new StreamWriter(File.Open(pathFile, FileMode.Append, FileAccess.Write)); } writer.WriteLine(“”); } else { writer.Write(“\” “); } foreach (string x in Request.Form) { if (x.ToUpper()!=”SUBMITBUTTON” && x.IndexOf(“_”) != 0) { if (!writeAtts) { writer.WriteLine(“” + Request.Form[x] + “”); } else { //Write out as attributes writer.WriteLine(x + “=\””+Request.Form[x]+”\” “); } } }

XML for ASP.NET Basics CHAPTER 2

LISTING 2.11

continued if (!writeAtts) { writer.WriteLine(“”); } else { writer.WriteLine(“/>”); } if (writeEndRoot) { writer.WriteLine(“”); } writer.WriteLine(); writer.Flush(); writer.Close(); return “”; } public string ReadFile(string file,bool bGetPath) { //Create the File System Object and txtfile string filePath = “”; string fileOut = “”; StreamReader reader = null; filePath = bGetPath?getPath(file):file; try { reader = new StreamReader(File.OpenRead(filePath)); fileOut = reader.ReadToEnd(); //Can be expensive } catch (Exception e) { fileOut = “There was an error: “ + e.ToString(); } finally { if (reader != null) reader.Close(); } return fileOut; }

private string getPath(string file) { string path = Request.ServerVariables[“PATH_TRANSLATED”]; path = path.Substring(0,path.LastIndexOf(“\\”)+1) + file; return path; } } //End Class public void submitButton_Click(Object Sender, EventArgs E) { string output = “”; string ID = Request.Form[“dateTime”]; ID = ID.Replace(‘/’,’-’);

2 XML FOR ASP.NET BASICS

44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85: 86: 87:

47

48

XML for ASP.NET Developers

LISTING 2.11

continued

88: ID = ID.Replace(‘:’,’-’); 89: ID = ID.Replace(‘ ‘,’-’); 90: CreateXmlFile file = new CreateXmlFile(Request); 91: string sStatus = file.writeXML(rootTag,”request”,ID,”1.0”, 92: “request.xml”,false,false); 93: if (sStatus.Length != 0) { 94: output += “Error: “ + sStatus; 95: content2.InnerHtml = output; 96: } else { 97: content.Visible = false; 98: content2.Visible = true; 99: } 100: } 101: 102: public void viewXML_Click(Object Sender, EventArgs E) { 103: CreateXmlFile file = new CreateXmlFile(Request); 104: Response.ContentType = “text/xml”; 105: Response.Write(file.ReadFile(“request.xml”,true) + 106: “”); 107: Response.End(); 108: } 109: 110: public void Page_Load(Object sender, EventArgs E) { 111: content.Visible = false; 112: content2.Visible = false; 113: if (!Page.IsPostBack) { 114: content.Visible = true; 115: } 116: } 117:

Looking at the preceding code, you can see that a class is specified named CreateXmlFile. This class accepts the Request object in its constructor. When the page first loads, the main HTML form is shown to the user. After entering the necessary information, the user clicks a button named submitButton that triggers the submitButton_Click event handler on the server. This handler instantiates the CreateXmlFile class and calls its writeXml() method. This method accepts the parameters listed in Table 2.2 TABLE 2.2

writeXML() Method Parameters

Parameter Name

Purpose

root

Root node name Record node name

node

XML for ASP.NET Basics CHAPTER 2

TABLE 2.2

continued

Parameter Name

Purpose

recordID

ID for a given record XML document version Name of XML document Write out end root tag Write data as attributes rather than elements

version fileName writeEndRoot writeAtts

49

2

Wait a minute! Didn’t we just spend an entire chapter discussing how important it is to follow the XML rules and close all tags so that XML documents are well formed? Well. . .yes we did. But because we’re not working with an XML parser, this is a necessary evil for the application to handle more than one bid request update to the XML file. Because the File object doesn’t have a method allowing us to delete one specific line easily, we can’t insert the final root tag until all bid requests for the month have been entered. After we discuss manipulating XML documents using the DOM in Chapter 6, you’ll see how this problem can be rectified. A potential resource-intensive alternative would be to use the File object’s ReadToEnd() method to read the entire contents of an existing XML document into a variable, replace the existing end root tag with empty strings, add a new bid request, and then write out the end root tag to the end of the document. This process would occur with each bid request addition and could become a problem if the client were to start entering more than 25 requests per week as specified. A few other workarounds to the problem exist as well, although we won’t focus on them here. Continuing with the current (non–parser-based) solution, after a bid request has been added to the XML document, you are presented with an opportunity to see the XML document. The viewXml_Click event handler (lines 102–108) contains the code that sets the Response. ContentType to “text/xml”, loads the non–well-formed XML document, dynamically adds the closing root tag, and then passes the now well-formed document to the browser (Internet Explorer 5or later required).

XML FOR ASP.NET BASICS

The writeXML() method creates a File object and then opens a text file. If the text file doesn’t already exist, one is created (lines 20–23) and the XML declaration and root tag items are written to the file. The function then proceeds to loop through each form element, writing each element’s name and value to the document (lines 34–43). If the writeXML() method’s writeAtts parameter is true, this process will add the form element name/value pairs to the document as attributes. Otherwise, it will add them as child elements of the node parameter. If the writeEnd Root parameter is true, the closing root element tag is written to the text file. This would be used only if one request were being captured per XML document. If the writeEndRoot parameter is false, no closing root tag is written to the document.

50

XML for ASP.NET Developers

Application Summary It’s obvious that this solution isn’t an optimal one. If the client ever anticipates having several thousand bid requests a month, you can imagine how big the file could get and what type of concurrency problems would be created. However, as long as the end root tag is added to the XML document (making it well formed) before the batch process runs to update the client’s database, it is one potential solution that will work. As mentioned previously, a much more efficient method of adding to or updating an XML document will be presented in Chapter 6.

Summary We’ve covered a lot of rules and concepts in this chapter. Although everything discussed plays an important role in creating XML documents, it’s extremely important that you take away from this chapter a good knowledge of XML’s rules. Documents that do not follow the rules may look good at first, but as you saw in the “Well-Formed XML Documents” section, the parser has no patience for rule bending and will let you know with an error message. In the next chapter, we’ll begin looking at a few of XML’s relatives that allow information located both in local and remote XML documents to be queried and/or manipulated. These include XPath, XPointer, and XLink.

XPath, XPointer, and XLink

IN THIS CHAPTER • Meet a Few of XML’s Relatives • XPath—The SQL of XML

52

53

• XPointer—Accessing XML Document Fragments 69 • XLink—Resource Relationship Management 76 • The XLink Simple Link • XLink Extended Links • Putting XLink Together

82 83 87

CHAPTER

3

52

XML for ASP.NET Developers

Meet a Few of XML’s Relatives In Chapter 2, “XML for ASP.NET Basics,” you saw that the XML language provides a structure for marking up data in a uniform, extensible, and descriptive manner that is readable both by humans and computers. Although this capability is certainly a welcome addition to the programming world, XML’s true power and flexibility can be realized only as it is combined with other languages and technologies. An XML document is quite useless on its own without a means for manipulating the data it is describing. To understand this further, imagine a SQL Server database that allowed for the creation of databases and tables but had no mechanism for querying the data. Although the data itself would be efficiently organized into relational tables, this structure wouldn’t be very useful if you couldn’t use Transact SQL (T-SQL) to run queries against the data. Assuming that an XML document is your SQL Server database, you obviously need some type of mechanism that allows you to access the data so that the XML document can be useful in application development. Several languages have been developed to allow XML documents to be queried and even linked in some interesting ways. These languages include XPath, XPointer, and and XLink. All three can be used in concert to access data located not only within a particular XML document but also within external documents located anywhere in the world. Much of the functionality contained within the XLink and XPointer languages is still being finalized by the W3C. As a result, Microsoft’s .NET XML parser implementation (along with many other popular parsers) does not yet implement XLink or XPointer capabilities. However, this won’t stop us from discussing some of the exciting capabilities that XLink and XPointer will offer in the near future. You may be wondering why a new manner of linking documents needs to be developed? After all, doesn’t the HTML language provide us with sufficient linking capabilities? The answer is both “yes” and “no.” Although most HTML documents employ the tag to link different documents, this functionality is extremely limited. For example, individuals clicking a link may not want to view the entire document that they are linking to on the other end. If they are clicking a link to obtain weather information, they may want only the current temperature for the city they live in. Current HTML linking capabilities require that the entire document be loaded rather than simply the section the individual wants to view. XPath, XPointer, and XLink exist to remedy this problem and improve on HTML’s current linking capabilities. The information in this chapter will be presented in the following order: • XPath—The SQL of XML? • XPointer—Accessing XML Document Fragments • XLink—Resource Relationship Management

XPath, XPointer, and XLink CHAPTER 3

53

XPath—The SQL of XML When the W3C committees first began working on an XML query language (http://www. w3.org/TR/xpath), they realized that the XPointer and XSLT groups were attempting to accomplish a similar task: access specific sections of an XML document. As a result, the XPointer, XSLT, and XPath groups worked together to specify a query language to be used with XML. The current XPath specification (version 1.0) became a W3C recommendation in November of 1999 and is a result of this joint effort. If you’ve ever used T-SQL to query a SQL Server database, you know how useful it is for obtaining recordsets. Depending on the type of ASP.NET development you do, you are more than likely used to seeing T-SQL (or ANSI SQL) syntax similar to the following example embedded within ASP.NET pages or stored procedures: SELECT * FROM AUTHORS WHERE au_id = ‘172-32-1176’

Although syntactically different, XPath provides the same access to XML document data as T-SQL does to SQL Server data. The XPath language is used by XSLT (covered in Chapter 7, “Transforming XML with XSLT and ASP.NET”) and XPointer to access data found within specific XML document elements, attributes, and so on.

The Windows file system emulates a hierarchical structure with the drive letter representing the root of all other files and folders on that drive. An XML document is structured hierarchically with the root element (also called the root node) containing different child elements (or nodes). These child elements may themselves contain other child elements. To access a folder on one of your drives ( C: for example), your computer follows a path similar to the following: c:\temp\subFolder1\subFolder2\xmlFile.xml

This path can easily be converted into an XML document: xmlFile.xml

XPATH, XPOINTER, AND XLINK

So what does XPath syntax look like? You may be surprised to learn that its syntax does not resemble XML’s syntax at all. In some ways it resembles a syntax that you are more than likely used to working with: the Windows file system.

3

54

XML for ASP.NET Developers

TIP As a point of review, you cannot simply add C: as the root element name. Remember in Chapter 2 that we discussed the concept of qualified namespaces. Putting the colon in the root name makes the parser think that C was declared as a qualified namespace somewhere in the document. Because it can’t find the declaration (or the element name after the colon), the parser will raise an error.

If you wanted to access subFolder2 in the preceding XML document using XPath syntax, you would simply type the following: C/temp/subFolder1/subFolder2

You could also type a shorthand version. This version of the query searches for all subFolder2 nodes located anywhere within the XML document: //subFolder2

You’re now an XPath expert! Well, the word “expert” may be a little strong at this point, but your experience in working with the Windows file system should help you in understanding how XPath works. XPath is, of course, much more powerful than this simple example. Aside from its basic syntax, the XPath language also includes its own set of functions to provide additional utilities such as formatting strings and numbers or performing mathematical calculations. Before going into more detail about XPath, it’s important that you realize that it is not designed as a standalone language. Going back to the Windows file system comparison, without having access to a DOS command prompt, File Manager, or Windows Explorer, typing the path to a file wouldn’t get you very far and you definitely wouldn’t find the file or folder you were looking for. The syntax you saw earlier to access a file is functional only when used in conjunction with another language or program (such as a command prompt). XPath was designed in the same manner. It is useful only when used with another language such as XPointer or XSLT.

XPath Basics The XPath specification defines a term named ”Location Steps” that sums up how the XPath language actually works. To get to a particular node’s location, you have to list the steps to get there using an XPath expression or pattern. Going back to the first XPath sample, we defined the starting point as C and listed each step that should be followed to walk through the element nodes to get to the destination data. Each step of the process was separated by a / character.

XPath, XPointer, and XLink CHAPTER 3

55

Let’s clarify this a little more through giving a simple real-life example. Getting to a node within a document is very similar to explaining your family lineage. If a friend asked you about a portion of your family line going back to your great grandfather, you may give the following information using XPath syntax: Great_Grandfather/Grandmother/Mother/Self

You can see from this sample that each step in your family lineage is separated by the / character. Another important term used in the XPath specification is that of the context node. The context node is the node being evaluated at each step of an XPath expression. In your family lineage example, the context node is first your Great_Grandfather. The context changes to the Grandmother node and then moves to the Mother node. Finally, the context node is Self. This same logic applies to nodes being evaluated at each step of an XPath expression. The context node becomes important as evaluations are being done on it. If someone asks you how many children your ______ had, it would be difficult to answer the question unless the blank was filled in (unless you can read minds of course). You need to know where to start (the context) in order to reply. If, however, someone asks you how many children your great grandfather had, you can now provide an answer because you have a context from which to start.

• An Axis Type • A Node Test • Predicates (filtering) The following sections explain each of these items in turn. After that discussion, we’ll discuss XPath functions and get into some examples so that you can see more XPath expressions at work.

Axis Types The family lineage XPath statement we looked at earlier took advantage of some XPath abbreviations to make things look a little nicer. Without using abbreviations, the same statement would look like this: Great_Grandfather/child::Grandmother/child::Mother/child::Self

Don’t worry about the :: characters. We’re not going to define any C++ interfaces or anything like that. The child:: syntax is one type of axis defined by the W3C that can be used when you’re trying to locate a node within a document. Each axis is followed by two colons (::) when used within an XPath expression. Axes are somewhat intimidating at first glance but are

XPATH, XPOINTER, AND XLINK

The path to a particular node within an XML document is constructed from three pieces of information:

3

56

XML for ASP.NET Developers

very useful when you know a few basics about how they work. Table 3.1 contains all the available axes as defined in the XPath specification. Table 3.1

XPath Axes

Axis

Axis Description

child

Includes all children of the context node. Includes all descendants of the context node. This includes children, grandchildren, and so on. Includes the parent of the context node. Includes all ancestors of the context node. Includes all siblings that follow the context node in document order. Includes all siblings that precede the context node in document order. Includes all nodes that follow the context node in document order. This does not include ancestors. Includes all nodes that precede the context node in document order. This does not include ancestors. Includes all attributes of the context node. Includes all namespaces within the scope of the context node. If no namespaces are declared, it is empty. Includes the context node only. Includes all descendants of the context node as well as the context node itself. Includes all ancestors of the context node as well as the context node itself.

descendant parent ancestor following-sibling preceding-sibling following preceding attribute namespace self descendent-or-self ancestor-or-self

Although many of the axes, such as self, child, and parent are self-explanatory, a few are not as obvious at first. Let’s take a look at a few axes examples based on Listing 3.1. Listing 3.1

Working with Axes in XPath

1: 2: 3: 4: 5:

XPath, XPointer, and XLink CHAPTER 3 Listing 3.1

57

continued

6: 7: 8: 9: 10: 11: 12: 13: 14:

Assuming that the context node is , the descendant axis to this node would, as the axis description says, select all descendants, which in this case would be the , , , and nodes. Which nodes would be included in the descendantor-self axis if the node is still the context node? This axis would contain the , , , , and nodes. Keep in mind that although this example uses the element named self, this has nothing to do with the word self as contained in the descendant-or-self axis. self as used in the axis name simply refers to the context node, which is in this example.

Axis following-sibling

Included Nodes ,

preceding-sibling

none

ancestor

, , ,

ancestor-or-self

, , , ,

attribute

fname

namespace

me

following

, ,

preceding

none

and lname

qualified namespace

Node Tests Node tests let you specify what type of node to locate relative to the context node. Each of the previously discussed axes have their own principal node type. For those axes that can contain

XPATH, XPOINTER, AND XLINK

The following are a few more examples that simply list the axis name and nodes contained within it. Assume that the node is now the context node:

3

58

XML for ASP.NET Developers

elements, the principle node type is element. Because the attribute axes can contain only attributes, its principle node type is. . . you guessed it, attribute. The previous examples have performed node tests to check for element nodes only. However, you could have done other types of node tests if you had wanted to get to a different location in the document other than an element. The other node tests you could have used include • The * wildcard character, which includes all items in the current axis. The wildcard works in a manner similar to the SQL * wildcard character used in SELECT statements. •

text(),

which includes all text nodes in the current axis.

•

node(),

which includes all nodes in the current axis.

•

comment(),

•

processing-instruction(),

which includes all comments in the current axis. which includes all processing-instructions in the current axis.

Although you’ll have the opportunity to see plenty of examples of node tests in action, the following are a few simple examples with explanations to get you started: axis::node test attribute::*

Explanation All attributes of the context node are selected.

child::text()

Matches the context node children’s text nodes.

descendant-or-

Matches all sibling elements that are self::sibling descendants of the context node. The context node itself is also included if it is a sibling element.

Predicates Using axes and node tests can help in reaching a specific location within an XML document. But what if the context node contains four children that are elements and you want to select only the third child element? You can use the child axis and element node test to get to the four children, but neither the axes nor node tests help you to select the third element only. Predicates, otherwise known as WHERE clauses, help solve this dilemma for you. A predicate helps to filter out unwanted nodes by taking advantage of built-in functions. This process is very similar to using the RowFilter property of the ADO.NET DataView class. Using ADO.NET, filtering out records that don’t have a specific ID (as defined in intID below) is as easy as typing the following code: dataView.RowFilter = “ID = “ + intID;

Using XPath, filtering out nodes that don’t meet specific requirements is as easy as typing child::sibling[position()=3]

This XPath statement uses a predicate to select the third sibling child of the context node.

XPath, XPointer, and XLink CHAPTER 3

59

You can see that a predicate is started and ended by using the [ and ] character tokens. XPath has several built-in functions, which you’ll learn more about in a moment, that can be used within the predicate statement. The preceding example used the position() function. Using one or more of these functions in combination with comparative operators, the processor performs the necessary checks on the current node-set to see which nodes should remain and should be excluded. If you’re wondering what a node-set is, think of it as another form of an ADO.NET DataSet. The difference is that the node-set contains a collection of XML nodes, whereas the DataSet contains records returned from a data source. The predicate statement as a whole produces a Boolean value after it is evaluated. Either the predicate statement is true and the node being evaluated is included in the node-set, or it is false and the node is excluded from the node-set. This Boolean value is derived by comparing the result of a function call to a value using comparative operators, including =, !=

•

=

•

-, +, *

•

and, or

•

div, mod

•

|

(union operator)

Your first look at predicates showed how to get at the third sibling child node of the context node. If your goal were to get the third and fourth child sibling nodes, you could use one of the following statements: child::sibling[position() >= 3] child::sibling[position() > 2] child::*[position() = 3 or position() = 4]

Later in the chapter, you’ll be presented with more predicate statements.

The Location Step Framework Putting the axis, node test, and predicate information types together results in the following location step syntax framework: :: []

All location steps in an XPath expression will follow this syntax. We can break the syntax into pieces: the XPath statement must first specify the type of axis to traverse. The child axis is the default if no axis is specified. After it is on the proper axis, the node test is performed to check whether a particular node exists. In cases where a specific node must be accessed, a predicate can be added to the XPath expression, which acts as a filter.

3 XPATH, XPOINTER, AND XLINK

•

60

XML for ASP.NET Developers

Samples of using this syntax are shown later in the chapter, along with abbreviated forms that can be used to shorten the location step framework. Before these are shown, however, it’s important that you understand what native functions exist in the XPath recommendation. Understanding these functions will allow you to fully leverage predicates.

XPath Functions Many functions are available other than the position() function shown earlier. The XPath recommendation categorizes each of the predicate functions based on its purpose and functionality. These categories include node-set functions, string functions, number functions, and Boolean functions. We’ll first discuss the node-set functions.

XPath Node-Set Functions The position() function that you have been working with thus far is an example of a node-set function. Node-set functions have the obvious function of returning information about one or more nodes. Table 3.2 shows the node-set functions listed in the W3C XPath recommendation. Table 3.2

Node-Set Functions

Function Name

Purpose

last()

Returns the index number assigned to the last node in the current context. The example selects the last customer child element. Example: child::customer[last()] Evaluates the position of the current node being evaluated within a given context and returns a number. Numbering starts with 1. Example: child::customer[position() = 2] This function takes a node-set as a parameter and returns the number of nodes within the node-set. It is similar to Count(*) in SQL. The example selects a father node containing four sibling nodes. Example: descendant::father[count(sibling) = 4] Selects nodes based on a unique ID attribute and returns a node-set. It expects an object and if the object is a node-set, the node-set is converted to a string value. Any IDs that match this string value will be returned. This function is similar to the key() function (covered in Chapter 7), but is more powerful because it can accept a node-set rather than a single string value. It is designed to work with a valid document in which attributes have been declared as type ID. The example selects all customer child nodes with a unique ID of 1234. The selection will also look for IDREF and IDREFS attribute node types that have a value of 1234 (ID, IDREF, and IDREFS are discussed in Chapter 4, “Understanding DTDs and XML Schemas”). Example: child::customer[id(“1234”)]

position()

count(node-set)

id(object)

XPath, XPointer, and XLink CHAPTER 3 Table 3.2

61

continued

Purpose

local-name(node)

Returns the node name located after the colon if a qualified namespace is associated with the node (applying it to family:father would return father) or simply the node’s name if no namespace is associated. The function can accept a node (that is, localname(node)) or can simply evaluate the current node being evaluated (local-name()). The example selects all child nodes of the context node with a local-name of father. Example: child::*[local-name() = “father”] Works like the local-name() function, except that it returns the actual node name as it appears in the original XML document, including the namespace prefix if any exists. Example: child::*[name() = “family:father”] This function returns the URI of any namespace associated with the node being evaluated. If no namespace URI exists, an empty string is returned. The example selects all child nodes of the context node that have a namespace URI equal to http://www.someURL.com. Example: child::*[namespace-uri() = “http://

name(node)

namespace-uri(node)

www.someURL.com”]

You’ll notice that there is no specific node-set function to extract a namespace prefix (the me in me:local-name for instance) should one exist on a node. The local-name() function allows you to get the node’s name, the name() function gets the prefix and local-name together, and the namespace-uri() function returns only the namespace URI. This certainly appears to present a problem because knowing the prefix associated with a particular node may be a big part of your applications, depending on the number of contributors to an XML document. Fortunately, this problem can be solved by taking advantage of node-set functions used in conjunction with XPath string functions.

XPath String Functions String functions in XPath provide some of the basic functionality that you are used to working with in ASP.NET documents using VB.NET or C#. Functions are available to convert values to a string, concatenate strings, return substrings, check string lengths, and more. Table 3.3 contains a complete listing of all string functions in the XPath recommendation.

3 XPATH, XPOINTER, AND XLINK

Function Name

62

XML for ASP.NET Developers

Table 3.3

String Functions

Function Name

Purpose

string(value)

This function converts a value to a string. If a node-set is passed in, the string value of the first node in the set is converted. This function is not normally needed because string conversions are handled on-the-fly when a string value is required. The example converts the number 101 to “101”. Example: string(101) This function concatenates (combines) all strings supplied as arguments. The example returns “Phoenix, Arizona.” Example: concat(“Phoenix”,”, “,”Arizona”) This function returns true if string1 starts with string2, and returns false otherwise. The comparison is case sensitive. The example will return true. If string2’s value had been “a”, false would be returned. Example: starts-with(“Arizona”,”A”) This function is similar to the InStr() function in VB.NET or IndexOf() function C#, although it doesn’t return a positional value. It returns true if string1 contains string2 in it. The comparison is case sensitive. The example returns true. Example: contains(“Sibling”,”Sib”) This function is similar to the Left() function in VB.NET, although it doesn’t accept a length argument. It returns the portion of string1 that precedes string2. If string2 doesn’t exist in string1, empty strings are returned. The example returns the “child” string. Example: substring-before(“child,sibling”,”,”) This function can also be used in conjunction with the name() function to get a node’s namespace prefix, which solves the problem mentioned in the previous section. Assuming the name() function returns me:myself, this example will return me: Example: substring-before(name(myself),”:”)

concat(string1, string2, string3, ...)

starts-with(string1, string2)

contains(string1, string2)

substring-before (string1,string2)

XPath, XPointer, and XLink CHAPTER 3 Table 3.3

63

continued

Purpose

substring-after (string1,string2)

This function is similar to the Right() function in VB.NET, although it doesn’t accept a length argument. It acts like the previous function except it returns the portion of string1 that occurs after string2. The example returns the “sibling” string. Example: substring-after(“child,sibling”,”,”) This function is similar to the Mid() function in VB.NET or the Substring() function in C#. It returns the portion of the input string starting at the character index specified in the second argument with a length equal to the third argument. If no length is specified, the returned string will contain the input string starting from the second argument to the end of the string. The first character starts with 1 rather than 0, like C#. The example returns the “ling” string. Example: substring(“sibling”,4) This function returns the number of characters in the supplied string argument. Passing in an empty string results in a value of 0 being returned. The example returns a value of 7. Example: string-length(“Sibling”) This function is similar to the Trim() function in VB, although it also replaces internal sections of whitespace with single spaces. The example returns “How are you?” Example: normalize-space(“ How are you? “) This function performs character substitutions. Characters that exist in the first two arguments are converted to the corresponding characters found in the third argument. This function is best understood by seeing an example. The example shown below will return “HOW ARE YOU?” Example: translate(“how are you?”,”aehouwy”,

substring(string, number,number)

string-length(string)

normalize-space(string)

translate(string, from,to)

”AEHOUWY”)

The next example will return “I AM fiNE” Example: translate(“i am fine”,”amne”,”AMNE”)

3 XPATH, XPOINTER, AND XLINK

Function Name

64

XML for ASP.NET Developers

Table 3.3

continued

Function Name

Purpose

translate(string, from, to) (continued)

Characters can be replaced (just like VB.NET’s Replace() function) by supplying the second argument with the character to replace and the third argument with the character that it should be replaced with. For example, the following code will return “how are you?” Example: translate(“how-are-you?”,” -”,” “)

XPath Number Functions Table 3.4 lists all number functions contained within the XPath recommendation. In situations where a function argument cannot be converted to a number, NaN (“not a number”) will be returned. Table 3.4

Number Functions

Function Name

Purpose

number(value)

This function converts the supplied argument to a number. If no argument is supplied, the function defaults to a node-set that contains only the context node. This function is not normally needed because number conversions are handled on-the-fly when a number value is required. If a node-set is supplied, it is first converted to a string that is then applied to the number() function. The following example returns 0. Example: number(‘0’) This next example returns a 1. Example: number(boolean(‘true’)) You’ll learn more about the boolean() function in the next section.

sum(node-set)

This function returns a number containing the sum of all numeric values of nodes contained within the node-set argument. Assuming that the numeric values of the child nodes found in the following XPath statement include (1,2,3,4), the example would return a calculated value of 10. Example: sum(/root/parcelNumbers/*) This function returns the supplied argument rounded down to the nearest integer. For example, if 10.4 were passed in, the return value would be 10. Example: floor(10.4)

floor(number)

XPath, XPointer, and XLink CHAPTER 3 Table 3.4

65

continued

Function Name

Purpose

ceiling(number)

This function is similar to the floor() function but rounds the supplied argument up to the nearest integer. For example, if 10.4 were passed in, the return value would be 11. Example: ceiling(10.4) This function returns a number rounded to the nearest integer. For example, 10.4 rounds to 10, whereas 10.5 rounds to 11. Example: round(10.4)

round(number)

XPath Boolean Functions The XPath specification contains a total of five Boolean functions. Although all these are listed in Table 3.5, you will more than likely only use two of the five functions on a constant basis when working with XPath expressions. Table 3.5

Boolean Functions

Purpose

boolean(value)

This function returns a Boolean value (true or false) depending on the value passed into the function. The conversion of a value to Boolean normally occurs automatically as needed. However, the boolean() function is useful to explicitly convert a value to a Boolean when necessary. For example, if you have a node named customerExists that contains the text “true,” you can convert this value from a string to a Boolean by using the following syntax: Example: boolean(/root/customerName/customerExists) To convert a 0 (false) or 1 (true) to a Boolean, use the following syntax: Example: boolean(1)

not(boolean)

This function returns the opposite of what is passed into it. Thus, if a true is passed in, a false will be returned and vice versa. The example returns a true. Example: not(false) This function returns true. This can be used when a constant Boolean value is needed in an XPath expression.

true()

3 XPATH, XPOINTER, AND XLINK

Function Name

66

XML for ASP.NET Developers

Table 3.5

Boolean Functions

Function Name

Purpose

false()

This function returns false. This can be used when a constant Boolean value is needed in an XPath expression. This function returns true or false based on whether the context node’s language (as determined by the value of the xml:lang attribute) equates with the supplied string argument. Assuming that an xml:lang attribute is equal to “en” on a particular node, the following example returns true if evaluated with that node as the context node. Example: lang(“en”)

lang(string)

XPath Abbreviation Examples Having covered all the various functions available in the XPath specification, you’re probably ready to move from the learning phase to the “let me see this in action” phase. Before jumping into some detailed XPath examples, you’ll be interested to know that many of the location step types mentioned earlier in the chapter have an abbreviated form that can save you time and make your XPath expressions much easier to read. A few of the key abbreviations need to be touched on briefly to prepare you for the samples. The following are some important XPath expression abbreviations: • The @ symbol is an abbreviation for the attribute:: axis: attribute::name can be written as @name. • The context node can be represented by a period character: self::* can be written as . • A few of the previously mentioned functions, such as position(), can be left out of the predicate expression: street[position()=3] can also be written as street[3]. • The root node can be accessed by typing /, and access to all children of the root node can be gained by typing //* or descendant::*. • An XPath axis such as child:: can normally be left out of an expression. child::street can be written as simply street. Understand that leaving out the axis syntax doesn’t mean that it isn’t there any longer. Every location step moves along a defined axis. When no axis is specified, the expression is assumed to follow the child axis. • The abbreviated code to access a parent node is similar to accessing a parent folder on the Windows file system. A parent node can be accessed by writing parent::* or ..

XPath, XPointer, and XLink CHAPTER 3

67

The following are a few examples shown first with the non-abbreviated syntax and then followed by the abbreviated syntax. Some of the examples include more than two XPath expressions to help you see other ways of accomplishing the same task. The examples are based on the following XML document:

XPath Examples Select the id attribute of the first golfer element: /golfers/descendant::golfer[position()=1]/attribute::id /golfers/golfer[1]/@id

Select all descendants of the golfer element. This includes the name and favoriteCourses elements: /golfers/descendant::golfer/* //golfer/* /golfers/golfer/*

3 XPATH, XPOINTER, AND XLINK

Heedy Wahlin Dan Wahlin

68

XML for ASP.NET Developers

Select all attribute descendants of the golfers root element: //attribute::* //@*

Select the name attribute of the third course element associated with the second golfer element: /golfers/child::golfer[position()=2]/child::favoriteCourses/ ➥child::course[position()=3]/attribute::name /golfers/golfer[2]/favoriteCourses/course[3]/@name //golfer[2]/favoriteCourses/course[3]/@name

Select the first golfer element and all children. This selects the name and favoriteCourses elements: /golfers/child::golfer[position()=1]/child::* /golfers/golfer[1]/*

Select the second golfer element’s course element having a name attribute equal to the first golfer element’s first course element name attribute (a little confusing unless you break it down into steps): /golfers/child::golfer[position()=2]/child::favoriteCourses/child::course/ ➥attribute::name[. = /golfers/child::golfer[position()=1]/child::favoriteCourses/ ➥child::course[position()=1]/attribute::name] /golfers/golfer[2]/favoriteCourses/course/@name[. = /golfers/golfer[1]/ ➥favoriteCourses/course[1]/@name]

Select the last course element’s name attribute that is located under the second golfer element: /golfers/child::golfer[position()=2]/favoriteCourses/course[last()]/@name //golfer[2]//course[last()]/@name /golfers/golfer[2]/favoriteCourses/course[last()]/@name

Select the city attribute of all course elements that have a name attribute starting with the letter “P”: /golfers/child::golfer/child::favoriteCourses/child::course[starts-with ➥(@name,’P’)]/attribute::city /golfers/golfer/favoriteCourses/course[starts-with(@name,’P’)]/@city

Select the first golfer element’s skill attribute and capitalize it: translate(/golfers/child::golfer[position()=1]/attribute::skill, ➥‘abcdefghijklmnopqrstuvwxyz’,’ABCDEFGHIJKLMNOPQRSTUVWXYZ’) translate(/golfers/golfer[1]/@skill,’abcdefghijklmnopqrstuvwxyz’, ➥‘ABCDEFGHIJKLMNOPQRSTUVWXYZ’)

XPath, XPointer, and XLink CHAPTER 3

69

Count the number of golfer elements: count(/golfers/child::golfer) count(//golfer)

After seeing the previous XPath statements, you may be wondering how you can test them to see if they actually work. You may also want to practice creating some of your own XPath statements. Fortunately, an excellent browser-based tool for testing XPath statements was created by Aaron Skonnard of DevelopMentor. The tool can be downloaded from http:// staff.develop.com/aarons/xmllinks.htm. Figure 3.1 shows an example of the tool in action.

3 XPATH, XPOINTER, AND XLINK

FIGURE 3.1 Using the XPath Interactive Expression Builder.

XPointer—Accessing XML Document Fragments Earlier in the chapter it was mentioned that the XPath recommendation was jointly developed by several W3C working groups. One of these contributing groups is also responsible for the XPointer language (http://www.w3.org/TR/xptr). Their participation was beneficial not only to the XPath language, but also to their own because XPointer leverages XPath’s capabilities. XPointer stands for XML Pointer. When combined with XLink and XPath, the XPointer language opens up many exciting possibilities for information retrieval from dispersed XML documents. The W3C XPointer Candidate Recommendation makes the following statement about XPointer’s purpose:

70

XML for ASP.NET Developers

XPointer supports addressing into the internal structures of XML documents. It allows for examination of a document’s hierarchical structure and choice of its internal parts based on various properties, such as element types, attribute values, character content, and relative position. In particular, it provides for specific reference to elements, character strings, and other parts of XML documents, whether or not they bear an explicit ID attribute. Many of the concepts mentioned in this statement strongly resemble functionality already available in the XPath language, which may lead you to believe that much is duplicated between the two. However, this is not the case. XPointer simply extends XPath’s functional utility, as you’ll see in the following sections. Your current XPath knowledge will be applicable to many XPointer concepts.

XPointer Basics At this point you may be wondering what the difference is between XPath and XPointer. Because both seem to allow access to specific items found within an XML document, can XPointer be used for something different? Obviously the answer to this question is “yes,” given all the work that has gone into creating the language. XPointer differs from XPath because it provides a mechanism for accessing specific content, referred to as document fragments, located in local or remote documents. This content isn’t limited just to nodes. XPointer even allows individual characters in a text string to be selected. Imagine having an XML document containing research data that is composed of three sections, including an introduction, body, and conclusion. The body and conclusion portions of the document do not exist within this XML document. They are located externally within two XML documents that contain information other than simply body or summary text. Using XPath alone, there is no mechanism for gaining access to the body and summary text in these remote documents. XPath is designed to locate specific nodes within a local XML document. This is where XPointer comes into play. Using portions of XPath syntax, XPointer allows the body and summary text sections to be gathered from the remote documents and placed into the current XML document. All this can be done without having to load the entire remote document (or documents in this case). Comparing this functionality to HTML, combining these languages allows you to link to a specific area of a document and “grab” its content without having to load the entire page and then scroll to the content as is done with HTML anchors. The capability to access data down to the individual character level opens up a whole new world for data sharing and exchange. Before getting too much further into the details, let’s cover a few key XPointer definitions:

XPath, XPointer, and XLink CHAPTER 3

Term sub-resource

point

71

Definition The portion of the XML document that XPointer identifies. Although the entire XML document would be considered the resource, the portion being accessed by XPointer would be the subresource. The W3C defines a point simply as “A position within XML information.” A point may represent a node within an XML document or simply a specific location within a node’s XML character data. The combination of a container node and index value define a point’s location. A point may be a position before any character or may precede or follow a node. A point can never exist on a character, though, only before or after it. As an example, the “T” character in the following document fragment has a container of type element and has an index of 0. The “e” would have an index of 1 and the “d” character an index of 2: Ted

character point

3 XPATH, XPOINTER, AND XLINK

A point with a container node that has no child nodes. Examples include a point within text, comments, processing instructions, and so on. node point A point with a container node that has child nodes. range A selection of XML content located between two end points. When you highlight a section of text in a program (such as Word) using the cursor, the selected area could be considered a range because it has starting and ending points. collapsed range A range that has equal start and end points. For example, if we start a point at character three and end a point at character three, the ranged is considered to be collapsed. location Similar to a node in XPath. However, because XPointers can begin in one paragraph and end in another and do not have to specify nodes in particular, a location can be a node, point, or range. location-set This is similar to a node-set created by an XPath expression. However, aside from including nodes, a location-set can also include points and/or ranges. singleton This term is reserved for situations where one range, string range, or single node is located by an XPointer. Multiple areas of XML content identified by an XPointer are not considered to be singletons. fragment identifier An XPointer identifier (expression) that has an escaped URI. Escaped refers to replacing characters such as < with their URI escape value, which would be < in this case.

72

XML for ASP.NET Developers

Points and ranges are used when working with XPointer expressions. Points determine where to start and end a search for XML content within a document, and a range contains the XML content located between two points. The syntax to create XPointer expressions using two points is as follows: http://www.someURL.com/someDOC.xml#xpointer( to )

This syntax would link to the range specified between point1 and point2 and load the entire document. You’ll notice that this is similar to how the HTML anchor currently works, although XPointer allows for much more flexibility, as you’ll see in the next few sections. After parsers support this feature, you’ll be able to pick out a section of XML within a remote document with pinpoint accuracy.

How XPointer Extends XPath To avoid duplicating functionality already available in the XPath language, XPointer leverages XPath where possible. However, it does extend XPath’s functionality in the following ways: • XPointer adds the point and range location types to the existing XPath node-set. As a result, an XPointer node test can include a test for a point or range in a location-set as well as the other node-set tests found in XPath. • XPointer builds on the concept of an XPath node-set by adding the locator-set concept, which includes points and ranges in addition to the items included in an XPath node-set. • The context in which XPath expressions are evaluated are governed by XPointer rules. • XPointer adds several new functions, including string-range(), range-to(), range(), range-inside(), here(), origin(), start-point(), end-point().

XPointer Functions The additional functions available in the XPointer language along with their corresponding descriptions are listed in Table 3.6. One interesting point about these functions is that they can be called after a / character in a location step (that is, node/function()). This is different from the XPath language where calling a function after the / character would normally result in the parser raising an error (exceptions to this exist, such as the count() and sum() functions to name just two). Table 3.6

XPointer Functions

Function Name

Purpose

range-to(expression)

This function returns a range for each location in the context. The example returns the range from an element with an id of 1111 to another element with an id of 2222.

XPath, XPointer, and XLink CHAPTER 3 Table 3.6

73

continued

Function Name

Purpose Example: xpointer(id(“1111”)/rangeto(id(“2222”)))

string-range(location-set, string,number,number)

range-inside(location-set)

This function returns ranges that match up with the content specified in the location-set argument. This is similar to the innerText property found in DHTML, which also returns the text between a start and end tag. It differs from the range() function in that it includes only a node’s content, not the node and its content. The example would return ranges for all folder elements that have an attribute named path starting with the letter “D.” The range starts just after the folder node’s beginning tag and ends just before its ending tag:

3 XPATH, XPOINTER, AND XLINK

range(location-set)

This next example returns a range from the first golfer element to the third golfer element: Example: xpointer(golfer[1]/range-to(golfer[3])) This function searches the string-value of a location for a substring that matches the string argument and returns range locations for any occurrences. The first argument accepts a location-set (//golfer), and the second argument accepts the string to search for. The third and fourth number arguments are optional but function much like the number arguments found in a C# Substring() function. The third argument tells where to start the returned range, and the fourth argument specifies the number of characters in the range. The example would return a range starting with the fourth occurrence of every “XML” string found in the title element. The range will start just after the “L” character (four characters in) and contain the five characters that come after the fourth (represented by [4]) “XML” string: Example: string-range(//title,”XML”,4,5)[4] This function returns ranges that match up with the locations specified in the location-set argument. The example would return ranges for all folder elements that have an attribute named path starting with the letter “D.” The range starts just before the folder node’s beginning tag and ends just after its ending tag: Example: range(//folder[starts-with(@path,”D”)])

74

XML for ASP.NET Developers

Table 3.6

continued

Function Name

Purpose

range-inside(location-set)

Example: range-inside(//folder[starts-

(continued)

with(@path,”D”)])

start-point(location-set)

This function returns a location-set containing the starting point for each range within the location-set argument. Here’s how the start-point() function handles different argument types: If start point is passed in, that point is returned unchanged. When a range is passed in, the starting point of the range is returned. When the argument is an element, some text, a comment, or a processing instructions, the argument is converted to a range and the starting point of that range is returned. If the argument is an attribute or namespace, a syntax error is signaled by the function. Example: start-point(//folder)

end-point(location-set)

This function returns a location-set containing the ending point for each range within the location-set argument. The details on this function are the same as the startpoint function, except that an ending point is always returned rather than a starting point. Example: end-point(//folder) This function returns a location-set containing the location of the XPointer that is being evaluated. In simpler terms, the here() function returns the element containing the XPointer itself, either as a text element or an attribute. The example allows the XPointer expression to point to locations relative to the location of the XPointer expression itself. Example: #xpointer(here()/books)

here()

origin()

This function is useful only when used within the context of XLink (discussed next) to link XML documents. It returns a location-set containing the location of the originating link.

XPath, XPointer, and XLink CHAPTER 3

75

XPointer Errors Errors in XPointer can be handled differently than errors in XPath. In situations where an XPath expression finds no matching locations within the XML document, an empty node-set is returned and no error is raised. However, XPointer must be stricter with error handling because it allows access to remote documents. XPointer is required to raise an error if a fragment identifier (expression) returns no results. The following is a summary of the three errors that can be associated with XPointer and their associated description: Description

Syntax Error

This error occurs when an XPointer expression (also called a fragment identifier) contains incorrect syntax. This error occurs when a resource document does not contain well-formed XML. The fragment identifier (XPointer expression) may be correct but be unable to create a point or range because of resource document problems. This error occurs when an XPointer expression is syntactically correct, the resource contains well-formed XML, but no locations are returned. As mentioned, this type of error does not occur in XPath, because empty node-sets are acceptable there.

Resource Error

Subresource Error

XPointer Examples As the XPointer language is moved to the W3C recommended status, more and more examples of using it with supporting parsers will become available. Until then, here are a few examples of using XPointer. The examples are prefixed by a remote resource name of www.someURL.com:

Identifying Fragments Using Bare Names Select a node with an id of chapter1 that is found in the document named remoteDocument.xml. This example shows how to use “bare names,” which is a shorthand method that saves you from having to use the id() function. You’ll notice that this is very similar to using an HTML anchor: http://www.someURL.com/remoteDocument.xml#chapter1

This can also be written as: http://www.someURL.com/remoteDocument.xml#xpointer(id(“chapter1”))

3 XPATH, XPOINTER, AND XLINK

Error

76

XML for ASP.NET Developers

Identifying Fragments Using Child Sequences XPointer allows nodes to be accessed by providing child sequence numbers as shown next: http://www.someURL.com/remoteDocument.xml#/1/3/4

The #/1/3/4 syntax tells XPointer to go to remoteDocument.xml and access the first element found there. After finding this element, find its third child element. Now choose this element’s fourth child element.

Identifying Fragments Using XPointer Expressions If every element of every XML document contained an id type attribute (as defined in the DTD), accessing XML content would be much easier. However, because many XML documents don’t have id attributes, a more detailed way of accessing XML content must be used. This is where XPointer expressions are useful. When bare name and child sequence methods of accessing XML content are not specific enough, an XPointer expression can be created. This expression will select the range between the first and fourth golfer nodes: http://www.someURL.com/remoteDocument.xml#xpointer(/golfers/golfer[1]/ ➥range-to(/golfers/golfer[4]))

The following example will pull the content between the first and third sibling nodes: http://www.someURL.com/remoteDocument.xml#xpointer(//father/sibling[1] to ➥//father/sibling[3])

The next example will return all ranges within the /golfers/golfer/name context that contain a substring equal to “Joe”: http://www.someURL.com/remoteDocument.xml#xpointer(string-range(/golfers/ ➥golfer/name,”Joe”))

Finally, the following document will first try to find a golfer element’s fourth name node. If that location cannot be found, it will try to find the last name node: http://www.someURL.com/remoteDocument.xml#xpointer(//golfer/name[4]) ➥xpointer(//golfer/name[last()])

XLink—Resource Relationship Management The XLink specification (http://www.w3.org/TR/xlink/) adds several additional pieces of functionality that make it easier to access external resources and maintain complex linking relationships. At press time, the XLink specification was in “Proposed Recommendation” status, so the majority of the concepts covered in this section are likely to remain unchanged. After the specification reaches “recommended” status at the W3C, you should start to see parsers or applications on the market that support XLink.

XPath, XPointer, and XLink CHAPTER 3

77

You may recall a short discussion we had concerning HTML linking limitations at the beginning of this chapter. Although HTML links work quite well in a browser, some of the limitations found in the HTML link include the following: • HTML allows links only between two resources. • HTML links have to be embedded in the originating link’s file. This can cause maintenance headaches. • HTML anchors can help locate specific information within a document but require that the entire page be loaded. This wastes bandwidth. • HTML links are unidirectional. They can point only in one direction. • The HTML link has few attributes for customizing linking capabilities based on different linking needs. • Updating a target document with anchors is not possible without having “write” access to that document. • HTML links require specific element tags to work ( for example). This makes it difficult to add linking capabilities to other elements.

XLink Basics The XLink specification doesn’t actually mention linking different documents. Rather, it defines a structure that consists of links between “resources.” These resources could be XML documents, media files (images, movies, or music), database information, or any other type of resource that needs to be referenced through a link. Adding more functionality to any type of established item, such as the HTML link, is oftentimes associated with an overall increase in complexity. This is not necessarily the case with XLink. After you understand its keywords, elements, attributes, and functionality, you’ll see that it looks just like regular XML. Although the XLink language allows you to define links the same way as you do in HTML, it does bring with it more advanced attribute and element definitions that help in linking two, three, or more resources in a uniform manner. Understanding the various attributes and definitions that come with the XLink language is important to leverage its linking power.

3 XPATH, XPOINTER, AND XLINK

A few of these limitations are addressed by the XPointer language because it allows specific content fragments to be accessed in remote XML documents. Although this is a great step forward, the old HTML link can be improved on in many other ways. XLink strives to make these improvements a reality by adding new linking capabilities to documents that comply with the XML version 1.0 recommendation.

78

XML for ASP.NET Developers

Before learning about the attributes and elements that exist in XPath, let’s take a look at some examples of what XPath syntax looks like. First let’s write out the syntax for what is coined a “simple link.” A simple link functions the same as a link found within an HTML page: John Doe

The following is an example of an extended link containing four different resources. This type of linking is not possible using HTML’s anchor tag:

XPath, XPointer, and XLink CHAPTER 3

79

I’ll defer an in-depth discussion of the different elements and attributes being used here until later in the chapter. You can see, however, that after you understand a few basic concepts concerning new elements and attributes defined in the XLink specification, implementing the XLink language isn’t much different than working with normal XML documents.

XLink Keyword Definitions Table 3.7 contains many XLink keywords that will become useful as you learn more about creating links. Table 3.7

Keywords in XLink

Description

Arc

An arc specifies how links are traversed. In the case where multiple resources are being linked, the arc can specify which direction to follow between links with the to and from attributes. In the case of a simple link, the arc is not necessary because it’s obvious which direction the link flows. In cases where two resources are specified to have a linking relationship, this is the resource identified in the to attribute. Example: An extended link associates many local and/or remote resources together. The link is considered inline if any of the resources are local and considered out-of-line if none are local. Defined by the W3C as “A link where some content in the linking element serves, by virtue of its presence inside the linking element, as a participating resource.” Use of the tag in HTML is considered an inline link. Data used to identify a resource in a link. Identification occurs by specifying a URI or other type of identity. A file external of any resource that contains an extended link. This type of file is similar to an include file in ASP.NET because it helps maintain specific information referenced by many resources in one location. A multidirectional link can be started by any of the resources participating in the link. As such, the HTML link would be excluded from this definition because it can initiate only a oneway link (hitting the Back button doesn’t count).

Ending-resource

Extended link

Inline link

Locator Linkbase

Multidirectional link

3 XPATH, XPOINTER, AND XLINK

Term

80

XML for ASP.NET Developers

Table 3.7

continued

Term

Description

Out-of-line link

When a link starts from a resource other than the document containing the link, the link is considered out-of-line. This type of link includes only resources that are remote. An out-of-line link exists when a document not under your control (you do not have write permissions to it) is included in a link. This type of link is necessary for remote links to initiate other links. A simple link is very similar to a normal HTML link in that it specifies a one-way link between two resources. Because one of these two documents is always local, simple links are always considered to be inline links. A traversal occurs when a resource identified in a link is accessed. Traversal can be started by a user or from an application.

Simple link

Traversal

Now that you’re familiar with a few of XLink’s definitions and keywords, let’s take a look at some attributes that are used in building simple and extended links.

XLink Attributes The XLink language specifies several attributes that add various linking capabilities. A listing of these attributes with their corresponding description can be found in Table 3.8. Table 3.8

XLink Attributes

Attribute

Description

xlink:arcrole

The arcrole attribute is a semantic attribute used to describe the meaning of a resource (or a property of a resource) based on the context the link is viewed in. It must contain a URI reference. The W3C explains the arcrole attribute in the following manner: A resource might generically represent a “person,” but in the context of a particular arc it might have the role of “mother” and in the context of a different arc it might have the role of “daughter.” Specifies the location to a remote resource. The XLink specification defines this as containing a URI reference.

xlink:href

XPath, XPointer, and XLink CHAPTER 3 Table 3.8

81

continued

Description

xlink:label

This traversal attribute is used to provide a way for arc elements to identify a resource or locator element based on its label. It can be used only on the resource or locator elements. This is similar to using the id=”. . . ” attribute on HTML elements when working with DHTML. This determines the link type to be used. Possible values include simple, extended, locator, arc, resource, title, none. You’ll learn more about what the extended, locator, arc, and title values accomplish. As far as the resource value, it can be used as an attribute value to define link participants that are available locally (rather than remotely). Content enclosed within the resource type element would be considered “local.” This attribute must contain a URI reference and is used to indicate a property that a resource has. This attribute contains content that is intended to be read by a human. The title attribute helps give information about the link. This determines how content identified by a link will be shown. The possible values are replace, embed, new, other, and none. The replace value functions in the same manner as linking between two pages in HTML, whereas the embed value would be similar to the function the tag element performs. The actuate attribute specifies how the link should be traversed from a timing perspective. Rather than always being triggered by human interaction, the link can be set to be triggered by an application. Possible values include onRequest, onLoad, other, and none. This attribute is used only with an arc element in an extended link to specify the end point of a link. Its value is equal to the label attribute on a resource or locator type element. This attribute is used only with an arc element in an extended link to specify the start point of a link. Its value is equal to the label attribute on a resource or locator type element.

xlink:type

xlink:role xlink:title

xlink:show

xlink:actuate

xlink:to

xlink:from

3 XPATH, XPOINTER, AND XLINK

Attribute

82

XML for ASP.NET Developers

The XLink Simple Link The HTML link that you’re already familiar with is actually an example of a simple link in the XLink language. It provides a way for a single document to link to another document. This type of link is unidirectional because the initiating page knows about the destination page, but the destination page is not actually participating in the link. The destination page simply displays its content in the browser. It’s true that you could hit the browser’s Back button, but the destination document still isn’t actually participating in the link. Because the simple link includes a local resource (one in which you created the link), it is always considered to be an inline link. Though limited in flexibility, the simple link has helped place the Web into the limelight and has made it an essential resource for businesses and individuals alike. Adding a simple link to an XML document that is part of an XLink-aware application is as easy as adding a few attributes to an existing XML element. Note that the XLink qualified namespace must be added to the XML document: Chapter 1

The xlink:type attribute is specified as “simple” and the xlink:href lists the link URI. This method of declaring a link is more efficient than the current HTML linking implementation. To understand why, imagine trying to add linking capability to a

tag in HTML without wrapping it with the and tags (or using scripting). Using attributes allows a link to be added to any element quite easily. Although you learned a little about XLink attributes earlier, let’s take a look at two interesting attributes that should prove to be very useful in applications that implement XLink in the future. The actuate attribute can take on values of onLoad, onRequest, other, and none. The onRequest value means that the link is traversed when the user requests it. The onLoad value is used to traverse a link immediately after a document completes loading. When the show attribute is equal to embed and actuate is equal to onLoad, a useful way of embedding content from outside resources can be accomplished. When combined with XPointer, these technologies could be used to create the research XML document discussed earlier that linked to introduction, body, and summary sections located in remote documents.

XPath, XPointer, and XLink CHAPTER 3

83

XLink Extended Links Extended links perform the obvious task of “extending” the capabilities of a simple link by allowing multiple resource links to be managed rather than just one. Like the simple link, extended links can be created by using XLink attributes placed on existing XML elements. The W3C gives the following definition: An extended link is a link that associates an arbitrary number of resources. The participating resources may be any combination of remote and local. The XLink specification also mentions that if all the resources are remote (not editable), the link is considered to be out-of-line. If any of the identified resources are local (editable), then the link is considered to be inline. Figure 3.2 shows a simple representation of an extended link. Resource 3

Resource 4

3 XPATH, XPOINTER, AND XLINK

Resource 1

Resource 2

FIGURE 3.2 Extended link relationships.

At first glance, this figure may look very similar to simple links between resources, as in HTML. However, the extended link includes all these resources in a relationship and then specifies how the links should be traversed. Listing 3.2 shows how these links could be written using extended link XPath syntax. It’s important to know that the extendLink and loc element names were chosen to make the sample easier to understand. These element names are not part of the XLink specification. In fact, any element name could be used.

84

XML for ASP.NET Developers

Listing 3.2

An Extended Link

1: 5: 8: 11: 14: 17:

label=”resource1”

label=”resource2”

label=”resource3”

label=”resource4”

The extended element type shown in Listing 3.2 acts as a container for four different resource links. It contains some of the same attributes you saw in the simple element type shown earlier, and it also declares the XLink qualified namespace. Inside this container are four locator elements that specify the URI to each resource. Going back to Figure 3.2, the small boxes located on each resource would represent that resource’s locator. Although the code shown in Listing 3.2 specifies the locators for each resource and groups each resource in an extended container, it does not say how links between the resources should be traversed. Should Resource 1 link to Resource 3? Should Resource 4 link to Resource 3? The listing doesn’t mention anything about the way the resources should be linked. To accommodate the need for specifying how links should be traversed, the XLink language introduces the arc concept. An arc can be thought of as a traversal path that specifies how to link from one resource and to another. Listing 3.3 adds on to Listing 3.2’s code by adding information about link traversals through the use of arc element types. Listing 3.3

An Extended Link with Arcs

1: 5:

XPath, XPointer, and XLink CHAPTER 3 Listing 3.3

85

continued

8: 11: 14: 17: 20: 23: 26:

Any variety of arc paths can be specified as long as all paths are unique. All this is done without having to actually add a physical link inside of resource3 that goes to resource4, as is the case when you link to a resource that you have no control over. Exactly how will resource3 link to resource4 if the link isn’t physically embedded in resource3? To answer this question completely, we will have to wait for the first XLink-capable applications to appear on the scene and analyze how this feature is implemented. One interesting point made in the XLink specification is that if a from or to attribute is missing in an arc type element, an arc will be created in the appropriate direction to all locator type elements with label attributes located within the extended link grouping. To clarify this less intuitive concept, the W3C provides the following example:

XPATH, XPOINTER, AND XLINK

By specifying the arc path, you now know the locations of four resources as well as how each link between the resources should be traversed. The arc elements listed previously tell the extended link that resource1 links to resource2, which links to resource3, which links to resource4. If you had wanted resource4 to link back to resource1, you could have applied another XLink type attribute to an element and specified the additional arc path using the from and to attributes.

3

86

XML for ASP.NET Developers

xlink:label=”parent” xlink:label=”child” xlink:label=”child” xlink:label=”child”

Based on each locator type’s title attribute, the following arcs would be assumed because there are missing from and to attributes in the arc type element: p1-c1, p1-c2, p1-c3, p2-c1, p2-c2, p2-c3, c1-c1, c1-c2, c1-c3, c2-c1, c2-c2, c2-c3, c3-c1, c3-c2, and c3-c3

As you can see, this rule causes a type of cross-join to occur that involves each locator type element. Although all possible arcs are pursued, the uniqueness of each arc is maintained. The extended link automatically allows links between resources to be organized and grouped. For this extended link to be useful, it would need to be embedded in one of the resources. This is called an inline extended link because the resource that contains the embedded link information would be editable, in contrast to a third-party read-only resource. After the extended link is inserted, the relationships between the different resources specified in the locator type elements can be managed.

Linkbases and External Linksets In a perfect world, links within an HTML document have the capability to be changed without having to edit the actual document itself. HTML alone does not allow for this, although you could, of course, maintain all links for an ASP.NET page in a database or XML document if you desired. The XLink authors knew that maintaining links in HTML is difficult and they built in the capability for resource links to be separated from the actual resources. A file referred to in the XLink specification as a “Linkbase” can be in a location that is separate from the actual resources. The contents of this file would contain one or more extended links. Because the extended link isn’t actually found within a resource, it is called an “external linkset.” Figure 3.3 depicts this. As Figure 3.3 shows, each resource is tied together by the external linkset. This linkset contains locator information about each resource and arc statements that specify how the links should be traversed, just as you saw earlier. Separating the actual link information from the resources is useful because it allows you to manage a list of links externally making overall maintenance much easier. To add a new link, you would simply add the resource’s locator to the external linkset document and provide an arc. No other documents need updating!

XPath, XPointer, and XLink CHAPTER 3 Resource 3

87

Resource 4

External Linkset

Resource 1

Resource 2

FIGURE 3.3 An out-of-line extended link.

Maintenance of links suddenly becomes much easier through the use of linkbases and external linksets.

Putting XLink Together Determining when to use the different XLink attributes can be somewhat confusing. Fortunately, the W3C created the following information table that specifies when attributes are required (R) and when they are optional (O). To see which attribute can be used with a given element type, look down each column. If a cell is empty, you can’t use the attribute with the element type. Refer to the table when you can’t remember much because it’s late at night and you’re feverishly working to finish up an XLink project!

3 XPATH, XPOINTER, AND XLINK

For an external linkset document to be used, a resource needs to know where the external linkset document is located. This is accomplished by placing code similar to the following into an inline resource:

88

XML for ASP.NET Developers

simple

extended

locator

arc

resource

title

type

R

R

R

R

R

R

href

O

role

O

O

O

arcrole

O

title

O

show

O

O

actuate

O

O

R O

O

O O

O

O

from

O

to

O

label

O

O

O

Summary In this chapter we covered a lot of technologies related to XML. Although the XPointer and XLink languages have yet to be implemented fully, they are promising technologies that will make developing with XML even more powerful. In Chapters 6 and 7, you will see how useful the XPath language can be to access data contained within an XML document using the DOM or XSLT. However, before jumping into those chapters, Chapter 4 takes a look at XML DTDs and schemas.

CHAPTER

Understanding DTDs and XML Schemas

4

IN THIS CHAPTER • Why Use DTDs or Schemas? • Do I Really Need To Validate? • DTD Basics

90 91

93

• XML Schemas—Looks a Lot Like XML!

101

• Using the Schema Keyword with Namespaces in XML-DR Schemas 105 • The W3C XML Schema

114

90

XML for ASP.NET Developers

Why Use DTDs or Schemas? By this point in the book you should have a good feel for how XML documents are created and how flexible and extensible they can be. XML is so flexible that many other languages, including XPointer and XLink (to name just two), have been modeled after it. Although flexibility and extensibility are certainly beneficial, too much of either can be detrimental if left uncontrolled. Imagine writing an ASP.NET page that uses whatever keywords you want. Instead of using if or switch statements to control program flow, you decide to make up your own version of the if statement and call it doThisIf. Although your keywords and logic may make perfect sense to you, no one else can use the code unless you explain to them the rules of how it works. In addition, to make your keywords work on your (or any other) Web server, you would need to write your own ASP.NET compiler that recognized the keyword additions you dreamed up. Although the preceding example is certainly far fetched, this same type of logic applies to creating XML documents if you plan on sharing them with anyone other than yourself. Unless other users know and can depend on a specific syntactical document structure, they will have a hard time using your document even if it is well formed. For example, putting a person’s address in a tag named address that has child tags named street, city, and state may make perfect sense to you. But the other party may expect that the address information you provide them is contained in a tag named deliveryAddress with child tags named address1, address2, city, and state. Unless these issues are cleared up between you and the other party, data exchange may prove difficult and frustrating. To solve this problem, the XML 1.0 specification includes the Document Type Definition (DTD). The DTD was born out of the strict rules that accompanied XML’s parent language, SGML. A DTD acts as a syntax guide to an XML document by declaring rules that must be followed for the document to be valid. Remember that all XML documents must be well formed, but they do not have to be valid to be parsed, assuming no DTD is present. Going back to the previous example involving addresses, a DTD would help the party receiving your XML document to understand the document’s structure and be assured that the structure follows the rules as defined in the DTD. If you decide to add a tag that isn’t included in the DTD, a validating parser will raise an error. Having this validation will allow any parties receiving your document to write an application based on your document’s defined set of rules. Although DTDs have excellent parser support and provide a rules-based way of validating XML documents, they do have their weaknesses. Some of these weaknesses include the following: • DTD syntax is difficult to read and can be somewhat difficult to write. This stems from its SGML lineage. Like any language, after you learn the basics of creating DTDs, they aren’t that difficult to work with.

Understanding DTDs and XML Schemas CHAPTER 4

91

• Determining when and when not to use quotes and other attributes can be confusing. • DTD syntax does not follow or conform to the well-formed XML rules established in the XML 1.0 specification. • DTDs have very limited support for data typing. • A DTD is very restrictive when defining the order of elements under a parent element. • Because a given XML document can have only one external reference to a DTD, namespace problems can arise. • Programmatically accessing information contained within a DTD is too complex. • DTDs have no built-in support for namespaces. Even with their weaknesses, DTDs have wide industry support and are still are very important in the world of XML. DTDs also have excellent support for entities. However, because of some of the inherent weaknesses previously mentioned, an alternative to DTDs has been developed by the W3C. This alternative is termed “XML Schemas.” Microsoft’s MSXML parser first began support for XML Data - Reduced schemas (XML-DR). These schemas offer XML-like syntax, stronger data typing, and more flexibility in describing an XML document’s structure and rules. Although Microsoft’s schema language differs from the W3C’s XML schema, they both look and act a lot like XML, as you’ll soon see. Before entering the world of DTDs and schemas, let’s take a look at when validation should and should not be used when working with XML documents.

Do I Really Need To Validate?

With that in mind, it’s important to know that all XML documents do not have to be valid to be considered useful documents. Many situations may occur where an XML document is developed that will not be exchanged with internal or external parties and therefore doesn’t need validation. As long as the creator of the document knows what it contains, any applications he or she writes will function. In fact, validating a document can slow down the parsing process because the parser must ensure that everything is kosher with the document’s structure. Validation also makes the

4 UNDERSTANDING DTDS AND XML SCHEMAS

In Chapters 2, “XML for ASP.NET Basics,” and 3, “XPath, XPointer, and XLink,” you worked with XML documents that were well formed but not valid. Opening any of these documents in Internet Explorer 5 or later proves to be no problem. Because none of the documents are truly valid, why doesn’t the XML parser return an error when the document is opened? The answer is that they are well formed, but because they do not contain any type of a DTD or schema reference, they are not validated. In addition to this, the XML parser built into Internet Explorer 5 or later does not validate XML documents by default, even if they do have a DTD associated with them. Validation must be turned on programmatically.

92

XML for ASP.NET Developers

document less flexible for future changes unless the DTD or schema is updated to reflect new needs. As an example, assume that you create an application that gathers data from an XML document. Rather than using a mechanism such as XPath to query elements by name, your application recursively loops through the document and writes out the data it contains to a Web page. Any new elements that are added cause no problems because they are included in the looping process. Although this type of application admittedly may not have a lot of utility, it definitely doesn’t require a DTD or schema to work correctly. Chapter 6, “Programming the Document Object Model (DOM) with ASP.NET,” takes a look at a sample application that uses XML to create a menu system very quickly on the server side. Because the document is itself quite simple and needs to be accessed quickly, a DTD or schema will not be used—simply because it isn’t necessary. XML documents that do have an association with a DTD or schema do not always have to be validated. Many parsers allow you to determine if validation should occur by telling the parser to turn validation on or off. We’ll talk about this more in Chapter 5 (“Using the XmlTextReader and XmlTextWriter Classes in ASP.NET”). All in all, the choice to validate is yours alone because there’s nothing that dictates exactly when validation should be used. In complex applications that expect particular elements and attributes, validation is more than likely a good idea. In other applications, validation may be overkill. Use your best judgment when deciding whether your document must be validated.

NOTE As you go through the next few sections, remember that raw XML documents viewed in Internet Explorer 5 or later are not validated. To check the validity of your documents or the samples that follow, point your browser to the following URL and click the Demo link: http://msdn.microsoft.com/Downloads/samples/ Internet/xml/xml_validator/sample.asp

If you’d rather work with a standalone product that validates, take a look at the following URLs: http://www.xmlspy.com http://www.xmetal.com http://www.extensibility.com

An excellent source of XML-related products can also be found at http://www.xmlsoftware.com.

Understanding DTDs and XML Schemas CHAPTER 4

93

DTD Basics As mentioned earlier, DTDs still have wide industry support even though they have several weaknesses associated with them. Because of this support, a basic overview of DTDs is given in this chapter so that you can understand and use them as appropriate in your XML documents. Because several books are available that concentrate specifically on DTDs, I won’t spend a lot of time covering them here. However, you’ll learn enough to effectively use them to validate XML documents. Because you are already familiar with what DTDs do, let’s jump right into the specifics by first looking at a sample DTD. This sample is based on the XML document shown in Listing 4.1. Listing 4.1

A Simple XML Document

The following is an example of how this document’s DTD might look:

4 UNDERSTANDING DTDS AND XML SCHEMAS

1: 2: 3: 4: 5: /default/default.aspx 6: Home 7: 8: 9: 10: About Us 11: 12: /calendar/default.aspx 13: Events Calendar 14: 15: 16: /news/default.aspx 17: Press Releases 18: 19: 20: /contact/default.aspx 21: Contact Numbers 22: 23: 24: 25:

94

XML for ASP.NET Developers

]>

The DTD DOCTYPE Back in Chapter 2’s discussion on entities, you had your first look at a DOCTYPE declaration. This declaration is similar to the XML declaration in that it lets the parser know when content is starting. A DOCTYPE declaration must follow the XML declaration and come before any elements. Comments or processing instructions may be between the XML declaration and DOCTYPE declaration. Adding the DTD directly into Listing 4.1 would result in the XML/DTD combination shown in Listing 4.2. Listing 4.2

XML Document with DTD

1: 2: 5: 6: 7: 8: ]> 9: 10: 11: 12: /default/default.aspx 13: Home 14: 15: 16: 17: About Us 18: 19: /calendar/default.aspx 20: Events Calendar 21: 22: 23: /news/default.aspx 24: Press Releases 25: 26:

Understanding DTDs and XML Schemas CHAPTER 4 Listing 4.2

95

continued

27: /contact/default.aspx 28: Contact Numbers 29: 30: 31: 32:

The DTD shown in Listing 4.2 is called an internal DTD. Internal DTDs actually “live” in an XML document, rather than being found in an external document. Here’s the general syntax for an internal DTD:

would be substituted for the real name of the document’s root element. If the root element name does not follow the DOCTYPE keyword, the parser will raise an error. As shown in Listing 4.2, the root element was actually named root and therefore placed after the DOCTYPE keyword. rootElementName

An XML document referencing an external DTD (one that is in a separate file) could use one of the following examples:

This example is called an external SYSTEM DTD. It functions in a similar manner as includes do in ASP.NET files or as .js or .css files do in HTML. After the parser sees the SYSTEM keyword, it knows to look for an external DTD at the URI (Universal Resource Identifier) specified. An external PUBLIC DTD would have the following syntax:

An application coming across this definition may have a built-in way of knowing where to look for the public DTD based on the organization name (SAMS) and document name (menus). If one cannot be found, the second URI (which is a SYSTEM URI) would be used.

DTD Elements The DTD used in Listing 4.2 contains several element type declarations. Element declarations are actually quite obvious in a DTD because they begin with the keyword ELEMENT. The structure of an element declaration is as follows:

4 UNDERSTANDING DTDS AND XML SCHEMAS

96

XML for ASP.NET Developers

Listing 4.2 declared the root, menuItem, hyperLink, and name elements (shown next): menuItem (hyperLink+, name+, menuItem*)> hyperLink ANY> name (#PCDATA)>

Element declarations are fairly straightforward to implement. They start with character. The content model for the hyperLink element declaration is ANY because it can contain text content: /default.aspx

or can be empty:

If the hyperLink element were always empty, you could have declared it as follows:

Understanding DTDs and XML Schemas CHAPTER 4

97

If the hyperLink element does not contain child elements (as in our example) and will contain only parsed character data (PCDATA), its declaration can be coded as follows:

Element declarations can also declare optional children. The following example specifies that the menuItem element must contain either a hyperLink element or zero or one name elements:

In cases where an element may contain parsed character data or child elements, the following declaration would be used:

This type of declaration is called a mixed content model because the menuItem element can contain text or elements. As a matter of definition, parsed character data is any data the parser actually parses. Any data within a CDATA section (covered in Chapter 2) would be considered as unparsed character data because the parser simply passes it through untouched.

DTD Attributes The structure of a DTD attribute declaration follows this pattern:

Listing 4.2 contained one attribute declaration. This particular attribute was named itemNumber and was an attribute of the menuItem element:

Table 4.2

Attribute Types

Attribute Type

Description

CDATA

Attributes typed as CDATA (described in Chapter 2) can contain any character information. Example:

4 UNDERSTANDING DTDS AND XML SCHEMAS

Attribute declarations start with

ID

IDREF/IDREFS

An attribute with an ID type must contain a value that is unique throughout the document. Example: The IDREF/IDREFS type allows for relationships to exist between different elements in a similar fashion to primary/foreign key relationships in a relational database. For example, the following code relates package2 and package3 to an invoice with an invoiceID equal to “ar7”. Example: ]>

Understanding DTDs and XML Schemas CHAPTER 4 Table 4.2

99

continued

Attribute Type

Description

NMTOKEN/NMTOKENS

A NMTOKEN represents a string value that is restricted to containing certain characters. For example, all NMTOKEN strings must be a single word (no whitespace allowed) and should not contain a colon because of namespace conflicts. The NMTOKEN type conforms to the elementnaming rules discussed in Chapter 2. The NMTOKENS type can contain more than one NMTOKEN separated by a whitespace. The example declares an itemNumber attribute that is of type NMTOKEN. Example: A notation type represents binary data such as a gif or jpg.

NOTATION

Attribute declarations can also have a default value. Up to this point, some of the examples you’ve seen contained defaults such as #IMPLIED and #REQUIRED. Table 4.3 is a listing of the default values that can appear within an attribute declaration. Table 4.3

Attribute Declaration Default Declarations

Description

#IMPLIED

The attribute’s value is optional and has no default value associated with it. Example: The attribute’s value is required anywhere in the document that the attribute exists. Example: Assigns a fixed default value to the attribute. Example:

“value”

Although the attribute is not required to have a value, the value assigned in the attribute declaration will be the default. This is good for ensuring that attributes contain values that you want to start with, as in the case of enumerations. Example:

DTD Entities Chapter 2 gave you your first taste of internal and external entities. These types of entities function in a manner similar to an include file in ASP.NET. For example, the following general

4 UNDERSTANDING DTDS AND XML SCHEMAS

Default

100

XML for ASP.NET Developers

entity declaration defines companyName as an entity name. Whenever this entity is referenced in an XML document, the companyName entity will be replaced with Tomorrow’s Learning:

The discussion of parameter entities in Chapter 2 didn’t provide you with many specifics simply because you had not learned about DTDs yet. So, we’ll cover these in more detail here. A parameter entity functions in a similar way to the internal and external entities, although it is referenced only in the DTD (in contrast to in the XML document) and uses slightly different syntax. The following is an example of a parameter entity and how it could be used within a DTD:

This example declares a parameter entity named clubTypes and assigns it a value of (TaylorMade|Cobra|Tommy Armour|Titliest). This value is then referenced in different element declarations, including the clubsUsed and clubPreference elements. Doing this causes the value (TaylorMade|Cobra|Tommy Armour|Titliest) to be dynamically placed into these element declarations and makes maintenance of the declarations easier. If the clubsUsed and clubPreference element declarations change to include different child elements, these can be changed in one place (at the clubTypes entity declaration) rather than at each element declaration. Although the preceding example is very simple, imagine if 20 different elements all allowed similar types of child elements. Changing the element declarations in one place is certainly much more efficient than editing each and every one of the element declarations directly! Parameter entities can also be quite useful when a base-set of attributes collectively describe more than one element. For example, if attributes named caption, name, id, width, and height are used on several elements, the following parameter entity definition could be used:

Applying this entity to an element definition can be accomplished by doing the following:

Understanding DTDs and XML Schemas CHAPTER 4

101

A simple external DTD named golfer.dtd along with its XML document (golfer.xml) are included with the book’s supplemental code. The external DTD uses a parameter entity named clubTypes, as shown earlier.

DTD Notations Notations are used within a DTD to specify external content that a parser cannot parse (binary data, for example). Up until this point, everything we’ve worked with has been text based. Notations allow for content that is non-ASCII to be included in an XML document. Because parsers are not required to support binary data according to the XML 1.0 recommendation, a notation allows binary data within a document to be associated with a helper application. In the following example, a png notation has been declared and associated with Adobe Photoshop. References to png will result in Photoshop being used to show the binary image data:

Summing Up DTDs DTDs provide structure for an XML document allowing it to be validated by a parser. Although the DTD syntax is not pretty to look at and can be somewhat difficult to work with, it will be some time before DTDs go away entirely because of their support throughout the industry. You’ll see an example of using the System.Xml assembly to validate against a DTD in Chapter 5. Before you learn how to do this type of validation, however, it’s important that you see some new ways of providing structure and validation for XML documents. We’ll talk about these “schemas” in the next section.

XML Schemas—Looks a Lot Like XML!

Many other people have questioned the DTD standard and have developed their own alternative versions of XML document validation. One of these alternative versions, XML-DR, has been developed by Microsoft and submitted to the World Wide Web Consortium(W3C). The W3C has looked at Microsoft’s proposal and several others and finished up work on an XML schema standard designed to allow for stronger data typing, XML-like syntax, and more overall power and flexibility in describing XML documents.

4 UNDERSTANDING DTDS AND XML SCHEMAS

After reading through the previous section covering DTDs, you may have wondered why an XML document’s structure isn’t validated by a document that actually looks like XML itself. After all, if a DTD is simply a repository of metadata about an XML document, shouldn’t it look like an XML document?

102

XML for ASP.NET Developers

At the time this chapter was written, Microsoft’s System.Xml assembly supported the entire XML schema specification, except for a few keywords that will be discussed later in this chapter. In addition to its support for W3C XML schemas, the System.Xml assembly also provides full support for Microsoft’s version of the XML schema (XML-DR) and DTDs. The next few sections cover XML-DR as supported by .NET’s System.XML assembly. We will also take a look at the W3C’s XML schema language toward the end of the chapter. To avoid confusion between the different schema versions, the next few sections focus exclusively on the XML-DR schema. Later on you’ll see that much of what you learn about Microsoft’s XML-DR schema language will be applicable to the W3C’s version.

A Sample XML-DR Schema and Its DTD Counterpart Let’s start our discussion on XML-DR schemas by walking through a simple example. Listing 4.3 contains information about different golfers. The metadata describing this XML document is shown in the XML-DR schema contained within Listing 4.4. Listing 4.3

Golfers XML Document

1: 2: 3: 4: 5: Paul 6: Allsing 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: Dan 17: Wahlin 18: 19: 20: 21: 22: 23: 24: 25:

Understanding DTDs and XML Schemas CHAPTER 4 Listing 4.4

103

Golfers XML Document’s XML Schema

4 UNDERSTANDING DTDS AND XML SCHEMAS

1: 2: 5: 6: Golfers schema used to validate Listing4.3.xml 7: 8: 9: 10: 11: 12 13: 14: 15: 16: 17: 18: 19: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 37: 39: 40: 41: 42: 43:

104

XML for ASP.NET Developers

The XML schema shown in Listing 4.4 contains all the metadata about the golfers XML document in Listing 4.3 and describes its structure using well-formed XML. Although the XML-DR schema is certainly much more verbose than an equivalent DTD (shown in Listing 4.5), hopefully you’ll agree that it is much easier to read and understand even if you have never seen a schema document before. After you learn the various element, attribute, and data type declarations, you’ll find that creating schemas is a snap. In case you wanted to see how much code the DTD would take for the same XML document, here it is: Listing 4.5 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19:

Golfers DTD Document

Although the XML document in Listing 4.3 references an external schema (Listing 4.4.xdr), the schema could have been included internally within the XML. To do this, you would simply take out the schema namespace reference in the golfers root element and place the schema directly under the golfer element: Golfers schema used to validate Listing4.3.xml

Understanding DTDs and XML Schemas CHAPTER 4

105

......... (remainder of schema would go here) ......... (xml content would go here)

The golfer element calls the schema through using xmlns=”x-schema:#golfers”, where #golfers is used to identify the schema name. Now that you’ve had a chance to look at an XML schema, the next few sections will break it apart and detail each piece used to create it.

Using the Schema Keyword with Namespaces in XML-DR Schemas An XML-DR schema begins with the Schema keyword, a name attribute, and two namespace declarations. The schema in Listing 4.4 started with the following Schema tag: . . . . . . .

WARNING Even slight changes to the namespaces will result in an error if validated by XMLDR–aware parsers.

We’ll use the dt qualified namespace later in the schema to assign specified data types to different elements and attributes. The name attribute is optional, although its inclusion is definitely recommended for schema recognition purposes.

4 UNDERSTANDING DTDS AND XML SCHEMAS

Notice the inclusion of the urn:schemas-microsoft-com:xml-date and dt=”urn:schemasmicrosoft-com:datatypes” namespaces. These are specific to Microsoft’s XML-DR schema version and must appear as shown.

106

XML for ASP.NET Developers

Because XML-DR schemas look, act, and obey the XML rules just like regular XML documents, the beginning tag must be ended appropriately using . The XML-DR Schema keyword is case sensitive and must appear with a capital S as shown.

XML-DR Elements, Groups, and Attributes Listing 4.4 contains a variety of elements and attributes that are used together to make the schema. The following sections describe these in more detail.

XML-DR Elements and Groups Declaring elements in an XML-DR schema is an extremely easy process because it’s a lot like using an element within an XML document. In fact, element declarations are very similar to using the Dim statement in Visual Basic to declare a variable in an ASP.NET page for later use. Going back to Listing 4.4, the lastName element was declared as follows:

The ElementType tag is case sensitive and must be used exactly as shown. The valid attributes that can be used with the ElementType tag are listed in Table 4.4 along with their description. Table 4.4

ElementType Tag Attributes

Attribute

Description

name

The name attribute specifies the name of the element being declared. Names used in the schema must follow XML element-naming rules. Example: The model attribute specifies how strictly or loosely content within an element is managed. Values can include open or closed. A closed model restricts content within the declared element to what the schema declares. Any attempts to add content to the element will fail. An open model allows other content to be added later. Example: The content attribute is similar to the content model used within DTDs. It determines what type of content can be included within the element. Valid values include empty, eltOnly, textOnly, and mixed. An element containing only attributes would be considered empty (because it has no child elements or text), whereas an element containing text and child elements would be considered mixed. Elements that contain no text but that do contain child elements would have a content value equal to eltOnly. Example:

model

content

Understanding DTDs and XML Schemas CHAPTER 4 Table 4.4

continued

Attribute

Description

dt:type

You saw earlier that DTDs restrict element and attribute data types to string values (PCDATA and CDATA) for the most part, although there are a few other types for attributes, such as ID and IDREF. XML schemas (both the XML-DR and W3C XML schema versions) support a variety of data types. The dt prefix corresponds to the qualified namespace declared in the tag. This is prefixed to set this type attribute apart from another one that can be used with the tag (shown later in the chapter). Example: One knock on DTDs is that elements specified in the content model for an element declaration must appear in the order they appear. For example, the following DTD declaration specifies that the golfer element must contain the name and course elements in the order listed. Example: If the golfer element contains a course element that comes before a name element, an error will occur. XML-DR schemas avoid this by using the order attribute. Valid values include one, many, or seq. Specifying one will allow any element from a list to be included. Using many will allow elements in a list to appear (or not appear) in any order, and using seq is like the preceding DTD example—all elements must appear in a specific order. Example:

order

107

The following golfer element declaration has a closed model (no additional items can be added), which can contain elements but not text (eltOnly), and requires that the elements

4 UNDERSTANDING DTDS AND XML SCHEMAS

108

XML for ASP.NET Developers

appear in the sequence listed (name followed by favoriteCourses). It also contains several attribute declarations, which are covered shortly:

Organizing the golfer element declaration in this manner allows for content to be declared once and then reused in other places rather than duplicating the information in multiple places. As an example, the golfer element (and associated content) can be included as a child element of the golfers root element declaration by doing the following:

As you can see, after an element has been declared, it can be used within other elements. This is accomplished by using the tag. Going back to our earlier comparison with ASP.NET, a declaration using the ElementType tag is similar to declaring a variable in an ASP.NET page and then giving it a value. Using the element tag would be similar to assigning the variable (or element) to another variable or object, which is the golfers element in this case. The element tag has several attributes that can be used with it. These attributes, as well as their designated purpose, are listed in Table 4.5. Table 4.5

Element Tag Attributes

Attribute

Purpose

type

The type attribute references the name attribute declared using the tag. Example: This specifies the minimum number of times the element may appear in the current context. Valid values include 0 when the element may nor may not exist and 1 where it must exist at least once. This attribute defaults to a value of 1 if not specified. Example:

minOccurs

Understanding DTDs and XML Schemas CHAPTER 4 Table 4.5

109

continued

Attribute

Purpose

maxOccurs

This specifies the maximum number of times the element may appear in the current context. Valid values include 1 when the element may occur only once and * where it may occur an unlimited number of times. This attribute defaults to a value of 1. Example:

Using the attributes with the element tag is as simple as including them within the tag. The following code sample shows the course element being assigned to the favoriteCourses element using the element tag:

In this example, the course element must occur at least once (minOccurs=”1”). It can also occur as many times as needed (maxOccurs=”*”). If the favoriteCourses element needed to contain a more complex combination of elements, how would you specify this in the schema? For example, assume that the favoriteCourses element can contain two elements named courseDetails and course or one of three elements named courseName, courseLocation, and courseLength. With a DTD, this is easily accomplished by using the pipe (|) and suffix characters, but nothing you’ve learned up to this point allows you to do the same thing in a schema. Implementing this variable combination of elements requires the group element as shown next:

In addition to the order attribute defined in Table 4.4, the group tag also accepts the minOccurs and maxOccurs attributes referenced in Table 4.5.

4 UNDERSTANDING DTDS AND XML SCHEMAS

110

XML for ASP.NET Developers

XML-DR Attributes When Microsoft designed the XML-DR schema, they applied many of the same principles to element and attribute declarations. This means that many of the features associated with elements also apply to the declaration and assignment of attributes:

This example declares four attributes named skill, handicap, clubs, and id, using the AttributeType tag. It then assigns these to the golfer element using the attribute tag. It’s important to note that the AttributeType elements declared have a scope limited to the golfer element. To make them have a global scope, AttributeType elements would need to be moved out on their own, becoming a child of the Schema element. Attributes that can be associated with the AttributeType tag are shown in Table 4.6. Table 4.6

AttributeType Tag Attributes

Attribute

Purpose

name

The name attribute specifies the name of the attribute being declared. Although it may seem somewhat odd that the attribute you are declaring has a name that is actually based on an attribute value, after you use the syntax a few times, it will become comfortable to work with. Names used in the schema must follow XML element-naming rules. Example: default specifies a default value for the attribute. Example: required determines whether a value is required for the attribute being declared that will be used in an XML document. It accepts values of yes and no. Example:

default

required

Understanding DTDs and XML Schemas CHAPTER 4 Table 4.6

111

continued

Attribute

Purpose

dt:type

This determines the data type for the attribute and functions the same as the dt:type attribute used with the ElementType tag. Although elements in a schema cannot be an enumeration data type, attributes can be. When dt:type=”enumeration” is specified on an attribute, the enumerated values are specified using the dt:values attribute. Example:

dt:values

After an attribute has been declared using the AttributeType element tag, it can be referenced by an attribute element anywhere within an ElementType tag. Any attribute tags not contained within an ElementType declaration will cause an error. The attribute element can contain the attributes listed in Table 4.7. Table 4.7

Attribute Tag Attributes

Purpose

type

The type attribute references the name attribute declared using the tag. Example: default specifies a default value for the attribute. If a default value was specified in the AttributeType element, it will be overridden. Example: As with the default attribute, this attribute can override a required attribute declared on the AttributeType element. Possible values include yes and no. Example:

default

required

XML Data Types DTDs are extremely limited in the validation they offer for data contained within an XML document. In fact, DTD data types have no support for basic data types such as integer and date. Fortunately, XML-DR schemas contain excellent data type support. Any text contained within an element or attribute can be assigned a specific data type. If text contained within an element or attribute in an XML document does not match the schema, an error will be raised. Table 4.8

4 UNDERSTANDING DTDS AND XML SCHEMAS

Attribute

112

XML for ASP.NET Developers

lists all the Microsoft XML-DR date types. These types are in addition to the primitive data types already available within DTDs, such as PCDATA, ID, and so on. Table 4.8

XML-DR Data Types

Data Type

Description

bin.base64 bin.hex boolean char date

MIME-style Base64 encoded binary BLOB. Hexadecimal digits representing octets. 0 = “false” and 1 = “true”. One character string. Date in a subset ISO 8601 format. Time data is not included. A bogus date such as 2/31/2000 will pass validation because the date itself is not actually validated. Date in a subset of ISO 8601 format. Time data can optionally be included, although time zone information cannot. Same as dateTime but with an optional time zone added in. Same as “number” but no more than 14 digits to the left of the decimal point and no more than 4 to the right. Real number with no limit on digits. A float can possibly have a leading sign, fractional digits, and optionally, an exponent. Numeric type but with an optional sign, no fractions, and no exponent. Number with no limit on digits. It can optionally have a leading sign, fractional digits, and an exponent. Time in a subset ISO 8601 format. No date or time zone information is included. Time in a subset ISO 8601 format. No date or information is included. Time zone is optional. 1-byte signed integer. 2-byte signed integer. 4-byte signed integer. 8-byte signed integer. Real number with seven-digit precision (4 bytes) Same as a float data type. Single-byte unsigned integer. 2-byte unsigned integer.

dateTime dateTime.tz fixed.14.4 float int number time time.tz i1 i2 i4 i8 r4 r8 ui1 ui2

Understanding DTDs and XML Schemas CHAPTER 4 Table 4.8

113

continued

Data Type

Description

ui4 ui8 uri uuid

4-byte unsigned integer. 8-byte unsigned integer. Universal Resource Identifier (URI). String. Hexadecimal digits representing octets. A uuid can contain embedded hyphens, although they are ignored. This is similar to a COM UUID. For example: “333C7BC4-460F-11D0-BC04-0080C7055A83”.

Data types can be applied to elements or attributes in one of two ways. The first is to use the dt:type attribute on the appropriate element or attribute declaration:

The second is to encapsulate the data type in a datatype element:

Because it is easier and involves less coding, the previous method of declaring the data type within the AttributeType or ElementType elements is more common.

XML-DR Description Element

Golfers schema used to validate Listing4.3.xml

The description element can be used within an AttributeType, ElementType, Schema, group, element, or attribute tag to provide additional information about why things are being done a certain way and can be useful for tracking revisions.

XML-DR Summary XML-DR schemas provide a way to describe XML documents in a more flexible and humanfriendly manner than DTDs. Although these schemas generally require more information and tags, reading XML-DR schemas is much easier than reading an equivalent DTD. Because an XML-DR schema must be written according to standard XML rules, making changes to a

4 UNDERSTANDING DTDS AND XML SCHEMAS

If you have ever walked into a failing project coded by someone else, you know how valuable comments can be. Although coding schemas can be less complex than writing a data-driven ASP.NET page, comments still have their place. Going back to Listing 4.4, the schema contained one description element (or comment) that looked like the following:

114

XML for ASP.NET Developers

schema via an XML parser is a very feasible proposition. Altering a DTD through the use of an XML parser can prove to be very difficult, if not impossible, depending on the parser being used. With all the positive things XML-DR schemas have going for them, why did the W3C create a new schema standard? To answer this completely, you’ll need to read through the next few sections. In short, the W3C XML schema specification provides additional functionality not available in the XML-DR schema.

The W3C XML Schema This section will present you with the main concepts available in the XML schema specification so that you can use XML schemas effectively. To view the full specification, take a look at the “Specifications and Development” section found at the following URL: http://www.w3.org/XML/Schema.

To get you up to speed quickly with XML schemas, Listing 4.6 contains the XML-DR schema you first saw in Listing 4.4, only it has now been converted to the W3C XML schema specification. Listing 4.6

W3C XML Schema

1: 2: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22:

Understanding DTDs and XML Schemas CHAPTER 4 Listing 4.6

115

continued

23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48:

NOTE The preceding example declares a qualified namespace named xsd and associates it with a URI of http://www.w3.org/2001/XMLSchema. Had a default namespace been declared instead (remember that a default namespace applies to everything within the document if it is declared at the root), each of the xsd namespace prefixes shown previously would not be necessary for this XML schema, although a targetNamespace attribute would need to be added as described later in this section. Many of the examples that follow will not list the xsd prefix for simplicity.

4 UNDERSTANDING DTDS AND XML SCHEMAS

At first glance, you may not see much resemblance to Microsoft’s XML-DR schemas. However, many features are found in Microsoft’s version that are very similar in the W3C’s version. The following sections explain a few differences and explain some new concepts defined by the W3C.

116

XML for ASP.NET Developers

W3C Schema Elements and Attributes Aside from a few changes in case (Schema went to schema) and namespace declarations, one major change exists in Listing 4.6’s sample schema as compared to the XML-DR schema shown in Listing 4.4. The new schema specification no longer relies on the ElementType and AttributeType elements to declare an element or attribute. Instead, these two elements have been merged with the element and attribute elements, respectively. The W3C XML schema specification allows for element and attribute declarations using code similar to the following:

or

An element or attribute that is applied to another element can then refer to this declaration through using a ref attribute:

Eliminating the ElementType and AttributeType elements by combining them into the eleand attribute elements makes a lot of sense and should make working with schemas less confusing.

ment

Data Type Definitions Earlier in this chapter, you saw how DTDs provide very little flexibility in declaring element and attribute data types. If you’re designing a DTD for an XML document and want to require that a boolean value be used on a particular attribute, you’re out of luck because DTDs handle only string types. XML-DR schemas improve on this deficiency by adding the capability to include specific data types. The W3C XML schema has taken the concept of data types to an even higher level with the inclusion of the Simple and Complex type elements. As you’ll see in the next few sections, these types allow for added flexibility in how element and attribute types are declared and used within a schema. You had the opportunity to see many data types associated with schemas back in the XML-DR discussion. Although similar types are found in the W3C XML schema specification, the following table contains a complete listing divided into primitive and derived types. This table, along with additional data type information, is available from the following W3C Web site: http://www.w3.org/TR/xmlschema-2/#section-Datatypes-and-Facets.

Understanding DTDs and XML Schemas CHAPTER 4

Numeric false false true true true false false false false false false false false false false false false false false false false false false false false false false false false false false true

4 UNDERSTANDING DTDS AND XML SCHEMAS

Data Type primitive string boolean float double decimal duration dateTime time date gYearMonth gYear gMonthDay gDay gMonth hexBinary base64Binary anyURI QName NOTATION derived normalizedString token language IDREFS ENTITIES NMTOKEN NMTOKENS Name NCName ID IDREF ENTITY integer

117

118

XML for ASP.NET Developers

Data Type nonPositiveInteger negativeInteger long int short byte nonNegativeInteger unsignedLong unsignedInt unsignedShort unsignedByte positiveInteger

Numeric true true true true true true true true true true true true

Figure 4.1 represents a diagram of the different data types in the XML schema specification.

The SimpleType Element The simpleType element allows for the creation of customized data types. Simple types become quite useful whenever you want to implement functionality available in another existing base type but want to restrict how the base data type can be used. For example, assume that you want to use a simpleType element to create a custom data type that is a positive integer between 55 and 100 inclusive: maxInclusive value=”100”/>

This example restricts the custom simpleType to be a positiveInteger data type but also extends it through the use of the minInclusive and maxInclusive XML schema elements. After it is specified, the simpleType can be used to define the data type of an element or attribute:

Understanding DTDs and XML Schemas CHAPTER 4

119

anytype

all Complex types

duration

boolean

dateTime

base64Binary

time

anySimpleType

date

hexBinary

gYearMonth

float

double

string

decimal

normalizedString

integer

token

language

ID

gYear

gMonthDay

anyURI

nonPositiveInteger

long

negativeInteger

int

unsignedLong

Qname

gDay

gMonth

NOTATION

nonNegativeInteger

Name

NMTOKEN

NCName

NNTOKEN

short

unsignedInt

IDREF

ENTITY

byte

unsignedShort

IDREFS

ENTITIES

positiveInteger

unsignedByte

FIGURE 4.1 Diagram of XML schema data types.

Any time a custom type (such as roundScore) is referenced and the xsd namespace prefix is not used throughout the schema because of declaring a default namespace, a namespace specific to the custom type must be defined and used within the schema as shown previously. Otherwise, the custom type will fall within the schema namespace and an error will be triggered when it is not found to be part of the XML schema specification.

UNDERSTANDING DTDS AND XML SCHEMAS

NOTE

4

120

XML for ASP.NET Developers

In cases where more complex restrictions need to be added to a base data type, the pattern element can be used. This element has a value attribute that can accept regular expressions. The following example defines a simpleType named us-zipcode:

The simpleType can also be constructed and associated directly within an element or attribute. However, declaring a simpleType in this manner restricts the scope of the type to be local to the element or attribute it is declared within. This is compared to the global scope associated with a simpleType declared on its own, as a child element of the schema element. An example of a local declaration follows. As mentioned, this declaration is very restricting because it can be used only within the element named score (it cannot be used anywhere else in the document). However, if the simpleType applies only to this one element, it may make sense to declare it this way:

Declaring Complex Types The capability to create reusable templates is a powerful and necessary feature if schemas are to be flexible and support complex XML documents. For example, assume that you have an element that contains four attributes and two elements listed in sequence. By creating a template for this content, you can reuse its structure anywhere in the schema, and other types can even extend its structure. The content model found within a complex type is composed of a variety of items called particles. Each particle is either a local or global declaration, meaning that complex types can reference other XML schema types, elements, compositors (such as sequence, choice, or all), or groups. Alternatively, local particles can be created internally within the complex type. This concept will be solidified more in the examples that follow. Because simple types and complex types can both exist in the same XML schema, naming collisions can occur when both have the same name. As a result, you must name the different types uniquely so that problems caused by naming conflicts do not impede the schema.

Understanding DTDs and XML Schemas CHAPTER 4

121

XML-DR schemas attempt to emulate some of the simple and complex typing through their use of the ElementType and AttributeType elements. However, the W3C XML schema offers a more powerful solution. The following is an example of using a complexType element to encapsulate different elements and attributes:

The sequence element type lets the parser know that the name and favoriteCourses elements must appear in the order shown in the schema: name first, followed by favoriteCourses. If you had wanted to allow one of three elements to potentially appear within an XML document, the sequence element could be replaced by the choice element:

Use of the choice element will result in one of the nested elements being listed. In this example, the name, favoriteCourses, or courseDifficulty elements can be included within an XML document, but only one can exist. If more than one element is used, an error will occur when the XML document is validated against the schema. At times, you may want three different elements to appear in a complexType but don’t care if they appear in an unordered manner. For instance, the code shown next requires that the name, favoritecourse, and courseDifficulty elements all appear within the XML document, but it does not restrict their sequence as the sequence element did earlier:

4 UNDERSTANDING DTDS AND XML SCHEMAS

122

XML for ASP.NET Developers

It’s important to note that the all element can appear only directly after a complex type declaration. This means that it cannot be nested within another particle such as the sequence element. This is contrary to how the sequence and choice elements can be combined to add additional logic:

The preceding example states that either the name element can be appear within an XML document, or a sequence consisting of the favoriteCourses and courseDifficulty elements. By combining choice and sequence elements, some interesting options can be created. Also note that the group element found in the XML-DR schemas is also available to use in the W3C XML schema version in a similar fashion. After the specifics associated with a complex type have been defined, it can then be referenced by name (golferType was used in the previous examples) within another complex type or within an element by using code similar to the following:

Understanding DTDs and XML Schemas CHAPTER 4

123

After complex types have been declared and defined, they can be inherited and extended by other complex types. This is a very powerful feature that allows for reusability resulting in less coding where used appropriately. Taking a break from golfing for a minute and using an animal complexType as an example, as shown in Listing 4.7, a feline and canine type can extend animal using the complexContent and extension elements: Listing 4.7

4 UNDERSTANDING DTDS AND XML SCHEMAS

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33:

Extending Complex Types

124

XML for ASP.NET Developers

Listing 4.8 shows the XML document that the previous XML schema describes. Notice that the cat element lists child elements, including the furColor, legCount, weight, and meows elements. This is because the cat element must include all the elements found within the feline complex type, which is an extension of the animal complex type. Listing 4.8 1: 2: 3: 4: 5: 6: 7: 8: 9:

The XML Document Described by Listing 4.7

Black 4 3 true

Creating Unique Fields, Keys, and Relationships Although DTDs do contain the capability to associate different elements with each other through the use of ID and IDREF attribute types, this association is often difficult to follow and use effectively. Because the capability to provide clear and concise associations is very important as XML continues to rise in popularity among applications and vendors, the XML schema specification includes the capability to associate different elements or attributes in an XML document in much the same way that relational databases provide the capability to join tables through primary and foreign key constraints. Creating a relationship between different elements (or attributes) can be accomplished by using the unique, key, keyref, selector, and field elements along with their supporting attributes. To fully understand how this is accomplished, an example is in order. You are more than likely familiar with the sample Northwind database that ships with Microsoft’s Access and SQL Server products. This database provides information about different customers and orders through a set of relational tables. A given customer can be linked to his or her orders through a CustomerID field found in both the Customers and Orders tables. Figure 4.2 shows the primary/foreign key relationships between the two tables. Listing 4.9 shows how these tables and their relationships could be converted into an XML schema.

Understanding DTDs and XML Schemas CHAPTER 4

Customers

∞

125

Orders

CustomerID CompanyName ContactName ContactTitle Address City Region PostalCode Country Phone Fax

OrderID CustomerID EmployeeID OrderDate RequiredDate ShippedDate ShipVia Freight ShipName ShipAddress ShipCity ShipRegion ShipPostalCode ShipCountry

FIGURE 4.2 Relating the Customers and Orders Tables in the Northwind Database.

Listing 4.9. An XML Schema Representing the Customers and Orders Tables in the Northwind Database

4 UNDERSTANDING DTDS AND XML SCHEMAS

1: 2: 5: 6: 7: This Schema validates against northwind.xml 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21:

126

XML for ASP.NET Developers

Listing 4.9. 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67:

continued

Understanding DTDs and XML Schemas CHAPTER 4 Listing 4.9.

127

continued

68: 70: 72: 74: 76: 78: 79: 80: 81: 82: 83: 84: 86: 87: 88: 89: 90:

After the unique constraint named CustomerID_PK is established, the OrdersTable element can then be related to the CustomersTable element in a primary/foreign key type relationship. Lines 84–88 show how the keyref element can be used to refer to an existing constraint, CustomerID_PK in this case. After the constraint is selected, the selector and field elements can be determined by using xpath statements as detailed in the previous paragraph. In cases

4 UNDERSTANDING DTDS AND XML SCHEMAS

This particular XML schema leverages the unique and keyref elements (shown in bold) to establish relationships. Lines 44–47 establish the CustomerID element (a child element of the CustomersTable element) as being unique and names this constraint CustomerID_PK. This is done by assigning the selector element xpath attribute to a period (.). Thinking back to Chapter 3, you’ll remember that the period (.) represents the context node. In this case, CustomersTable is the current element being worked with, so it is being assigned to the selector element. The field element’s xpath attribute is then assigned to the CustomerID element. In cases where more than one element or attribute makes up a unique constraint, multiple field elements can be listed as children of the unique element, the same as multiple fields can be combined to create a primary key in a relational database. Had this example contained an attribute that must hold a unique value, the xpath attribute of the field element could have listed the path to the attribute instead (for example: @attributeName).

128

XML for ASP.NET Developers

where an element or attribute doesn’t have to be unique but a key needs to be established, the key element can be used in place of the unique element.

Namespace Support in XML Schemas Thinking back to our earlier discussion on DTDs, you’ll recall that one of the weak points of DTDs was that they are incapable of supporting namespaces. As the number of XML documents circulating throughout the world continues to increase, the usage and need for namespaces will increase as well. This, of course, does not bode well for DTDs. To remedy the inability of DTDs to support namespaces, the W3C XML schema working group went to a lot of trouble to ensure that namespace support was built in to the XML schema specification from the ground-up. By doing this, XML schemas will be able to handle more complex XML documents and describe them more effectively. So how are namespaces handled? Let’s take a look. Every XML schema must contain a specific namespace and associated URI that is either default or local, depending on the desires of the schema author. Currently, the namespace that must be used is http://www.w3.org/2001/XMLSchema. So why, you may ask, is this URI needed? In sum, it allows different elements, attributes, and data types declared within an XML schema to be identified as belonging to the XML schema specification. As far as built-in schema data types (discussed earlier), this allows them to be positively identified and allows XML schema authors to create custom data types as long as they are associated with a different namespace. Custom data types come into play when simple types are created, as discussed earlier in the chapter. Although including the URI associated with the XML schema specification is certainly beneficial, XML documents may contain other namespace declarations and associated URIs. Fortunately, these can be handled easily within XML schemas by adding the targetNamespace attribute to the schema root element:

This will associate all top-level components (those that are immediate children of the xsd:schema element) with the namespace URI of http://www.someURI.com. This does not associate any other elements or attributes that are not immediate children of the xsd:schema

Understanding DTDs and XML Schemas CHAPTER 4

129

element with the namespace! This is very important to understand. In cases where other elements or attributes within the schema need to be associated with the namespace as well, the elementFormDefault and attributeFormDefault attributes can be applied to the schema root element. The following example shows how all elements not associated with the XML schema namespace can be associated with the namespace URI contained within the targetNamespace attribute:

In cases where some element declarations should not be associated with the target namespace, they can remain unqualified by adding the form attribute to the element declaration:

Referencing XML Schemas from Within XML Documents

Black 4

4 UNDERSTANDING DTDS AND XML SCHEMAS

After you have created an XML schema document, how do you reference it within your XML document? The answer is surprising simple and involves only using a few attributes and/or namespace declarations that are applied to the root element of the XML document. You saw a simple example of referencing an XML schema that did not have a targetNamespace attribute included within its schema root element back in Listing 4.8. This example used the noNamespaceSchemaLocation attribute along with the schema instance namespace (xsi) to reference the schema named Listing4.7.xsd:

130

XML for ASP.NET Developers

3 true

Had the schema file contained a targetNamespace attribute, the noNamespaceSchemaLocation attribute would be replaced with the schemaLocation attribute. This attribute must contain the URI referenced within the targetNamespace attribute of the schema along with the path to the schema file. The two pieces of information must be separated by a space or carriage return. The root element of the XML document must also declare the schema instance namespace (xsi): Black 4 3 true

Both examples assume that the XML schema document is located within the same directory as the XML document. A file path or URL can be used in cases where the two documents are in separate locations.

XML Schema Summary The current W3C XML schema specification promises to bring an abundance of power to the creation of XML schemas. Although we haven’t covered all the elements and attributes contained within the W3C XML schema specification, we have covered many of the basic building blocks.

Summary This chapter provided you with an in-depth look at DTDs, XML Data–Reduced schemas (XML-DR), and W3C XML schemas. Although DTDs have their pitfalls, they are still very prominent and will be until an implementation of the XML schema recommendation is built in to more parsers and supported throughout different industries. Because ASP.NET relies on the System.Xml assembly for XML parsing, you can avoid many of the shortcomings associated with DTDs by validating your XML documents using XML-DR schemas or the new W3C XML schemas because of the superior support for data types, XMLlike structure, and overall power that schemas have to offer. Keep in mind that although you

Understanding DTDs and XML Schemas CHAPTER 4

131

can certainly use XML-DR schemas for validation, it is recommended that you switch to the W3C XML schema specification since Microsoft provides full support for the schema standards. If you already have a lot of time invested in XML-DR schemas, a few XML software packages (XMLSpy, for instance) are available that already convert between the XML-DR and W3C XML schemas, making it relatively easy to make the switch in the future. The next chapter explores the XmlTextReader, XmlValidatingReader, and XmlTextWriter classes and shows how the information you’ve learned up to this point can be used in real applications to validate XML documents. Stay along for the ride because things from here on out promise to be a little more hands-on and exciting!

4 UNDERSTANDING DTDS AND XML SCHEMAS

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET

IN THIS CHAPTER • Introducing the System.Xml Assembly

134

• In-Memory Versus Forward-Only Parsing • Pull Versus Push Models

135

137

• Using the XmlTextReader Class to Parse XML 138 • Building a SAX-Style Push Model Using the XmlTextReader 145 • Validating XML Documents Using the XmlTextReader and XmlValidatingReader 159 • Creating a Generic Validation Class

162

• Passing Authentication Credentials with the XmlTextReader Class 166 • Using the XmlTextWriter Class to Create XML Documents 166

CHAPTER

5

134

XML for ASP.NET Developers

Introducing the System.Xml Assembly Up to this point in the book, you’ve learned some of the more mundane languages and concepts associated with eXtensible Markup Language(XML). Although XPath, XPointer, XLink, Document Type Definitions(DTDs), and schemas aren’t necessarily going to keep you from sleeping at night because of excitement, they are essential in making XML a useful language. Without being able to access specific areas of an XML document with XPath or ensure that a document is valid with XML schemas, XML would be of little use in building applications. Having said that, let’s jump right into learning about the System.Xml Assembly and see how to leverage some of the classes it contains in your ASP.NET applications. Working with XML in ASP.NET applications requires that you reference a specific namespace. A namespace in the .NET platform is used as an organizational system for program components and is important in resolving naming conflicts (much like XML namespaces). To access XML-specific features of the .NET platform, you must reference the System.Xml namespace in your projects. This namespace is associated with the System.Xml assembly that is installed with the .NET framework. If you’re not familiar with assemblies, the .NET SDK defines them in the following manner: An assembly is a collection of types and resources that are built to work together and form a logical unit of functionality, a “logical” dll. In more basic terms, an assembly takes several physical files, such as interfaces, classes, resource files, and so on, and creates metadata referred to as a manifest about how the files work together. The assembly can also contain information about versioning and security. One of the many benefits of assemblies is that they can be used in ASP.NET applications without adding a CLSID to the registry using regsvr32.exe. If you’ve dealt with “DLL Hell” in the past, you should be very pleased to hear this. Eliminating the regsvr32.exe and registry aspect means that you can build custom assemblies and then simply copy them to the bin directory of your ASP.NET application. No other work is required! The System.Xml assembly contains many of the classes that provide XML functionality in the .NET platform. The following list contains some of the main classes that you’ll find yourself using in XML-related ASP.NET applications. •

XmlAttribute

•

XmlDocument

•

XmlElement

•

XmlNode

•

XmlNamedNodeMap

•

XmlNodeList

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

•

XmlNodeReader

•

XmlTextReader

•

XmlTextWriter

•

XmlValidatingReader

•

XPathDocument

•

XslTransform

135

You’ll see how to use these classes and many others in upcoming chapters. In this chapter we will focus specifically on the XmlTextReader, XmlTextWriter, and XmlValidatingReader classes along with several of their supporting classes. Figure 5.1 gives an overview of how these classes fit together.

XmlReader and XmlWriter Architecture Abstract

XmlReader

XmlTextReader

XML 1.0 XmlWriter Namespaces

XmlNodeReader

Abstract

XmlTextWriter

Support Classes XmlConvert XmlResolver XmlValidatingReader DTD, XSD and XDR Schema Validation

XmlSchemaCollection

XmlNameTable

XmlNamespaceManager

FIGURE 5.1 XmlReader and XmlWriter architecture.

In-Memory Versus Forward-Only Parsing

5 AND

XMLTEXTREADER

XMLTEXTWRITER

Before you see how to work with the classes shown in Figure 5.1, it’s important that you know when and why the classes should be used. In Chapter 6, “Programming the Document Object Model (DOM) with ASP.NET,” you’ll learn how to use the Document Object Model(DOM) (a tree-based Application Program Interface(API)) to access specific nodes within an XML document in a variety of ways, ranging from programmatic access to using XPath statements. To

136

XML for ASP.NET Developers

see when and why you should use the XmlTextReader and XmlTextWriter classes discussed in this chapter, it’s necessary to provide you with a basic overview of how the DOM works. The concept of the DOM is actually very simple. If you think of a genealogical chart containing your family lineage, you’ll recognize that it contains a tree structure with hierarchical relationships in it. For example, if you start with your grandfather in the chart, your mother may be listed under him. You would, of course, be listed under your mother. The DOM works in a manner similar to the genealogical chart just described. Each node found within an XML document is loaded into memory so that a tree hierarchy is constructed with the root node being the start of the hierarchy. By having this tree in memory, the capability to update, delete, and insert nodes is made available through a specific API. Although the programming API exposed by the DOM is very powerful, it can present problems with memory consumption, especially when large XML documents must be parsed. For example, if you have an XML document that is several megabytes in size and each node is loaded into the DOM tree structure and placed into memory, you can imagine how this could tax a computer in cases where multiple XML documents of this size are being processed simultaneously. To overcome some of the potential memory problems associated with using the DOM (the DOM is very useful in some situations, as you’ll see in Chapter 6) and to provide an alternative in cases where the DOM isn’t necessary, the .NET platform includesthe XmlTextReader class. This class “lives” within the System.Xml assembly. Rather than loading the entire document into memory as the DOM does, the reader processes one node at a time in a forward-only manner. This is possible because the XmlTextReader is a stream that parses the XML document into a sequence of XML tokens. Information about these tokens can be obtained through calling different properties and methods built in to the class. This forward-only stream creation means that when an XML document’s root element is reached, only one node is in memory at any given time. When a child node is reached, its ancestors have been parsed, but they are not in memory and going back to them is not an option (remember, the process is forward only). This type of functionality allows one XML token at a time to be checked and processed rather than loading everything into memory as with the DOM. It provides a very low memory alternative that is capable of working with large XML documents efficiently. The XmlTextReader functions by starting with an 8KB buffer that is capable of growing to the size it needs to accommodate the largest token in the stream. For example, a 32KB comment has to be returned as a single, contiguous token, which causes the parser buffer to grow to 32KB in this case. If that is the biggest token that is added to the stream, the buffer will stay that size for the rest of the document.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

137

All attributes are buffered as well because of namespace support. A start tag with 100 attributes will typically require a larger buffer as a result. Even though the buffer size grows to fit the largest token, the XmlTextReader still offers a very memory-conservative approach to dealing with XML documents[md]especially when compared to the DOM. So is the DOM bad? Certainly not! It is very useful in many situations, as you’ll see in Chapter 6.

Pull Versus Push Models There is more than one way to parse an XML document in a forward-only manner. If you’ve worked with XML much in the past, you’re probably familiar with the Simple API for XML (SAX) that relies on an event-based push model. SAX has become popular for parsing XML documents in a fast and efficient manner. Microsoft’s MSXML3 parser contains SAX support that can be used in Visual Basic or C++ applications. Although SAX is not a World Wide Web Consortium(W3C) recommendation and is not even maintained by the W3C, it has become a defacto standard throughout the world when XML documents must be read in a forward-only manner. SAX is actually maintained and developed by David Megginson and several others who belong to an XML-DEV mailing list. SAX is an event-based model that works by pushing out information about different XML nodes it finds in a document to a content handler. The content handler can then process the data it receives, as appropriate. If you’re interested in learning more about SAX and how it works, you can find more information at http://www.megginson.com/SAX/index.html. With the widespread use of SAX, you’re probably thinking that .NET must surely include SAX support, right? Actually, SAX is not “officially” supported in .NET, although you’ll see later in the chapter that a SAX-style model can be created. Instead, the .NET platform provides an alternative pull model for parsing an XML document rather than the push model found in SAX. Why, you ask? There are actually several reasons[md]most of which focus on performance gains. Table 5.1 lists many of these reasons. Table 5.1

Benefits of the Pull Model found in .NET

State Management

Multiple Input Streams

5 AND

XMLTEXTREADER

XMLTEXTWRITER

Layering Test

Push model content handlers must build complex state machines that a pull model client can simplify by managing the state with natural top-down procedural refinement. A pull model allows a client to splice together multiple input streams. Doing this with a push model can be difficult. You can easily build a push model on top of a pull model, whereas the reverse isn’t true. You’ll see an example of this later in the chapter.

138

XML for ASP.NET Developers

Table 5.1

continued

Hints from Client

Avoids Extra Copy

Skipping Items

You can design a pull model API to allow the client to give hints to the parser about what the client expects next. For example, in data type support, when a client knows the next item to process is supposed to be an integer, the parser can parse the integer right out of the parser buffer instead of returning a string subsequently thrown away. A pull model allows the client to give the parser the buffer to write the strings into. This technique avoids the extra copy from the parser buffer to the string object, which is then pushed to the client buffer. The push model must push everything, including the attributes, comments, text, whitespace, and so on. With a pull model, the client pulls only what it’s interested in. If, for example, the client doesn’t read the attributes, those attribute values don’t need to be entity expanded, values “stringized,” names atomized, and so on. This model allows for more efficient messaging-level applications of XML.

Using the XmlTextReader Class to Parse XML Now that you’ve been introduced to the DOM and had the opportunity to see why the .NET platform includes a pull model rather than a push model, as in SAX, it’s time to see how to actually use this pull model to parse XML. Forward-only, noncached XML document parsing is handled by the XmlTextReader class. This class inherits properties and methods from the abstract XmlReader class and is quite simple to instantiate and use. The pull model it provides allows for a lot of flexibility in reading an XML document. To instantiate and use the class, the following code can be used: XmlTextReader xmlReader = new XmlTextReader(xmlDocument);

This version of the constructor allows the file path (a string) to the XML document to be passed as an argument. Several other constructors can be used while instantiating the XmlTextReader as well. For example, a TextReader or Stream can also be passed in as arguments. See the .NET SDK for more details on the different XmlTextReader constructors. After the XmlTextReader object is created, parsing can then begin on the document in a forward-only manner. This is accomplished by using the different properties and methods built in to the class. Table 5.2 lists what properties are available and Table 5.3 lists the available methods.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Table 5.2

139

XmlTextReader Properties

Property

Description

AttributeCount

Returns the number of attributes on the current node. This can be used in looping through the attributes associated with a particular element node. The MoveToNextAttribute() method (see Table 5.3) provides a more efficient manner of doing this, however. Returns the base URI of the current node. Returns a Boolean value based on whether an entity is resolved. Returns the depth of the current node in the XML element stack. Returns the encoding attribute for the XML document being parsed. Returns a Boolean value telling whether the XmlTextReader is positioned at the end of the stream. Returns a Boolean value indicating whether the current node has any attributes. Returns a Boolean value indicating whether the node can have a value. Although many nodes can have values, such as attributes and CDATA sections, others cannot, such as end element tags. Returns a Boolean value that specifies whether the current node is an attribute that was created from the default value defined in the DTD or schema. Returns a Boolean value indicating whether the current node is an empty element, such as ( for example). Returns the value of the attribute when looping through a collection. This is the indexer for the XmlTextReader in C#. Returns the current line number of the position within the XML document. This is similar to the getLineNumber() method associated with the Locator class in SAX. Returns the current line position. This is similar to the getColumnNumber() method in SAX. Returns the name of the current node without the namespace prefix attached to it.

BaseURI CanResolveEntity Depth Encoding EOF HasAttributes HasValue

IsDefault

IsEmptyElement Item LineNumber

LinePosition LocalName Name

5 AND

XMLTEXTREADER

XMLTEXTWRITER

Namespaces

Returns the name of the current node along with any associated namespace prefix. Gets or sets a value indicating whether to do namespace support. Namespace support is the default (true).

140

XML for ASP.NET Developers

Table 5.2

continued

Property

Description

NamespaceURI

Returns the namespace URI of the node the reader is positioned on. Gets the XmlNameTable associated with this implementation. Using the NameTable can result in more efficient object comparisons. An example of using it is shown later in the chapter. You’ll likely use this property very heavily in your ASP.NET applications. It returns the type of the current node based on the XmlNodeType enumeration. Gets or sets a value indicating whether to do whitespace normalization as specified in the WC3 XML recommendation version 1.0 (see http://www.w3.org/TR/1998/REC-xml-19980210). Returns the namespace prefix (if any) of the current node. Returns the quotation mark character used to enclose the value of an attribute node. For example, ‘ or “. Returns the read state of the stream based upon the ReadState enumeration. Possible values can be ReadState.Closed, ReadState.EndOfFile, ReadState.Error, ReadState.Initial, or ReadState.Interactive. Returns the text value of the current node. Gets or sets a value that specifies how whitespace is handled. This property ties into the WhitespaceHandling enumeration. Returns the current xml:lang scope where the current node resides. Gets or sets the XmlResolver used for resolving URLs and/or PUBLIC IDs used in external DTDs. The XmlUrlResolver class inherits from the XmlResolver abstract class and is used to resolve DTD and schema locations. If the directory where the DTD or schema resides requires authentication, the credentials to pass for authentication can be set through this property.

NameTable

NodeType

Normalization

Prefix QuoteChar ReadState

Value WhitespaceHandling XmlLang XmlResolver

XmlSpace

Returns the current xml:space scope where the current node resides. This property is associated with the XmlSpace enumeration that contains values of XmlSpace.None, XmlSpace.Default, XmlSpace.Preserve.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Table 5.3

141

XmlTextReader Methods

Method

Description

Close()

Changes the ReadState to Closed and sets all the properties back to zero. Use in conjunction with the ReadState property. Returns the value of an attribute. Returns the remainder of the buffered XML in cases where a different XmlTextReader may finish reading a document. After this method is called, the EOF property is set to true. Returns true if the current content node is a start element tag. Resolves a namespace prefix that exists within the current element’s scope. Assuming the namespace resolves, the namespace URI will be return in a string value. Move to a specified attribute based on indexed position or name. After calling this method, you can access the Name, NamespaceURI, and Prefix properties associated with that attribute. Checks whether the current node is a content (nonwhitespace text, CDATA, Element, EndElement, EntityReference, or EndEntity) node. If the node is not a content node, the method skips ahead to the next content node or end of file. Nodes that are of type ProcessingInstruction, DocumentType, Comment, Whitespace, or SignificantWhitespace will be skipped over. After navigating through attributes of an element, you can move back to the element by using this method. Moves to the first attribute of an element node. Moves to the next attribute of an element node. This can be used effectively in a while loop to enumerate through any element attributes.

GetAttribute() GetRemainder()

IsStartElement() LookupNamespace()

MoveToAttribute()

MoveToContent()

MoveToElement() MoveToFirstAttribute() MoveToNextAttribute()

Read()

ReadAttributeValue()

AND

XMLTEXTREADER

ReadBinHex

5 XMLTEXTWRITER

ReadBase64

Reads the next XML node from the stream. You will normally use this method within a while loop to parse through an XML document. Reads and parses the attribute value into Text and/or EntityReference node types. Decodes Base64 and returns the decoded binary bytes. Decodes BinHex and returns the decoded binary bytes.

142

XML for ASP.NET Developers

Table 5.3

XmlTextReader Methods

Method

Description

ReadChars

Reads the text contents of an element into a character buffer. The size of the buffer will normally be set initially. Characters are then added to the buffer: int len; while ((len = reader.ReadChars(buffer, 0, buflen)) > 0) { //Call Buffer Function or create String }

ReadElementString() ReadEndElement() ReadInnerXml()

ReadOuterXml()

ReadStartElement() ReadString() ResolveEntity() Skip()

Used to read text-only elements. Verifies that the current node is an element end tag and places the position within the stream to the next node. Reads all the content (including markup) of the current node as a string. If the current node is empty, an empty string will be returned. Reads all the content (including markup) of the current node as a string. This includes the node’s start and end element tags. If the current node is empty, an empty string will be returned. Verifies that the current node is an element and positions the reader on the next node. Reads the contents of an element type node as a string. Resolves the entity reference for EntityReference nodes. Note: The XmlTextReader cannot resolve general entities. Skips the current element node and moves it to the next node if one exists.

Listing 5.1 provides an example of working with some of the XmlTextReader properties and methods to walk through an XML document and write out the XML tokens it finds to the browser. An explanation of the code follows. Listing 5.1. 1: 2: 3: 4: 5: 6: 7:

Using the XmlTextReader Class

public class ReadXmlFile { string output = “”; public string ReadDoc(String doc) { string m_Document = doc; XmlTextReader xmlReader = null;

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Listing 5.1.

continued try { xmlReader = new XmlTextReader(m_Document); WriteXml(xmlReader); } catch (Exception e) { output += “Error Occurred While Reading “ + m_Document + “ “ + e.ToString(); } finally { if (xmlReader != null) xmlReader.Close(); } return output; } private void WriteXml(XmlTextReader xmlReader) { while (xmlReader.Read()) { if (xmlReader.NodeType == XmlNodeType.Element) { output += indent(xmlReader.Depth*4); output += “<” + xmlReader.Name + “”; while (xmlReader.MoveToNextAttribute()) { output += “ ” + xmlReader.Name + “=\”” + xmlReader.Value + “\” ”; } if (xmlReader.IsEmptyElement) { output += “/>”; } else { output += “>”; } } else if (xmlReader.NodeType == XmlNodeType.EndElement) { output += indent(xmlReader.Depth*4); output += “”; } else if (xmlReader.NodeType == XmlNodeType.Text) { if (xmlReader.Value.Length != 0) { output += indent(xmlReader.Depth*4); output += “” + xmlReader.Value “”; } } }

AND

XMLTEXTREADER

} private string indent(int number) { string spaces = “”; for (int i=0; i < number; i++) {

5 XMLTEXTWRITER

8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: + 43: 44: 45: 46: 47: 48: 49: 50:

143

144

XML for ASP.NET Developers

Listing 5.1.

continued

51: spaces += “ ”; 52: } 53: return spaces; 54: } 55: } //End Class 56: 57: private void Page_Load(Object sender, EventArgs e) { 58: ReadXmlFile readXmlFileSample = new ReadXmlFile(); 59: output.InnerHtml = 60: readXmlFileSample.ReadDoc(Server.MapPath(“golfers.xml”)); 61: } 62: 63: 64: 65: 66: 67: 68: Working with the XmlTextReader Class 69: 70:

71: 72: 73:

This example starts by referencing the System.Xml assembly in line 1. Doing this allows access to all the classes found within the assembly, including the XmlTextReader class needed for this application. After the page is hit, the Page_Load() event takes care of instantiating the ReadXmlFile class (line 58). After the class is instantiated, the ReadDoc() method is called and the path to the XML document is passed in as an argument (line 60). The ReadDoc() method takes care of instantiating the reader by passing the file path to its constructor. It then passes the newly created XmlTextReader object to the WriteXml() (line 22) method. Each node in the XML document is processed as it is reached. This processing begins with a call to the XmlTextReader’s Read() method (line 23). As each token in the stream is read, the node type is checked. If the node type is equal to XmlNodeType.Element, the MoveToNextAttribute() method is called within a while loop (lines 27–30). Any existing attributes are iterated through and displayed, as appropriate. If the node is not an element but is instead an element end tag (XmlNodeType.EndElement), the appropriate closing tag is included (line 38). If the node is actually a text node (XmlNodeType.Text), the text is included, but the font color is set to red so that the data stands out more (lines 41–44). The text is read by calling the Value property.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

145

Each node is indented a specified amount by checking the XmlTextReader’s Depth property. This property automatically tracks how deep you are into an XML document’s hierarchical structure, making it very easy to display the document in a properly formatted manner or simply track parent/child relationships. After the entire document has been parsed, it is written out to the browser. Note that the attributes are not automatically passed to you, as with SAX. If you didn’t want to work with any attributes, they could simply be skipped over. The same logic follows for text nodes, processing instructions, comments, and so on. Until you tell the code to pull these different node types from the stream, they are simply ignored, which keeps buffer sizes minimal and results in very fast and efficient XML document parsing. The XmlTextReader can also be associated with the XmlNameTable class to increase efficiency even more in certain scenarios. The XmlNameTable class is capable of holding a table of atomized string values and is useful when the same element, namespace, or attribute name is compared multiple times while reading the XML document stream. Instead of doing costly string comparisons, the XmlNameTable can do object pointer comparisons. For example, if a conditional check is done on a particular namespace URI many times while parsing, the URI can be added to the XmlNameTable as shown next to increase efficiency: XmlTextReader reader = new XmlTextReader(url); object myUri = reader.NameTable.Add(“http://www.SomeServer.com/namespaceURI”);

As the stream of XML tokens is read, a direct object pointer comparison can then be made against the XmlNameTable object: if (reader.NamespaceURI.Equals(myUri)) { //Do special processing if the two URI values are equal }

This method of testing for a URI value is in contrast to the following less-efficient way of doing the same conditional test: if (reader.NamespaceURI == “http://www.SomeServer.com/namespaceURI”) { //Do special processing if the two URI values are equal }

Building a SAX-Style Push Model Using the XmlTextReader

AND

XMLTEXTREADER

XMLTEXTWRITER

Earlier in the chapter, it was mentioned that a SAX-style push model could be built from a pull model but that the reverse was not true. This is possible because with a pull model you determine what should be pulled and when it should be pulled. With a push model you have no control over what you get because everything found in the document is pushed to you via events.

5

146

XML for ASP.NET Developers

Before jumping into the code used to create the SAX parser, you may wonder why you would want to create this in the first place, especially because the pull model exposed by the XmlTextReader is so efficient already. The first answer to this question is that SAX is very popular throughout the world. Because of its popularity, many applications being ported to .NET may have SAX ContentHandlers with a lot of code in them that functions well. Converting all this code to work directly with the XmlTextReader could be costly from a management perspective. Rather than rewriting these handlers, the code that will be shown could be used temporarily while other parts of the application are ported to .NET. If you don’t buy the previous reason for creating the SAX parser class in .NET (hey, I gave it my best shot!), suffice it to say that creating a SAX parser provides an excellent stage for displaying just how powerful the XmlTextReader can be in .NET applications. Through seeing the process of creating the SAX parser, you’ll become more familiar with different ways that the XmlTextReader can be used and see a few other things you can do with .NET classes. If you’ve used SAX in the past, you’re probably intimately familiar with the different parts of the SAX parser ContentHandler interface. Listing 5.2 shows this SAX interface converted to a .NET interface. Listing 5.2

The IContentHandler Interface (IContentHandler.cs)

1: using XmlParsers.Sax.Helpers; 2: interface IContentHandler { 3: 4: void setDocumentLocator(Locator locator); 5: 6: void startDocument(); 7: 8: void endDocument(); 9: 10: void processingInstruction(string target, string data); 11: 12: void startPrefixMapping(string prefix, string uri); 13: 14: void endPrefixMapping(string prefix); 15: 16: void startElement(string namespaceURI, string localName, 17: string rawName, Attributes atts); 18: 19: void endElement(string namespaceURI, string localName,string rawName); 20:

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Listing 5.2 21: 22: 23: 24: 25:

147

continued void characters(char[] ch, int start, int end); void ignorableWhitespace(char[] ch, int start, int end); void skippedEntity(string name);

If you’re not familiar with this interface, it’s actually quite simple to understand. The different interface members are called by the SAX parser as it parses an XML document. For example, when the document parsing starts, startDocument() is called. When an element type node is found within the document, startElement() is found and any attributes associated with the element are passed as arguments (whether you want them or not). This push process continues until the end of the document is reached (endDocument()). A few classes are required by SAX that are not built in to the .NET platform. Fortunately, creating custom classes to emulate the classes that the SAX ContentHandler expects is very straightforward. Listing 5.3 shows some helper classes and a struct that were created to enable SAX-like functionality in the IContentHandler interface (and in the IErrorHandler interface, which is not shown here). More specifically, the code takes care of creating a SAXParseException, Attributes, and Locator class. The Attributes class contains a collection of attributes that will be passed as an argument to startElement() in the ContentHandler. The Locator class allows the line position and column position of the SAX parser to be tracked as it is parsing the XML document. Listing 5.3

5 AND

XMLTEXTREADER

namespace XmlParsers.Sax.Helpers { using System; using System.Collections; public class SAXParseException { string lineNumber = “”; string systemID = “”; string message = “”; public string getLineNumber() { return lineNumber; } public string getSystemID() { return systemID; } public string getMessage() { return message; }

XMLTEXTWRITER

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16:

Creating SAX Helpers (SAXHelpers.cs)

148

XML for ASP.NET Developers

Listing 5.3 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60:

continued public string LineNumber { set { lineNumber = value; } } public string SystemID { set { systemID = value; } } public string Message { set { message = value; } } } public class Locator { int lineNumber; int columnNumber; public Locator() { lineNumber = 0; columnNumber = 0; } public int LineNumber { set { lineNumber = value; } } public int ColumnNumber { set { columnNumber = value; } } public int getLineNumber() { return lineNumber; } public int getColumnNumber() { return columnNumber; } } public struct SaxAttribute { public string Name;

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Listing 5.3 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83:

149

continued public string NamespaceURI; public string Value; } public class Attributes { public ArrayList attArray = new ArrayList(); public int getLength() { return attArray.Count; } public string getQName(int index) { SaxAttribute saxAtt = (SaxAttribute)attArray[index]; return saxAtt.Name; } public string getValue(int index) { SaxAttribute saxAtt = (SaxAttribute)attArray[index]; return saxAtt.Value; } public Attributes TrimArray() { attArray.TrimToSize(); return this; } }

}

After all the classes expected by the SAX ContentHandler and ErrorHandler interfaces are created and ready to be used, the actual implementation of the SAX parser can be constructed through using the XmlTextReader class, along with a few others. Listing 5.4 shows this implementation and is followed by step-by-step details on what the code is doing. Listing 5.4

5 AND

XMLTEXTREADER

namespace XmlParsers.Sax { using System; using System.Xml; using System.Collections; using XmlParsers.Sax.Handlers; using XmlParsers.Sax.Helpers; /// /// The SaxParser class build a SAX push model /// from the pull model found in the XmlTextReader. /// public class SaxParser { private ContentHandler Handler = null;

XMLTEXTWRITER

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12:

Constructing a SAX Parser Using the XmlTextReader Class (SAXParser.cs)

150

XML for ASP.NET Developers

Listing 5.4 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57:

continued private ErrorHandler errorHandler = null; public void setErrorHandler(ErrorHandler errorHandler) { this.errorHandler = errorHandler; } public void setContentHandler(ContentHandler handler) { this.Handler = handler; } public void parse(string url) { int buflen = 500; char[] buffer = new char[buflen]; Stack nsstack = new Stack(); Locator locator = new Locator(); SAXParseException saxException = new SAXParseException(); Attributes atts; XmlTextReader reader = null; try { reader = new XmlTextReader(url); object nsuri = reader.NameTable.Add( “http://www.w3.org/2000/xmlns/”); Handler.startDocument(); while (reader.Read()) { int len; string prefix; locator.LineNumber = reader.LineNumber; locator.ColumnNumber = reader.LinePosition; Handler.setDocumentLocator(locator); switch (reader.NodeType) { case XmlNodeType.Element: nsstack.Push(null);//marker atts = new Attributes(); while (reader.MoveToNextAttribute()) { if (reader.NamespaceURI.Equals(nsuri)) { prefix = “”; if (reader.Prefix == “xmlns”) { prefix = reader.LocalName; } nsstack.Push(prefix); Handler.startPrefixMapping(prefix, reader.Value); } else { SaxAttribute newAtt = new SaxAttribute(); newAtt.Name = reader.Name; newAtt.NamespaceURI = reader.NamespaceURI;

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Listing 5.4

continued newAtt.Value = reader.Value; atts.attArray.Add(newAtt);

5 AND

XMLTEXTREADER

} } reader.MoveToElement(); Handler.startElement(reader.NamespaceURI, reader.LocalName, reader.Name, atts.TrimArray()); if (reader.IsEmptyElement) { Handler.endElement(reader.NamespaceURI, reader.LocalName, reader.Name); } break; case XmlNodeType.EndElement: Handler.endElement(reader.NamespaceURI, reader.LocalName, reader.Name); while (prefix != null) { Handler.endPrefixMapping(prefix); prefix = (string)nsstack.Pop(); } break; case XmlNodeType.Text: while ((len = reader.ReadChars(buffer, 0, buflen))>0) { Handler.characters(buffer, 0, len); } //After read you are automatically put //on the next tag so you have to //call the proper case from here. if (reader.NodeType == XmlNodeType.Element) { goto case XmlNodeType.Element; } if (reader.NodeType == XmlNodeType.EndElement) { goto case XmlNodeType.EndElement; } break; case XmlNodeType.ProcessingInstruction: Handler.processingInstruction(reader.Name, reader.Value); break; case XmlNodeType.Whitespace:

XMLTEXTWRITER

58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85: 86: 87: 88: 89: 90: 91: 92: 93: 94: 95: 96: 97: 98: 99:

151

152

XML for ASP.NET Developers

Listing 5.4 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125:

continued char[] whiteSpace = reader.Value.ToCharArray(); Handler.ignorableWhitespace(whiteSpace,0,1); break; case XmlNodeType.Entity: Handler.skippedEntity(reader.Name); break;

} } //While Handler.endDocument(); } //try catch (Exception exception) { saxException.LineNumber = reader.LineNumber.ToString(); saxException.SystemID = “”; saxException.Message = exception.GetBaseException().ToString(); errorHandler.error(saxException); } finally { if (reader.ReadState != ReadState.Closed) { reader.Close(); } } } //parse() } //SAXParser } //namespace

Let’s take a step-by-step look at what is happening in the code shown in Listing 5.4.

Step 1: Referencing Assemblies The namespace XmlParsers.Sax is declared and several assemblies are made available to the SAXParser class, including the System.Xml assembly shown in line 3. The helper classes shown in Listing 5.3 are also referenced (XmlParser.Sax.Helpers) along with the necessary content handlers (XmlParser.Sax.Handlers). 1: 2: 3: 4: 5: 6:

namespace using using using using using

XmlParsers.Sax { System; System.Xml; System.Collections; XmlParsers.Sax.Handlers; XmlParsers.Sax.Helpers;

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

153

Step 2: Setting the Handlers The setErrorHandler() and setContentHandler() methods take care of letting the SAXParser class know which objects to pass information to as the stream of XML is read or when an error occurs. 12: 13: 14: 15: 16: 17: 18: 19:

private ContentHandler Handler = null; private ErrorHandler errorHandler = null; public void setErrorHandler(ErrorHandler errorHandler) { this.errorHandler = errorHandler; } public void setContentHandler(ContentHandler handler) { this.Handler = handler; }

Step 3: Declaring the XmlTextReader Class After the ContentHandler and ErrorHandler classes are set, the parse() method of the SAXParser class can be called with the path to the XML document being passed in as a parameter. Within the parse() method, several objects are created, including those necessary to handle buffering (lines 21–22), namespace prefixes (line 23), the ContentHandler Locator and Attributes objects (line 24, line 26), and the ErrorHandler SAXParseException object (line 25). Finally, line 27 shows an XmlTextReader object named reader being set to null. 20: 21: 22: 23: 24: 25: 26: 27:

public void parse(string url) { int buflen = 500; char[] buffer = new char[buflen]; Stack nsstack = new Stack(); Locator locator = new Locator(); SAXParseException saxException = new SAXParseException(); Attributes atts; XmlTextReader reader = null;

Step 4: Instantiating the XmlTextReader Class

5 AND

XMLTEXTREADER

XMLTEXTWRITER

The next section of code begins the try portion of a try/catch/finally block and then takes care of instantiating the XmlTextReader class. Notice that the path to the XML document that will be parsed is passed into the constructor. This path was originally passed into the parse() method as a string (shown in Step 3). Line 31 shows the creation of an XmlNameTable object as well. In cases where you will do numerous comparisons between a particular string value and an XML token returned by the XmlTextReader during parsing, you’ll want to consider using an XmlNameTable. This is because object comparisons can be done during the parsing process that offer performance benefits over regular string comparisons. In Step 6, you’ll learn more about how the XmlNameTable object named nsuri (line 30) is used.

154

XML for ASP.NET Developers

28: 29: 30: 31:

try { reader = new XmlTextReader(url); object nsuri = reader.NameTable.Add( “http://www.w3.org/2000/xmlns/”);

Step 5: Reading from the Stream Assuming the XML document identified by the file path passed into the constructor of the XmlTextReader is found, the stream of XML tokens are now ready to be read. If the file is not found, the catch block will be hit, which will cause the ErrorHandler to be called (shown later). Before the stream reading begins, however, the ContentHandler’s startDocument() method is called to let it know that parsing is about to begin (line 32). After the ContentHandler has been notified, the process of reading the stream is started by calling the XmlTextReader’s Read() method from within a while statement, as shown in line 33. This method will return true as long as the end of the stream has not been reached. Lines 36–38 show how information about the reader’s position within the stream can be passed to the ContentHandler. After this information has been passed, the bulk of the parsing work begins as the reader’s NodeType property is checked within a switch statement (line 39). 32: 33: 34: 35: 36: 37: 38: 39:

Handler.startDocument(); while (reader.Read()) { int len; string prefix; locator.LineNumber = reader.LineNumber; locator.ColumnNumber = reader.LinePosition; Handler.setDocumentLocator(locator); switch (reader.NodeType) {

Step 6: Checking for Element Nodes Now that we’re within the switch statement, each XML token read from the stream can be checked against the XmlNodeType enumeration. The case statement shown in line 40 will be hit if an element type node is found in the stream. Because element nodes are the main structural component of an XML document, the bulk of the parsing work will be done within this particular case. Line 41 starts things off by creating a null entry into a stack object named nsstack. This object will be used to track namespace prefixes that may be found on a given element so that the ContentHandler’s startPrefixMapping() method can pass this information (shown in lines 45–51). Line 42 then creates a SAX helper class named Attributes that is used to hold any attributes found on a given element. To enumerate through any existing attributes, the XmlTextReader’s MoveToNextAttribute() method can be called as shown in line 43. This method returns a value of true each time an attribute is found. Lines 53–59 take care of

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

155

adding each attribute’s Name, NamespaceURI, and Value to the Attributes object collection. Notice that as the attributes are being enumerated through, the NamespaceURI property of the reader object is being compared to the XmlNameTable object named nsuri (line 44). As mentioned earlier, this object-to-object comparison results in performance gains over simply comparing strings, as shown next: if (reader.NamespaceURI == “http://www.w3.org/2000/xmlns/”) { ........ }

After all attributes has been enumerated through (assuming some existed in the first place), the XmlTextReader’s MoveToElement() method is called to get back on the original element. Now that the necessary information about the element has been gathered, the ContentHandler’s startElement() method is called and the objects detailed earlier along with information about the element itself are passed in as arguments (lines 63–65). After this is completed, a check is made to see whether the element’s content model is empty (line 66). If it is, the endElement() method is called to let the ContentHandler know that the parser will be moving on to other nodes within the XML document.

5 AND

XMLTEXTREADER

case XmlNodeType.Element: nsstack.Push(null);//marker atts = new Attributes(); while (reader.MoveToNextAttribute()) { if (reader.NamespaceURI.Equals(nsuri)) { prefix = “”; if (reader.Prefix == “xmlns”) { prefix = reader.LocalName; } nsstack.Push(prefix); Handler.startPrefixMapping(prefix, reader.Value); } else { SaxAttribute newAtt = [sr] new SaxAttribute(); newAtt.Name = reader.Name; newAtt.NamespaceURI = [sr] reader.NamespaceURI; newAtt.Value = reader.Value; atts.attArray.Add(newAtt); } } reader.MoveToElement(); Handler.startElement(reader.NamespaceURI, reader.LocalName, reader.Name, atts.TrimArray());

XMLTEXTWRITER

40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65:

156

XML for ASP.NET Developers

66: 67: 68: 69: 70:

if (reader.IsEmptyElement) { Handler.endElement(reader.NamespaceURI, reader.LocalName, reader.Name); } break;

Step 7: Checking for End Element Nodes The next case statement simply checks whether the current XML Token being read from the stream is of type XmlNodeType.EndElement. As with empty elements, an end element that is found in the stream will cause the ContentHandler’s endElement() method to be called so that it knows the current element has been completely processed. This section of code also takes care of reading off of the stack object nsstack and calling endPrefixMapping()(lines 74–77). 71: 72: 73: 74: 75: 76: 77: 78:

case XmlNodeType.EndElement: Handler.endElement(reader.NamespaceURI, reader.LocalName, reader.Name); while (prefix != null) { Handler.endPrefixMapping(prefix); prefix = (string)nsstack.Pop(); } break;

Step 8: Reading Text Nodes Although the capability to handle element nodes (both start and end elements) is certainly useful, getting to the text contained within these elements is a necessity if the data is to be of any use. Fortunately, the XmlTextReader makes it easy to handle text nodes by using the ReadChars() method. Lines 80–83 show how this method is used. First, notice that the ReadChars() method accepts several arguments, including the buffer to write characters to (appropriately named buffer in this case), the position within the buffer to start writing to, and the number of characters to write into the buffer. If you remember back to Step 3 (lines 21 and 22) the size of the buffer along with the actual buffer itself were defined. In this example, the size of buflen is set to 500. In cases where a text node is greater than 500 characters, the while loop will take care of filling the buffer repeatedly with 500 characters at a time until all characters within the text node have been handled. After reading the characters, the XmlTextReader automatically places itself on the next XML token within the stream. This means that you do not explicitly have to tell it to move, because it does the moving for you. As a result of this behavior, lines 87–93 take care of checking what the new node type is that the reader is positioned on and calls the proper case statement depending on the node type. If these statements were omitted, several start or end elements could be skipped and left unprocessed.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 79: 80: 81: 82: 83: 84: 85: 86: 87: 88: 89: 90: 91: 92: 93: 94:

157

case XmlNodeType.Text: while ((len = reader.ReadChars(buffer, 0, buflen))>0) { Handler.characters(buffer, 0, len); } //After read you are automatically put //on the next tag so you have to //call the proper case from here. if (reader.NodeType == XmlNodeType.Element) { goto case XmlNodeType.Element; } if (reader.NodeType == XmlNodeType.EndElement) { goto case XmlNodeType.EndElement; } break;

Step 9: Handling Processing Instructions, Whitespace, and Entities As processing instruction, whitespace, and entity node types are encountered during the parsing process, each is passed to the appropriate method within the ContentHandler, as shown in the following code. As you look through the code, you’ll see that this process is fairly straightforward. 95: 96: 97: 98: 99: 100: 101: 102: 103: 104: 105: 106:

case XmlNodeType.ProcessingInstruction: Handler.processingInstruction(reader.Name, reader.Value); break; case XmlNodeType.Whitespace: char[] whiteSpace = reader.Value.ToCharArray(); Handler.ignorableWhitespace(whiteSpace,0,1); break; case XmlNodeType.Entity: Handler.skippedEntity(reader.Name); break;

Step 10: Ending the Parsing Process and Catching Errors

5 AND

XMLTEXTREADER

XMLTEXTWRITER

If the XML document is parsed completely by the XmlTextReader, the endDocument() method is called on the ContentHandler (line 109). If an error arises during the parsing process, such as the XML document not being found or not being well-formed, the error will be caught by

158

XML for ASP.NET Developers

the catch block shown in lines 111–117. This block takes care of calling the ErrorHandler object so that the error can be reported to the SAX application. After the parsing process has completed, the finally block will be called. This block takes care of ensuring that the XmlTextReader is not already closed through checking the ReadState property. 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122:

Handler.endDocument(); } //try catch (Exception exception) { saxException.LineNumber = reader.LineNumber.ToString(); saxException.SystemID = “”; saxException.Message = exception.GetBaseException().ToString(); errorHandler.error(saxException); } finally { if (reader.ReadState != ReadState.Closed) { reader.Close(); } }

Step 11: Calling the SAX Parser from an ASP.NET Page After reading through all the code explanations in the previous 10 steps, you should have a good idea of what features the XmlTextReader class has to offer. The only thing left to show is how an ASP.NET page can instantiate and use the SAXParser class and its associated handler classes to parse an XML document. Listing 5.5 shows the segment of code from a file named SAXTest.aspx that instantiates the SAXParser class. Listing 5.5

Using the SAXParser Class from an ASP.NET Page

1: public void StartSAX() { 2: Response.Write(“Starting SAX Parsing....

”); 3: SaxParser parser = new SaxParser(); 4: ContentHandler handler = new ContentHandler(Request,Response); 5: ErrorHandler errorHandler = new ErrorHandler(Request,Response); 6: parser.setContentHandler(handler); 7: parser.setErrorHandler(errorHandler); 8: try { 9: parser.parse(Server.MapPath(“SAXTest.xml”)); 10: } 11: catch (Exception exp) { 12: Response.Write(exp.ToString()); 13: } 14: }

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

159

The ContentHandler class in this example receives data about different nodes in the XML document and then writes the results out to the browser. However, the same code (with minor modifications) could be used to update a database, text file, or other data store. In concluding the discussion on creating a .NET version of the SAX parser by using the XmlTextReader class, it’s important to keep in mind that it is always recommended that you use the XmlTextReader directly in your ASP.NET applications. It is engineered to provide fast and efficient support of XML document parsing.

Validating XML Documents Using the XmlTextReader and XmlValidatingReader XML provides a very useful and extensible framework for marking up data that can be exchanged between applications in a platform-neutral manner. However, the capability to create your own XML element and attribute names does come with a price. This price comes into play when you want to exchange XML documents with other people or applications not familiar with your document structure. Thinking back to Chapter 4, “Understanding DTDs and XML Schemas,” you’ll recall that three types of documents have been created to handle this problem and make exchanging XML documents a feasible and efficient proposition. As a refresher, this chapter presented you with information on DTDs, XML Data-Reduced Schemas (XML-DR), and W3C XML schemas (XSD). In this section you’ll see how to apply the knowledge you gleaned from Chapter 4 to your ASP.NET applications. If you’ve worked with MSXML3, you’re probably familiar with using the validateOnParse property or validate() method to validate XML documents against DTDs or XDR schemas. With the validateOnParse property, a document can be validated as it is parsed into the DOM structure while the validate() method allows for runtime validation of a document that has already been parsed and loaded. Although validating XML documents in .NET applications is quite a bit different from the MSXML3 mechanism, the manner in which documents are validated is much more efficient and flexible now.

5 AND

XMLTEXTREADER

XMLTEXTWRITER

The validation process involves the XmlTextReader because it provides fast, forward-only, noncached access to XML documents. However, the XmlTextReader doesn’t have any properties or methods that can handle the validation process. Instead, the XmlTextReader is used in conjunction with another class named the XmlValidatingReader. This class inherits from the abstract XmlReader class just as the XmlTextReader does. In fact, almost all the properties and methods found in the XmlTextReader are also found in the XmlValidatingReader. However, the XmlValidatingReader is designed specifically to validate XML documents or read XML fragments (shown in Chapter 9, “SQL Server 2000, XML, and ASP.NET”).

160

XML for ASP.NET Developers

Instantiating the XmlValidatingReader The XmlValidatingReader has three constructors that can be used to initialize it. The first one accepts an XmlTextReader as an argument, whereas the remaining two accept several arguments and handle XML fragments such as those returned from SQL Server 2000. You’ll be exposed to the other constructors in Chapter 9. To validate XML documents, you’ll want to use the first constructor as shown next: XmlValidatingReader vReader = new XmlValidatingReader(reader);

The XML document that is parsed by the reader object (an XmlTextReader object) is used by the XmlValidatingReader as it does comparisons of the XML document against DTDs or schemas.

Setting the ValidationType After the XmlValidatingReader class is instantiated, its ValidationType property can be set to the proper ValidationType enumeration member: vReader.ValidationType = ValidationType.Auto;

Table 5.4 shows the different members of the ValidationType enumeration. Table 5.4

ValidationType Enumeration

Member Name

Description

Auto

If the XmlValidatingReader’s ValidationType property is not set, this member will be used as the default. The .NET SDK lists the following rules about the Auto member: If there is no DTD or schema, it will parse the XML without validation. If there is a DTD defined in a declaration, it will load the DTD and process the DTD declarations such that default attributes and general entities will be made available. General entities are loaded and parsed only if they are used (expanded). If there is no declaration but there is an XSD schemaLocation attribute, it will load and process those XSD schemas, and it will return any default attributes defined in those schemas. If there is no declaration and no XSD or XDR schema information, the parser is a non-validating parser (that is, ValidationType=ValidationType.None) If there is no declaration and no XSD schemaLocation attribute but there are some namespaces using the MSXML x-schema: URN prefix, it will load and process those schemas, and it will return any default attributes defined in those schemas.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

161

TABLE 5.4 continued Member Name

DTD None

Schema

XDR

Description If there is no declaration but there is a schema declaration (), it will validate using the in-line schema. Allows for validation against a DTD only. Creates the equivalent of a nonvalidating parser. No validation errors will be thrown when this is used. Validate against XSD schemas. Validate against XDR schemas.

Using the XmlSchemaCollection Class If you will be validating against XDR or XSD schemas, the XmlSchemaCollection class can be used to cache your schemas, thus providing performance benefits. Using the XmlSchema Collection class is as simple as instantiating it and then calling the Add() method: XmlSchemaCollection schemaCol = new XmlSchemaCollection(); schemaCol.Add(“http://www.someURI.com”,”schema.xsd”);

The Add() method has several overloaded forms that can be used. The preceding version accepts the namespace associated with the schema (normally the targetNamespace URI for XSD schemas) and the name of the schema document. The Add() method can be called multiple times in cases where several schemas are used in an application for validation. The main benefit of using this class to hold different schemas is that the schemas do not have to be reloaded each time validation needs to take place because they can be pulled from the schema cache. After adding the appropriate schemas to the collection, the XmlValidatingReader (named vReader in this example) needs to be associated with the collection to take advantage of its caching features: vReader.Schemas.Add(schemaCol);

Attaching Event Handlers 5 AND

XMLTEXTREADER

XMLTEXTWRITER

After the XmlValidatingReader has been instantiated and its properties have been set, the reader must be hooked up to an event handler that will be called if an error occurs during the validation process. In .NET, event handlers can be attached to an object by using += and subtracted by using the -= syntax. The XmlValidatingReader has one event named Validation EventHandler that can be attached to catch errors that may arise. Attaching to the event

162

XML for ASP.NET Developers

involves using the += syntax along with specifying the callback handler that should be called if a validation error occurs. After the event handler is attached, the Read() method is called on the XmlValidatingReader object to start validating the XML document. vReader.ValidationEventHandler += new ValidationEventHandler(this.ValidationCallBack); // Parse through XML while (vReader.Read()){}

The callback handler (named ValidationCallBack()) is shown in the following code segment. Note that an external class with specific error-handling capabilities could be referenced as well. private void ValidationCallBack(object sender, ValidationEventArgs args) { //Deal with any errors here }

Creating a Generic Validation Class Now that you’ve seen what is involved with using the XmlValidatingReader, let’s put all these concepts together to build a generic validating class that could be called from any ASP.NET page when validation against a DTD, XDR, or XSD schema is needed. Listing 5.6 shows this class named Validator. Listing 5.6

A Generic Validation Class (validator.cs)

1: namespace XmlParsers.Validation { 2: using System; 3: using System.Xml; 4: using System.Xml.Schema; 5: using System.IO; 6: using System.Text; 7: using System.Net; 8: /// 9: /// The Validator class encapsulates XML validation functionality 10: /// 11: public class Validator { 12: bool _valid; 13: bool _logError; 14: string _logFile; 15: string _xmlFilePath; 16: XmlTextReader xmlReader = null; 17: XmlValidatingReader vReader = null; 18: 19: public bool Validate(string xmlFilePath, 20: XmlSchemaCollection schemaCol, 21: bool logError,string logFile) {

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Listing 5.6

continued _logError = logError; _logFile = logFile; _xmlFilePath = xmlFilePath; _valid = true; try { xmlReader = new XmlTextReader(_xmlFilePath); vReader = new XmlValidatingReader(xmlReader); if (schemaCol != null) { vReader.Schemas.Add(schemaCol); } vReader.ValidationType = ValidationType.Auto; /* Provide your own resolver if implementing a custom * caching mechnism * XmlUrlResolver resolver = new XmlUrlResolver(); * vReader.XmlResolver = resolver; */ vReader.ValidationEventHandler += new ValidationEventHandler(this.ValidationCallBack); // Parse through XML while (vReader.Read()){} } catch { valid = false; } finally { //Close our readers if (xmlReader.ReadState != ReadState.Closed) { xmlReader.Close(); } if (vReader.ReadState != ReadState.Closed) { vReader.Close(); } } return _valid; }

5 AND

XMLTEXTREADER

private void ValidationCallBack(object sender, ValidationEventArgs args) { valid = false; //hit callback so document has a problem DateTime today = DateTime.Now; StreamWriter writer = null; try { if (_logError) { writer = new StreamWriter(_logFile,true,Encoding.ASCII);

XMLTEXTWRITER

22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66:

163

164

XML for ASP.NET Developers

Listing 5.6

continued

67: writer.WriteLine(“Validation error in: “ + 68: xmlFilePath); 69: writer.WriteLine(); 70: writer.WriteLine(args.Message + “ “ + 71: today.ToString()); 72: writer.WriteLine(); 73: if (xmlReader.LineNumber > 0) { 74: writer.WriteLine(“Line: “ + 75: xmlReader.LineNumber + 76: “ Position: “ + 77: xmlReader.LinePosition); 78: } 79: writer.WriteLine(); 80: } 81: writer.Flush(); 82: } 83: catch {} 84: finally { 85: if (writer != null) { 86: writer.Close(); 87: } 88: } 89: } 90: } //Validator 91: } //namespace

The Validator class simply implements the functionality discussed in the last few sections. The bulk of the work is done in the Validate() method, which accepts the following parameters: Parameter Name xmlFilePath schemaCol

logError logFile

Description Path to the XML document that will be validated. Represents an XmlSchemaCollection created by the client of the Validator class. This argument can be null when necessary (DTD validation, for instance). Boolean determining whether logging should be used when errors in validation occur. Path to the log file that will be written to if logError is true and an error occurs during validation.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

165

The Validate() method first sets the values of a few global variables and then instantiates the XmlTextReader using the XML document located at the path specified in the xmlFilePath parameter (line 27). Notice that the _valid variable is set to true to start, because it will be assumed that the document is valid. In line 28, the reader is passed to the constructor of the XmlValidatingReader named vReader. From here, the method takes care of setting properties on vReader and then attaches the ValidationEventHandler event handler to a callback function named Validation CallBack. After these preparatory steps have taken place, vReader then reads through and validates the XML document against the appropriate DTD or schema (line 42). If any errors occur during validation, ValidationCallBack() will be called and the global variable named _valid will be set to false. If the _logError variable is true, information about the error will be written to a log file that can be reviewed later. After processing within the ValidationCallBack() handler has finished, control will return to the Validate() method and the value of the _valid variable will be returned to the calling ASP.NET page. Calling the Validator class from within an ASP.NET page is as simple as instantiating the class, creating the XmlSchemaCollection (optional), and then calling the Validate() method while passing in the proper parameters. Listing 5.7

Calling the Validator Class from an ASP.NET Page (validateSchema.aspx)

5 AND

XMLTEXTREADER

XMLTEXTWRITER

1: void Page_Load(object sender, System.EventArgs e) { 2: string xmlFilePath = Server.MapPath(“golfersNotValid(XSD).xml”); 3: string logFile = Server.MapPath(“validationErrors.log”); 4: 5: XmlSchemaCollection schemaCol = new XmlSchemaCollection(); 6: schemaCol.Add(“http://www.golfExample.com”, 7: Server.MapPath(“golfers.xsd”)); 8: Validator validator = new Validator(); 9: bool status = validator.Validate(xmlFilePath,schemaCol,true,logFile); 10: if (status) { 11: Response.Write(“Validation of golfersNotValid(XSD).xml “ + 12: “ was SUCCESSFUL!”); 13: //Call method to process XML document here 14: } else { 15: Response.Write(“Validation of golfersNotValid(XSD).xml “ + 16: “ failed! Check the “ + 17: “log file for information on the failure.”); 18: } 19: }

166

XML for ASP.NET Developers

Passing Authentication Credentials with the XmlTextReader Class There may be times when the XML document used by the XmlTextReader is secured and therefore inaccessible without passing the appropriate user credentials. Fortunately, the XmlTextReader class allows credentials to be passed so that the document can be accessed. This is accomplished by using the CredentialCache class located in the System.Net namespace. When no special credentials are specified (when anonymous access is allowed, for instance), the CredentialCache class’s DefaultCredentials property is used behind the scenes. In many situations you won’t have to worry about setting the credentials, so the line shown in bold is not necessary: XmlTextReader xmlReader = new XmlTextReader(“golfers.xml”); xmlReader.XmlResolver.Credentials = CredentialCache.DefaultCredentials; while (xmlReader.Read()) { //....process nodes }

In cases where specific user IDs and passwords must be specified to access XML documents located at different URLs, the NetworkCredential class can be used along with the CredentialCache class, as shown next. Using these classes presents an excellent mechanism for accessing secured XML documents. XmlTextReader xmlReader = new XmlTextReader(“http://www.golfExample.com/xml/golfers.xml”); NetworkCredential creds = new NetworkCredential(“golfNut”,”1putt”, “lottaWater”); CredentialCache credsCache = new CredentialCache(); credsCache.Add(new Uri(“www.golfExample.com”), “Basic”, creds); credsCache.Add(new Uri(“xml.golfExample.com”), “Basic”, creds); xmlReader.XmlResolver.Credentials = credsCache; while (xmlReader.Read()) { //....process nodes }

Using the XmlTextWriter Class to Create XML Documents Up to this point in the chapter, you’ve seen how the XmlTextReader class can be used along with several supporting classes to parse XML in a forward-only, noncached manner. In this section you’ll see how this same concept can be used to dynamically create XML documents without incurring any overhead from creating a DOM structure. In Chapter 6 you’ll see how to do this same type of thing using DOM-specific classes.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

167

The XmlTextWriter class performs the task of writing to an XML document in a forward-only, cursor-style manner. Although all the properties and methods associated with the class won’t be listed here, they are extremely simple to use after you’ve seen an example. To introduce you to how the XmlTextWriter class works, Listing 5.8 shows how to use several of its properties and methods. Listing 5.8

Generating XML with the XmlTextWriter Class

5 AND

XMLTEXTREADER

XMLTEXTWRITER

1: 2: 3: public void Page_Load(Object Src, EventArgs E) { 4: string xmlDoc = Server.MapPath(“xmltextwriter.xml”); 5: XmlTextWriter writer = null; 6: try { 7: writer = new XmlTextWriter(xmlDoc,Encoding.UTF8); 8: writer.Formatting = Formatting.Indented; 9: writer.WriteStartDocument(true); 10: writer.WriteComment(“XML Nodes added using the XmlTextWriter”); 11: writer.WriteStartElement(“golfers”); 12: writer.WriteAttributeString(“xmlns”,”x-schema:golfers.xdr”); 13: writer.WriteStartElement(“golfer”, null); 14: writer.WriteAttributeString(“skill”,”moderate”); 15: writer.WriteAttributeString(“handicap”,”12”); 16: writer.WriteAttributeString(“clubs”,”Taylor Made”); 17: writer.WriteAttributeString(“id”,”1111”); 18: writer.WriteElementString(“firstName”,null,”Paul”); 19: writer.WriteElementString(“lastName”,null,”Allsing”); 20: writer.WriteStartElement(“favoriteCourses”, null); 21: writer.WriteStartElement(“course”,null); 22: writer.WriteAttributeString(“city”,”Phoenix”); 23: writer.WriteAttributeString(“state”,”Arizona”); 24: writer.WriteAttributeString(“name”,”Ocotillo”); 25: writer.WriteEndElement(); 26: writer.WriteStartElement(“course”,null); 27: writer.WriteAttributeString(“city”,”Tempe”); 28: writer.WriteAttributeString(“state”,”Arizona”); 29: writer.WriteAttributeString(“name”,”Ken McDonald”); 30: writer.WriteEndElement(); 31: writer.WriteStartElement(“course”,null); 32: writer.WriteAttributeString(“city”,”Phoenix”); 33: writer.WriteAttributeString(“state”,”Arizona”); 34: writer.WriteAttributeString(“name”,”Ahwatukee CC”); 35: writer.WriteEndElement(); 36: writer.WriteEndElement(); //favoriteCourses 37: writer.WriteEndElement(); //golfer

168

XML for ASP.NET Developers

Listing 5.8

continued

38: writer.WriteEndElement(); //golfers 39: writer.Flush(); 40: writer.Close(); 41: XmlDocument doc = new XmlDocument(); 42: doc.Load(xmlDoc); 43: Response.ContentType = “text/xml”; 44: doc.Save(Response.Output); 45: } 46: catch (Exception e) { 47: Response.Write(e.ToString()); 48: } 49: finally { 50: if (writer != null) { 51: writer.Close(); 52: } 53: } 54: } 55:

The XmlTextWriter constructor accepts several different arguments. This example passes in a document name (xmltextwriter.xml) to which all output can be written. It also passes in the desired encoding type for the document by using the Encoding enumeration. After the class is instantiated, several methods are called that allow for customization over what is included in the XML document. To start, the Formatting property is set to Formatting.Indented so that the resulting XML document has a hierarchical indentation (line 8). Next, the XML declaration is added by passing in a Boolean value of true to the WriteStartDocument() method (line 9). Several nodes are then added to the document through calling the appropriate methods. The specific methods used in Listing 5.8 are shown next along with their description: Method WriteXmlDecl(boolean)

Description Determines whether an XML declaration should be added with a standalone attribute. If true, the following will be added: false

will yield:

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5

Method

WriteComment(comment) WriteStartElement(elemName)

WriteEndElement()

WriteAttributeString(attName,value)

WriteElementString (elemName, nameSpace, value)

169

Description If you do not want any XML declaration, simply omit the call to the WriteXmlDecl() method. Adds an XmlComment node to the document. Creates an XmlElement start tag using the supplied argument as the tag name. This is used when an element can contain more than just attributes. Creates an ending element tag. This method must appear after the corresponding WriteStartElement() method. Creates an attribute on the appropriate element using the supplied name and value arguments. This method is used when an element contains only a text node. It accepts the element name, namespace URI, and text node value.

Converting EDI or Legacy Data to XML The capability to write out XML in a forward-only manner lends itself nicely to document conversions. For example, if a flat file containing thousands of rows needs to be converted to XML, you could parse it and manually wrap the different element tags around the data. Although this process would work, the number of string conversions needed to take care of creating the XML could get rather expensive. On top of this, the code could also become difficult to maintain because of the number of string concatenations or StringBuilder calls. The XmlTextWriter provides an excellent way to avoid some of these problems by converting the flat-file data to XML in a fast, efficient, and code-friendly manner.

AND

XMLTEXTREADER

If you haven’t seen an EDI document before, you’ll get your first look in Listing 5.9. This simplified document represents a purchase order. If you have EDI experience, you’ll recognize that this is not necessarily complete, but it will suffice for our purposes.

5 XMLTEXTWRITER

Another example of how the XmlTextWriter class could be quite valuable is in Electronic Data Interchange(EDI) to XML conversions. EDI is a standard that is used by a large number of companies to exchange data with trading partners. If your company doesn’t support EDI (you support only XML in your applications, for example), what can you do to allow your company to exchange documents with these companies? One potential solution would be to use the XmlTextWriter class to dynamically create XML based on data within an EDI document. Let’s take a closer look at how this could be accomplished.

170

XML for ASP.NET Developers

Listing 5.9 1: 2: 3: 4: 5: 6: 7:

A Purchase Order EDI Document (ediModule.edi)

BEG*1234*01/24/2001~ DTM*110*01/25/2001~ PO1*1*232324~ NTE*Line Number 1~ PO1*2*99999~ NTE*Line Number 2~ CTT*2*10~

This document contains a header section, two detail sections, and a summary section. Marked up in XML, the document could look like the one shown in Listing 5.10. Listing 5.10

A Purchase Order EDI Document Converted to XML

1234 01/24/2001 01/25/2001 1 232324 Line Number 1 2 99999 Line Number 2 2 10

Converting the EDI document shown in Listing 5.9 to the XML document shown in Listing 5.10 is surprisingly simple when the XmlTextWriter class is used. Listing 5.11 shows the code to accomplish this task.

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Listing 5.11

171

Converting EDI to XML (ediModule.cs)

5 AND

XMLTEXTREADER

XMLTEXTWRITER

1: namespace EDI.Converter { 2: using System; 3: using System.Xml; 4: using System.IO; 5: using System.Text; 6: 7: /// 8: /// EDI to XML Converter 9: /// 10: 11: public class EdiToXml { 12: string _ediPath; 13: XmlTextWriter writer; 14: public EdiToXml(string ediPath,string xmlPath) { 15: ediPath = ediPath; 16: writer = new XmlTextWriter(xmlPath,Encoding.UTF8); 17: } 18: public bool Convert() { 19: FileStream fs = null; 20: StreamReader reader = null; 21: string ediLine; 22: try { 23: writer.WriteStartDocument(); 24: writer.WriteStartElement(“root”); 25: fs = new FileStream(_ediPath, 26: FileMode.Open,FileAccess.Read); 27: reader = new StreamReader(fs); 28: while ((ediLine = reader.ReadLine()) != null) { 29: string[] tokens = ediLine.Split(new char[]{‘*’}); 30: GenerateXml(tokens); 31: } 32: writer.WriteEndElement(); //Close root element 33: return true; 34: } 35: catch { 36: return false; 37: } 38: finally { 39: if (fs != null) { 40: fs.Close(); 41: }

172

XML for ASP.NET Developers

Listing 5.11 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85:

continued if (reader != null) { reader.Close(); } if (writer != null) { writer.Close(); } } } private void GenerateXml(string[] tokens) { if (tokens[0] != null) { switch (tokens[0].ToString().ToUpper()) { case “BEG”: writer.WriteStartElement(“header”); writer.WriteStartElement(“poNumber”); writer.WriteString(Clean(tokens[1])); writer.WriteEndElement(); writer.WriteStartElement(“poDate”); writer.WriteString(Clean(tokens[2])); writer.WriteEndElement(); break; case “DTM”: writer.WriteStartElement(“shipDate”); writer.WriteString(Clean(tokens[2])); writer.WriteEndElement(); writer.WriteEndElement(); //header break; case “PO1”: writer.WriteStartElement(“detail”); writer.WriteStartElement(“lineNum”); writer.WriteString(Clean(tokens[1])); writer.WriteEndElement(); writer.WriteStartElement(“partNum”); writer.WriteString(Clean(tokens[2])); writer.WriteEndElement(); break; case “NTE”: writer.WriteStartElement(“desc”); writer.WriteString(Clean(tokens[1])); writer.WriteEndElement(); writer.WriteEndElement(); //detail break; case “CTT”: writer.WriteStartElement(“summary”);

Using the XmlTextReader and XmlTextWriter Classes in ASP.NET CHAPTER 5 Listing 5.11

173

continued

86: writer.WriteStartElement(“lineCount”); 87: writer.WriteString(Clean(tokens[1])); 88: writer.WriteEndElement(); 89: writer.WriteStartElement(“totalQuantity”); 90: writer.WriteString(Clean(tokens[2])); 91: writer.WriteEndElement(); 92: writer.WriteEndElement(); //summary 93: break; 94: } 95: } 96: } 97: private string Clean(string token) { 98: string newToken = token.Replace(“~”,””); 99: return newToken; 100: } 101: } //EdiToXml 102: } //namespace

After the EdiToXml class is instantiated and passed the path to the EDI and XML documents, the code in lines 25–31 reads through the EDI document line by line using the StreamReader class (part of the System.IO namespace). Each line is split into different tokens and is placed into a string array based on the * separator. The string array (named tokens) is then passed to the GenerateXml() method, which writes out the data found within the string array to an XML document using the XmlTextWriter class. When you use this class, the code is nicely organized, easy to follow, and very efficient. To see the EdiToXml class in action, run the file named EdiToXmlClient.aspx.

Summary You should now have a good feel for how XML can be read and written using forward-only, noncached mechanisms. The XmlTextReader and XmlTextWriter classes (along with their supporting classes) pack a lot of power that can provide your ASP.NET/XML applications with efficiency and speed. There’s still a lot more to learn, however, so don’t relax just yet! In the next chapter, you’ll learn more about the DOM and see how you can use it to navigate XML documents and to insert, update, delete, and move XML nodes.

5 AND

XMLTEXTREADER

XMLTEXTWRITER

CHAPTER

Programming the Document Object Model (DOM) with ASP.NET

6

IN THIS CHAPTER: • Welcome to the DOM

176

• In-Memory Versus Forward-Only Parsing • Working with MSXML3 via Interop

178

179

• DOM Classes in the System.Xml Namespace and Assembly 182 • The XmlNode Class

183

• The XmlDocument Class

189

• The XmlNodeList Class

200

• The XmlNamedNodeMap Class

201

• Selecting Nodes Within the DOM Using Xpath 204 • Putting It All Together

205

• The XmlNodeReader Class • XMLHTTPRequest Object

209 211

• Sample Application—Client/Server-Side Hierarchical XML Menus 219 • Chapter 2 Sample Application Revisited

225

176

XML Basics

Welcome to the DOM In the previous chapter, you learned how to work with XML in a forward-only manner using the XmlTextReader and XmlTextWriter classes. You also saw how these classes can be used to provide fast and efficient XML parsing/writing. It’s now time to examine another way to work with XML that provides the capability to update, insert, delete, and move nodes within an XML document. Welcome to the DOM! You may not realize it, but you’re probably already familiar with the concept of the DOM. If you’ve done any type of Dynamic HTML (DHTML) development in Internet Explorer 4 or later, you have used a DOM that was created by the browser. You may have used it to change a heading color or to dynamically show or hide specific content. When a browser loads a page in Internet Explorer 4 or later, the various parts that make up the page are loaded into a structure and placed in memory. Accessing this structure using DHTML is as easy as knowing what part of the document you want to gain access to. By using the window.document.all collection, you have access to the entire HTML page’s objects and content through client-side code written in JavaScript (officially called ECMAScript: http://www.ecma.ch/ecma1/stand/ecma262.htm) or VBScript. For example, changing the text color of a particular section located within a tag having an id attribute equal to “mainContent” could be accomplished with the following code in Internet Explorer 4 or later: function changeColor(color,div) { window.document.all(div).style.color=color; } Testing this out

If you have done much DHTML programming, you’re probably painfully aware that the DOM used in Internet Explorer 4 or later is very different from the one used in Netscape Navigator 4 (the Netscape 6 DOM is more like Internet Explorer’s DOM). Unfortunately, the two browsers

Programming the Document Object Model (DOM) with ASP.NET CHAPTER 6

The DOM Level 2 is made of a set of core interfaces to create and manipulate the structure and contents of a document and a set of optional modules. These modules contain specialized interfaces dedicated to XML, HTML, an abstract view, generic stylesheets, Cascading Style Sheets, Events, traversing the document structure, and a Range object. Many of the concepts mentioned in the W3C statement are new additions to the DOM specification. Some of these include a style sheet object model, namespace support, an event model, and support for text ranges. More information about the DOM Level 2 specification can be found at http://www.w3.org/TR/DOM-Level-2/. “What does all this have to with XML?” you ask. Actually—everything. Although the DOM created by the browser isn’t the same because of form collections, image collections, and so on, many of the same concepts apply to an XML document’s DOM. When an XML document is first loaded and parsed, an internal representation (similar to a tree structure) of the document is placed in memory. This structure is based on the concept of nodes with the root node being followed by other children nodes. Like the DOM the browser creates, the DOM created by a DOM-compatible XML parser is programmatically accessible using classes that help you access specific nodes within the DOM structure. After these classes and their associated properties and methods are understood, virtually any node within an XML document can be accessed, updated, inserted, or deleted. To gain a better understanding of how the DOM works, Figure 6.1 shows a visual representation of the following XML document’s DOM: Dan Wahlin Pinetop Lakes CC Ocotillo

As shown in Figure 6.1, the DOM is composed of the various items found within the XML document. Each of these items is a node in the DOM structure. This means that the text under the two course nodes is actually represented in the DOM by a text node. The example shown

6 PROGRAMMING THE DOCUMENT OBJECT MODEL

are so different that a page that works perfectly fine in one is very unlikely to work in the other. The W3C recognized the problems caused by inconsistencies between DOMs and issued a DOM Level 1 recommendation back in 1998. More information about this can be found at http://www.w3.org/TR/REC-DOM-Level-1/introduction.html. Since releasing the DOM Level 1 recommendation, the W3C also released DOM Level 2 and is currently starting work on DOM level 3. The W3C states

177

178

XML Basics

is very basic and doesn’t include many of the nodes that could exist in a given XML DOM (attribute nodes, comment nodes, and so on), but it does give you a visual overview of how the DOM is structured.

golfer

name

Dan Wahlin

courses

course

course

Pinetop Lakes CC

Ocotillo

FIGURE 6.1 Representation of the DOM.

The next sections will explain how you can gain access to an XML document’s DOM, both on the server side with ASP.NET and on the client side with JavaScript. Before covering those topics, however, let’s first revisit the differences between in-memory and forward-only parsing.

In-Memory Versus Forward–Only Parsing The DOM model is very efficient at allowing access to specific XML document nodes. It allows complete flexibility in updating, inserting, deleting, or moving nodes. However, as with most things, this power does come with a price. One of the problems associated with the DOM concerns memory consumption. Because an entire XML document’s structure is loaded into memory after being parsed, a large document could potentially consume a lot of memory. A smarter implementation of an XML DOM could behave more like a database system and page nodes in and out from disk to conserve memory. In fact, some object database vendors have put DOM wrappers on their systems, thereby achieving this sort of hybrid XML database.

Programming the Document Object Model (DOM) with ASP.NET CHAPTER 6

When should you use the DOM instead of the forward-only parsing model exhibited by the XmlTextReader class? Unfortunately, the answer to this question isn’t a simple one because each application has unique requirements. In general, XML documents that simply need to be read and not updated should leverage the speed and efficiency provided by the XmlTextReader class. Doing this helps ensure that the application remains scalable. On the other hand, XML documents that need modification either in the form of updates, inserts, or deletes will benefit from the flexibility of having the document’s structure in memory and should therefore use classes associated with the DOM. Although this is a less scalable solution, it is certainly needed in many situations. You’ll be introduced to the classes that can be used to manipulate the DOM in a moment. Let’s first take a quick look at how MSXML3 can be used in ASP.NET applications.

Working with MSXML3 via Interop The .NET platform provides two routes to take for accessing the DOM. The optimal route is discussed in the next section on the System.Xml namespace and assembly. The alternative route is to use the .NET Interop service to access a “classic” COM XML parser such as MSXML3. Why would you ever want to take the alternative route when you can simply use the parser designed specifically for .NET applications? The answer depends on the amount of work you already have invested in your current applications. It may be that you’re ready to move to the enhanced scalability built in to .NET applications and that you’re ready to leverage the power of C# or VB.NET used in conjunction with ASP.NET. However, you may have hundreds or thousands of lines of existing code that manipulates the DOM using the MSXML3 parser. Is it worth it to completely rewrite all this code to use the new parser? That is a question that you must answer yourself. If converting all your code to the .NET framework is not an option because of time constraints, Interop may be the best temporary route to take.

6 PROGRAMMING THE DOCUMENT OBJECT MODEL

In Chapter 5, “Using the XmlTextReader and XmlTextWriter Classes in ASP.NET,” you saw how the DOM memory limitations can be overcome by using the XmlTextReader class (and helper classes). Rather than loading the entire document into memory as with the DOM, the reader processes one node at a time by creating a stream that XML tokens can be read from. This forward-only stream means that when the document’s root element is reached, very little data is buffered in memory at any given time. When a child node is reached, its ancestors have been parsed, but they are not in memory and going back to them is not an option. This type of functionality allows one item at a time to be checked and processed rather than loading everything into memory. It provides a very low memory alternative that is capable of working with very large XML documents.

179

180

XML Basics

If you take the Interop route, you can port your XML application to the .NET platform without rewriting all your existing code. To do this, you must follow a few simple steps: 1. Convert MSXML3.dll to managed code using the Tlbimp.exe utility file. 2. Import this newly converted file’s namespace into your ASP.NET page. 3. Begin the conversion process from ASP to ASP.NET. To get started, the first step in the preceding list must be completed. The Tlbimp.exe utility converts the type definitions found in a COM type library to a .NET assembly that contains metadata about the COM type definitions. In sum, the utility takes the type library information found within MSXML3 and converts it into a form that can be used within an ASP.NET page. To make the conversion, go to a command prompt and type the following: tlbimp msxml3.dll /out:c:\inetpub\wwwroot\bin\msxml3Managed.dll

You may need to adjust the output file path as necessary. The output path should point to the appropriate bin directory where you’ll be running the application that uses MSXML3 in your ASP.NET page. If the Tlbimp.exe utility ran successfully, a new file will show up at the location specified by the out parameter. To view the metadata contained within this file, locate the IL Disassembler tool (Start, Programs, Microsoft .NET Framework SDK, Tools) or go to the command prompt and type the following from within the appropriate bin directory: ildasm msxml3Managed.dll

When you open the newly created metadata file, you should see a screen similar to the one shown in Figure 6.2.

FIGURE 6.2 msxml3Managed.dll metadata.

Programming the Document Object Model (DOM) with ASP.NET CHAPTER 6

LISTING 6.1

Using MSXML3 in the .NET Platform

1: 2: 3: 4: 5: void Page_Load(Object Src, EventArgs E) { 6: DOMDocument30 doc = new DOMDocument30(); 7: doc.load(Server.MapPath(“golfers.xml”)); 8: IXMLDOMNode node = doc.documentElement; 9: Response.Write(“Document Element Name: ” + node.nodeName + 10: “”); 11: for (int i=0;i 0) { 15: for (int j=0; 16: j INFORMATION TECHNOLOGY SPECIALIST REQUEST REVIEW FORM

Programming the Document Object Model (DOM) with ASP.NET CHAPTER 6

LISTING 6.8

Continued

Figure 6.3 shows a screenshot of the page generated by the code shown in Listing 6.8. After a user selects a specific IT request from the drop-down box, the getRequest() method locates the request id the user selected and assigns it to the id variable. Next, a QueryString is dynamically created that includes the request id the user desires to see. Notice that the URL points to an ASP.NET page (lines 81–83). The XMLHTTPRequest object is instantiated and a call is placed to its open() method (line 86). After this method has been successfully called, the information is sent to the remote server using the send() method shown in line 87. After the remote server has responded, the resulting XML document text is placed within an XML data island (named requestData) that is embedded in the Web page. An XML data island is an Internet Explorer 5 or later feature that allows XML documents to be embedded in a Web page. Using the updateBindings() method (lines 92–106), the data island is used to populate div tags located on the page programmatically. An alternative way of accomplishing the same task would be to bind the fields to the data island using the dataSrc and dataFld element attributes.

6 PROGRAMMING THE DOCUMENT OBJECT MODEL

122: 123: 124: 125: 126: 127: Select A Request: 128: 129: 130: 131: 132: Select One: 133: 134: 135: 136: 138: 139: 140: 141:

142: 144:

145: 146: 147:

217

218

XML Basics

FIGURE 6.3 The IT request form.

On the server side, an ASP.NET page named Listing6.8.aspx checks to see whether a QueryString variable named status contains a value of getXML. If it does, it takes the id value that was passed on the QueryString, instantiates an XmlDocument, and calls the SelectSingleNode() method passing in an XPath statement that includes the request id. The resulting XML fragment is then returned to the client-side XMLHTTPRequest object. The code shown in Listing 6.9 shows this process and further illustrates how to use the XmlNode’s SelectSingleNode() method to select a specific node within the requests.xml file. LISTING 6.9

Selecting Nodes with the SelectSingleNode() Method. (This page is called from listing6.8.aspx.) 1: 2: 3: void Page_Load(Object Src, EventArgs E) { 4: Response.ContentType = “text/xml”; 5: Response.Expires = -1; 6: 7: string ID = Request.QueryString[“id”]; 8: string status = Request.QueryString[“status”]; 9: 10: switch (status.ToUpper()) { 11: case “GETXML”: 12: GetRequestXML(ID);

Programming the Document Object Model (DOM) with ASP.NET CHAPTER 6

LISTING 6.9

Continued

The end result of this process is that the user can select different request IDs and view their associated data without having to leave the Web page. This solution is server friendly because only a few calls are made to the server to obtain data; that allows the end user to be more efficient and happy, which hopefully results in fewer calls to the help desk.

Sample Application—Client/Server-Side Hierarchical XML Menus Now that you’ve seen what you can do with the main XML classes, let’s leverage that knowledge to construct a menu similar to the Start menu in Windows. XML was chosen for this application simply because of its capability to support hierarchical structures and because of the speed with which it can be accessed from a Web server. The application will use an XML document named menuItems.xml and an ASP.NET file named menus.aspx on the server side. On the client side, a cascading style-sheet document and a JavaScript document will be used

6 PROGRAMMING THE DOCUMENT OBJECT MODEL

13: break; 14: default: 15: break; 16: } 17: } 18: 19: private void GetRequestXML(string requestID) { 20: XmlDocument doc = new XmlDocument(); 21: try { 22: doc.Load(Server.MapPath(“requests.xml”)); 23: } 24: catch (Exception c) { 25: Response.Write(“There are currently no” + 26: “ requests to view.”); 27: } 28: //Perform XPath query using SelectSingleNode() method 29: string xpath = “//request[@id=’” + requestID + “‘]”; 30: XmlNode requestNode = doc.SelectSingleNode(xpath); 31: if (requestNode != null) { 32: Response.Write(requestNode.OuterXml); 33: } else { 34: Response.Write(“NO ID”); 35: } 36: 37: } 38:

219

220

XML Basics

for the Dynamic HTML (DHTML). All these files working together produce the menu application shown in Figure 6.4.

FIGURE 6.4 Screenshot of the XML-based menu application.

The foundation of the application is the XML document because it contains the data used for the menus. A portion of the document is shown next: About Us /calendar/default.aspx Calendars /govt/default.aspx Government /pdf/orgchart.pdf Organization Charts

As you can see, the XML document relies on one of XML’s core strengths: the capability to describe hierarchical relationships. Looking at the preceding document, you can see that

Programming the Document Object Model (DOM) with ASP.NET CHAPTER 6

On the server side, a custom class named XmlMenu has a recursive function used to handle navigating through the XML document. It uses a few of the classes you’ve seen before, such as the XmlDocument and XmlNode classes, and a few you may not know about yet, called ArrayList and StreamWriter. These different classes are used to access node values for display or to store node information. As the menuItem nodes in the XML document are navigated, the different menu structures are placed into ArrayLists. After all the arrays are created, a call to the Response object sends the formatted menus up to the client where the DHTML JavaScript code takes over. Now that you have a feel for the application, let’s take a look at the code that starts things off on the server side (menus.aspx):

As shown, the code starts by instantiating the XmlMenu class, which is part of the XmlHierMenu namespace in the XmlMenu class. After the class is instantiated, a call is made to its CreateMenu() method. This method accepts the name of the menu and the path to the menu’s XML document. In this example, three menus named menu1, menu2, and menu3 will be created for use in an ASP.NET page. The CreateMenu() method is shown in Listing 6.10:

6 PROGRAMMING THE DOCUMENT OBJECT MODEL

several tags are nested within each other, creating a parent/child relationship. This relationship is used to create menus that can contain submenus as seen in the Windows Start menu.

221

222

XML Basics

LISTING 6.10

CreateMenu() Method (xmlMenus.cs)

1: public string CreateMenu(string startMenu,string file) { 2: StringBuilder strOutput = new StringBuilder; 3: int i = 0; 4: ArrayList startArray = new ArrayList(); 5: string strVariable = “”; 6: string strTemp = “”; 7: 8: XmlDocument XMLDoc = new XmlDocument(); 9: try { 10: XMLDoc.Load(file); 11: } 12: catch (Exception e) { 13: strOutput.Append(e.GetBaseException().ToString()); 14: return strOutput.ToString(); 15: } 16: 17: XmlNodeList nodeList = XMLDoc.DocumentElement.ChildNodes; 18: 19: foreach (XmlNode node in nodeList) { 20: XmlNode currentNode = node; 21: if (currentNode.HasChildNodes == true && 22: currentNode.ChildNodes.Count>1) { 23: strCurrentMenu = startMenu + “_” + (i+1); 24: string thisMenu = startMenu; 25: if (currentNode.ChildNodes.Count>2) { 26: strVariable = “” + _strImage + 32: currentNode.ChildNodes[1].InnerText + 33: “\n”; 34: startArray.Add(strVariable); 35: WalkTree(currentNode); 36: } else { 37: strVariable = “” + currentNode.ChildNodes[1].InnerText +

Programming the Document Object Model (DOM) with ASP.NET CHAPTER 6

LISTING 6.10

“\n”; startArray.Add(strVariable); } } i++; } startArray.TrimToSize(); arrayNamesArray.Add(startMenu); for (i=0;i golfers have lower handicaps

Transforming XML with XSLT and ASP.NET CHAPTER 7

263

The xsl:variable element can have a name and a select attribute. The name attribute is required and serves the obvious purpose of assigning a name that can be used to reference the variable. The select attribute is optional but when listed, must contain a valid XPath expression.

At times, the value of an attribute may need to be dynamically generated and used in several places. In many cases, using a variable can make this process easier: #ff0000 #ffff00 #ffffff

Although the value of the color attribute found on the font tag could be added by using the xsl:attribute element multiple times, by defining the value once in the variable, the code is kept cleaner and the processing is more efficient.

TIP The previous example shows a shortcut that can be used to embed data directly into attributes that will be written out to the result tree. By wrapping a variable (or other item) with the { and } brackets, it will dynamically be added to the result tree. This is continues

7 TRANSFORMING XML WITH XSLT AND ASP.NET

So what have we gained by using a variable in this template? The code has actually been made much more efficient as compared to writing the same code without using the variable. Instead of having to calculate the count of all the golfers in the XML document with handicaps less than 11 each time a golfer node template is matched, the variable obtains this value and stores it when the XSLT style sheet is first loaded. The variable can then be referenced in several places by adding the $ character to the beginning of the variable name ($count in this case). Doing this cuts out unnecessary processing during the transformation process.

264

XML for ASP.NET Developers

in contrast to adding the attribute name and value to a tag by using the xsl:attribute element. As another example, if you had an attribute named width in an XML document, you could write it out to a table tag by doing the following: . This is similar to doing something such as

in ASP.NET.

Variables can also be useful for storing values returned by calling a template. This process will be shown a little later after you’re introduced to the xsl:param element. Parameters in XSLT Parameters are useful in a variety of programming languages, with XSLT being no exception. Parameters can be used in XSLT documents in two basic ways. First, parameter values can be passed in from an ASP.NET application. This allows data not found within the XML document or XSLT style sheet to be part of the transformation process. Second, parameter values can be passed between XSLT templates in much the same way that parameters can be passed between functions in C# or VB.NET. You’ll see how parameters can be used in both ways later in the chapter. Declaring a parameter is similar to declaring a variable. Simply name the parameter and add an optional select attribute:

As with variables, parameters can be children of the xsl:stylesheet or xsl:transform elements and can also be children of the xsl:template element. So when would you want to use a parameter? Let’s assume that the golfers XSLT document shown in Listing 7.4 needs to show a specific golfer based on user input in a Web form. To accomplish this task, the ASP.NET application can pass in the value entered by the user to a parameter within the XSLT document. This value can then be used to display the proper golfer’s information. A simplified document that uses a parameter named golferNum is shown next:

Transforming XML with XSLT and ASP.NET CHAPTER 7

265

Having this parameter in the XSLT style sheet will cause a specific golfer’s information to be transformed. Any other golfers in the XML document will simply be ignored. How is this accomplished? A small change was made to the xsl:apply-templates element in the golfers template. Instead of processing all golfer nodes in the XML document, the XPath expression in the select attribute specifies the specific golfer node to process:

Although this example hard-codes a value for the golferName parameter, an ASP.NET page would normally pass the value in using specific classes in the System.Xml assembly. You’ll be introduced to these classes later in the chapter. If the value passed into the golferName parameter from the ASP.NET page does not match up with an existing golfer node in the XML document, no error will be raised. Parameters can also be used in conjunction with the xsl:call-template element. Fortunately, from working with other programming languages, you already have a good understanding of how this works. Imagine calling a method named GetOrders() that accepts a single parameter as an argument. The method call would look something like the following: GetOrders(“ALFKI”);

Now imagine that GetOrders is the name of an XSLT template used to transform an XML document containing customers and orders. Calling the template and passing the parameter can be accomplished by doing the following:

This example shows the use of the xsl:call-template and xsl:with-param elements to initiate the template call. The xsl:call-template element has a single attribute that provides the name of the template to call. The xsl:with-param element has two attributes. One is used to name the parameter that data will be passed to and the other provides the value that is to be passed. The select attribute can contain any valid XPath expression. The xsl:with-param element can only be a child of the xsl:call-template or xsl:apply-templates element.

7 TRANSFORMING XML WITH XSLT AND ASP.NET

266

XML for ASP.NET Developers

TIP The xsl:param element named CustomerID (shown earlier) has a parameter value of ALFKI with single quotes around it because it is a string value rather than an XPath expression. Had the single quotes been omitted, the XSLT processor would try to find a node named ALFKI (which doesn’t exist, of course). Although this seems fairly obvious, it’s an easy mistake to make.

The xsl:param element in the template being called is updated by using the xsl:with-param element shown previously. It has two potential attributes, including name and select, as described earlier. In the previous example, the parameter named CustomerID is assigned a default value of ALFKI. This value will be overridden when the GetOrders template is called and a parameter value is passed to it using the xsl:with-param element. Because variables cannot be updated in XSLT, parameters play a large role in allowing values to be passed between templates. A global parameter (declared as a child of the xsl:stylesheet or xsl:transform elements) can receive input from an ASP.NET page, but it cannot be updated more than once after processing of the XSLT document begins. However, the capability to place parameters within the scope of a specific template body offers the capability to call templates recursively. This is possible because a single template can call itself and pass a parameter value (or more than one value, in the case of multiple parameters within the template) that can then be processed as appropriate. Although the inability to update variables and parameters may seem somewhat restrictive, the authors of the XSLT specification knew that it was necessary because XML documents can contain many different structures. You can’t depend on one template being processed before another, especially in the case where one XSLT document is used to transform a variety of XML documents—all with different structures. Accessing “Return” Values of XSLT Templates You may have noticed that although a template can act somewhat like a method, it has no way to return a response…or does it? By wrapping the xsl:variable element around a template call made using the xsl:call-template element, the output normally written to the result tree can instead be captured by the variable. This process is shown next:

Transforming XML with XSLT and ASP.NET CHAPTER 7

267

Customer ID:

The variable named Orders will be filled with a node-set generated by a call to the GetNames template. Doing this offers a powerful means for building more dynamic and efficient XSLT documents. Now that you’re familiar with several of the main elements used in creating XSLT style sheets, it’s time to examine XSLT functions.

XSLT Functions In Chapter 3, “XPath, XPointer, and XLink,” you were introduced to several functions built in to the XPath language. Because XSLT relies on XPath for creating expressions that locate nodes in an XML document, these functions are available for use in your XSLT documents. In addition to these functions, the XSLT language adds a few more. Table 7.3 shows these functions and provides a description and example of using them in XSLT documents. TABLE 7.3

XSLT Functions

Function

Description

current()

Returns a node set that contains the current node as its only member. This function exists to help identify the current node when it is different from the context node. In previous examples you have seen that the context node can be represented by the . character. For example, to write out the value of the context node being processed by a template, you can do the following:

This code will provide the same result:

7 TRANSFORMING XML WITH XSLT AND ASP.NET

268

XML for ASP.NET Developers

TABLE 7.3

continued

Function current()

Description (continued)

At this point in the template, the current node is the same as the context node. When used within the square brackets of a predicate ([ and ]), however, the current node is often different from the context node. An example of this is shown next: Other Comparable Golfers:

document(object,node-set?)

The predicate statement ([./@skill = current()/ @skill]) will compare the value of the context node’s skill attribute (in this case, the golfer node being looped through) to the golfer node being handled by the template (the current node). This is an example of how the context node changes during a loop. However, the current node is associated with the node being handled by the template and stays the same during the looping process. Although XSLT makes it easy to transform a single XML document into other structures, what happens if the result tree needs to be created from more than just one XML document? Using the document() function, other XML documents can be pulled into an XSLT document for processing. This can be useful in many situations, including when one XML document contains a presentation structure and another contains the data to be plugged into that structure. Using the document() function, these types of activities can be accomplished relatively easily. An example of using the document() function is shown next:

Transforming XML with XSLT and ASP.NET CHAPTER 7

TABLE 7.3 Function

269

continued

Description This will load data.xml into the variable named xmlDoc. Referencing elements within the external document can be accomplished in the following manner:

The following XSLT document creates a result tree containing the handicap nodes from the referenced documents:

7 TRANSFORMING XML WITH XSLT AND ASP.NET

Although the preceding document() function example targets an external document, this function can also be used to target a node-set within the main XML document. This can be useful when you want to work with a lookup table structure embedded in the XML document. Aside from providing a string URI value, a node-set can be passed to access the remote document, as shown next: For the XML document:

270

XML for ASP.NET Developers

TABLE 7.3

continued

Function

Description

element-available(string)

This function is useful if you are writing an XSLT document that may be processed using different XSLT processors. Before using elements that you know may not be supported, a check can be made to see if the processor does indeed support the element in question. This is helpful when testing for XSLT elements found in a later version of XSLT or in checking for vendor specific elements. The function will return a Boolean value: HI!

format-number(number, string,string?)

This function converts numbers to a string using a format pattern supplied in the second parameter. Here are some examples of using this function: The following function call returns 5,351: format-number(5351,”#,###”)

The following function call returns 5351.00: format-number(5351, “#.00”)

The following function call returns 53.5100: format-number(53.51, “#.0000”)

The following function call returns 0053.5100: format-number(53.51, “0000.0000”)

The following function call returns 0053.51: format-number(53.51, “0000.####”)

The following function call returns 53.6: format-number(53.56, “0.0”) function-available(string)

generate-id(node-set?)

Similar to element-available, although this function checks whether specific functions are supported by the XSLT processor. This function generates a string that is guaranteed to uniquely identify a node. The same string will always be returned for the same node. The string that is generated will vary from processor to processor and will start with an alphabetic character.

Transforming XML with XSLT and ASP.NET CHAPTER 7

TABLE 7.3

271

continued

Function

Description

key(string,object)

This key can then be accessed by using the key() function: ... system-property(string)

This function returns the value of the system property identified by the name passed as the argument. Three different system properties must be supported by a compliant XSLT processor, including xsl:version, xsl:vendor, and xsl:vendor-url. An example of using this function follows:

unparsed-entity-uri()

This function returns declarations of unparsed entities in the DTD of the source XML document. Given the entity declaration:

The following code:

Would return a value of http://www.lottaclubs.com/clubs.txt.

7 TRANSFORMING XML WITH XSLT AND ASP.NET

This function is used in conjunction with the xsl:key element to return a node-set that has a specific name and value defined by the xsl:key statement. For example, the following code shows how the xsl:key element can define a key:

272

XML for ASP.NET Developers

.NET Classes Involved in Transforming XML Now that you’ve seen the different XSLT elements and functions that are at your disposal, it’s time to learn about what classes in the .NET framework can be used in your ASP.NET applications when XSL transformations are necessary. After all, XSLT is simply a text-based language that is of little utility without an XSLT processor. Several classes built in to the System.Xml assembly can be used when transforming XML into other structures via XSLT. Back in Listing 7.3, a preview of a few of these classes interacting with each other was given that demonstrated how to transform an XML document into HTML. In this section you’ll learn more about these classes and a few others so that you are fully armed with everything you need to know to use XSLT in your ASP.NET applications. Figure 7.3 presents an overview of the main classes used in XSL transformations.

XML Stores DOM XmlDocument

DOM DataSet XmlDataDocument

Fast XSLT XPathDocument

Implement XPathNavigator and IXPathNavigable

XSL/T

XPath

XslTransform XmlReader System.IO.Stream

XmlWriter System.IO.Textwriter

FIGURE 7.3 .NET Classes involved in XSL transformations.

Table 7.4 provides a description of each of these classes. TABLE 7.4

.NET Classes Used in XSL Transformations

Class

Description

XmlDocument

The XmlDocument class implements the IXPathNavigable interface and extends the XmlNode class, which provides the capability to create nodes within a DOM structure. This class was discussed in Chapter 6. Because the XmlDocument class provides node-creation capabilities, it will not provide the fastest throughput in XSL transformations. However, in cases where a DOM structure must be edited first before being transformed, this class can be used.

Transforming XML with XSLT and ASP.NET CHAPTER 7

TABLE 7.4

273

continued

Description

XmlDataDocument

The XmlDataDocument class extends the XmlDocument class. The XmlDataDocument class can be used when working with DataSets in ADO.NET. Chapter 8, “Leveraging ADO.NET’s XML Features Using ASP.NET,” covers this class in more depth. The XPathDocument class implements the IXPathNavigable interface like the XmlDocument class does. However, the XPathDocument class does not extend the XmlNode class (as the XmlDocument class does) and therefore provides the fastest option for transforming XML via XSLT. You’ll see this class used in the examples that follow. Because the XPathDocument class implements the IXPathNavigable interface, it is able to leverage features built in to the abstract XPathNavigator class (which, in turn, uses the XPathNodeIterator abstract class for iteration over node-sets) to provide cursor-style access to XML data, resulting in fast and efficient XSL transformations. The XslTransform class is used to transform XML data into other structures. Using the XslTransform class involves instantiating it, loading the proper style sheet with the Load() method, and then passing specific parameters to its Transform() method. This process will be detailed in the next few sections. The XsltArgumentList class is used to provide parameter values to xsl:param elements defined in an XSLT style sheet. It can be passed as an argument to the XslTransform class’s Transform() method.

XPathDocument

XslTransform

XsltArgumentList

The XPathDocument Class Before looking at the XslTransform class, you need to familiarize yourself with the XPathDocument class. To use this class you must reference the System.Xml.XPath namespace in your ASP.NET applications. As mentioned in Table 7.4, this class provides the most efficient way to transform an XML document using XSLT because it provides a read-only representation of a DOM structure. The XPathDocument class is very simple to use because it has only one XML-related method named CreateNavigator() that can be used to create an instance of the XPathNavigator class. However, it does have several constructors that are worth mentioning. Table 7.5 shows the different constructors.

7 TRANSFORMING XML WITH XSLT AND ASP.NET

Class

274

XML for ASP.NET Developers

TABLE 7.5

XPathDocument Constructors

Constructor

Description

Public XPathDocument(XmlReader, XmlSpace) Public XPathDocument(XmlReader) Public XPathDocument(TextReader) Public XPathDocument(Stream) Public XPathDocument(string,XmlSpace)

Public XPathDocument(string)

Accepts an XmlReader as well as an XmlSpace enumeration. Accepts an XmlReader. Accepts a TextReader. Accepts a Stream. Accepts the string value of the path to an XML document and an XmlSpace enumeration. Accepts the string value of the path to an XML document.

Listing 7.3 used the last constructor shown in Table 7.5 that accepts the path to the XML document to transform. You could also load the XPathDocument with XML data contained in a Stream (a FileStream for instance), an XmlReader, or a TextReader. Having these different constructors offers you complete control over how transformations will be carried out in your ASP.NET applications. Which one you use will depend on how you choose to access your application’s XML documents. Listing 7.8 instantiates an XPathDocument class by passing in an XmlTextReader object. LISTING 7.8

Instantiating an XPathDocument Class

public void Page_Load(Object sender, EventArgs E) { string xmlPath = Server.MapPath(“listing7.1.xml”); string xslPath = Server.MapPath(“listing7.2.xsl”); FileStream fs = new FileStream(xmlPath,FileMode.Open, FileAccess.Read); StreamReader reader = new StreamReader(fs,Encoding.UTF8); XmlTextReader xmlReader = new XmlTextReader(reader); //Instantiate the XPathDocument Class XPathDocument doc = new XPathDocument(xmlReader); Response.Write(“XPathDocument successfully created!”);

Transforming XML with XSLT and ASP.NET CHAPTER 7

LISTING 7.8

275

continued

//Close Readers reader.Close(); xmlReader.Close(); }

The XslTransform Class The XslTransform class is found in the System.Xml.Xsl namespace. Using it is as easy as instantiating it, loading the XSLT document, and then calling its Transform() method. Tables 7.6 and 7.7 show the different properties and methods found in the XslTransform class. TABLE 7.6

XslTransform Class Properties

Property

Description

XmlResolver

The XmlResolver property can be used to specify a resolver class used to resolve external resources. For example, it can be used to resolve resources identified in xsl:include elements. If this property is not set, the XslTransform class will use the relative path of the supplied XSLT style sheet to resolve any included style sheets. Chapter 5 showed an example of using the XmlUrlResolver class to access authenticated documents.

TABLE 7.7

XslTransform Class Methods

Method

Description

Load()

Loads an XSLT document. This method can accept an XmlReader, a document URL, or a variety of other objects. The Transform() method is overloaded and can therefore accept a variety of parameters. The most common form of the method that you’ll likely use in your ASP.NET applications is shown next (check the .NET SDK for the other overloaded versions of the method):

Transform()

xsl.Transform(XpathDocument,XsltArgumentList,Stream)

7 TRANSFORMING XML WITH XSLT AND ASP.NET

Running the code shown in Listing 7.5 will write out “XPathDocument successfully created!” to the browser. You’ll certainly agree that because it has simply readied the XML document for transformation, this code doesn’t buy you much. To actually transform the XML document using XSLT, you’ll need to use another class named XslTranform.

276

XML for ASP.NET Developers

Listing 7.9 builds on Listing 7.8 by adding in the XslTransform class. LISTING 7.9 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28:

Using the XslTransform Class

public void Page_Load(Object sender, EventArgs E) { string xmlPath = Server.MapPath(“listing7.1.xml”); string xslPath = Server.MapPath(“listing7.2.xsl”); FileStream fs = new FileStream(xmlPath,FileMode.Open, FileAccess.Read); StreamReader reader = new StreamReader(fs,Encoding.UTF8); XmlTextReader xmlReader = new XmlTextReader(reader); //Instantiate the XPathDocument Class XPathDocument doc = new XPathDocument(xmlReader); //Instantiate the XslTransform Class XslTransform xslDoc = new XslTransform(); xslDoc.Load(xslPath); xslDoc.Transform(doc,null,Response.Output); //Close Readers reader.Close(); xmlReader.Close(); }

In the next section, you’ll see how you can pass in parameter values to XSLT style sheets using the XsltArgumentList class.

The XsltArgumentList Class Earlier in the chapter, you saw how parameters could be used in XSLT style sheets through the xsl:param element. As a quick refresher, this XSLT element must have a name attribute and optional select attribute:

XSLT parameters allow your ASP.NET applications to pass in values needed by the style sheet to properly process the source XML document. In this section you’ll see how to create an

Transforming XML with XSLT and ASP.NET CHAPTER 7

277

XsltArgumentList class and add parameter name/value pairs to it. It can also be used with extension objects. Table 7.8 shows the different methods available on the XsltArgumentList class (it has no properties).

TABLE 7.8

XsltArgumentList Methods

Description

AddExtensionObject(namespaceURI, object)

Allows an extension object to be added to the collection of extension objects. The namespace URI can be used to remove or retrieve an object from the collection using either GetExtensionObject() or RemoveExtension Object(). Similar to the addObject() method found on the IXslProcessor interface in MSXML3. Allows a parameter name/value pair to be added to the collection of parameters. If you do not want to assign a namespaceURI, the URI can be empty strings. It is similar to the addParameter() method found on the IXslProcessor interface in MSXML3. Allows an extension object to be retrieved from the collection of extension objects based on the namespaceURI assigned to the object in the AddExtensionObject() method. Allows a parameter name/value pair to be retrieved from the collection of parameters based on a name and namespaceURI combination. If a parameter name has no assigned namespaceURI, the URI can be empty strings. Allows an extension object to be removed from the collection of extension objects based on the namespaceURI assigned to the object in the AddExtensionObject() method. Allows a parameter name/value pair to be removed from the collection of parameters based on a name and namespaceURI combination. If a parameter name has no assigned namespaceURI, the URI can be empty strings.

AddParam(name,namespaceURI,value)

GetExtensionObject(namespaceURI)

GetParam(name,namespaceURI)

RemoveExtensionObject (namespaceURI)

RemoveParam(name,namespaceURI)

7 TRANSFORMING XML WITH XSLT AND ASP.NET

Method

278

XML for ASP.NET Developers

The method that you’ll use most frequently among those listed in Table 7.8 is the AddParam() method. This method accepts the name of the parameter, a namespace URI (optional), and the value of the parameter. The following example shows how to add a parameter named golferName to the XsltArgumentList collection: XSLT Code:

ASP.NET Code: XsltArgumentList args = new XsltArgumentList(); args.AddParam(“golferName”,””,”Dan”);

This code allows the XSLT parameter named golferName to be assigned a value of Dan. Although the value of Dan was hard-coded into the AddParam() method, it could just as easily be dynamically pulled from a text box or drop-down box, as you’ll see in the next example. Because the XsltArgumentList class relies on the HashTable class behind the scenes, multiple parameter name/value pairs can be added and stored. After an XsltArgumentList class has been instantiated and filled with the proper name/value pairs, how do the parameters in the XSLT style sheet get updated with the proper values? The answer is to pass the XsltArgumentList into the XslTransform class’s Transform() method, as shown next: //Create the XPathDocument object XPathDocument doc = new XPathDocument(Server.MapPath(“Listing7.1.xml”)); //Create the XslTransform object XslTransform xslDoc = new XslTransform(); xslDoc.Load(Server.MapPath(“Listing 7.4.xsl”)); //Create the XsltArgumentList object XsltArgumentList args = new XsltArgumentList(); args.AddParam(“golferName”,””,”Dan”); //Perform the transformation - pass in the parameters in the XsltArgumentList xslDoc.Transform(doc,args,Response.Output);

In the next section you’ll be presented with an ASP.NET application that does this task.

Putting It All Together You’ve now seen the main XSLT classes built in to the .NET framework. In this section you’ll see how these can be used to build a simple ASP.NET application that allows a user to select a specific golfer’s information from an XML document. After the golfer is chosen, XSLT will be

Transforming XML with XSLT and ASP.NET CHAPTER 7

279

used along with the XPathDocument, XslTransform, and XsltArgumentList classes to display the golfer’s information. Figures 7.4 and 7.5 show screen shots of the two pages involved in the sample XSLT application.

7

The golfer selection form.

FIGURE 7.5 The XSLT-generated results of the golfer selection.

To build this application, code-behind techniques were used in the ASP.NET page. If you’re not familiar with this mechanism in ASP.NET coding, it allows the actual program code to be stored separately from the visual portion (the HTML) found in the ASP.NET page. The technique of placing all the code (programming code and HTML) into one ASP.NET page shown in many places throughout the book was used simply to make listings easier to read and follow.

TRANSFORMING XML WITH XSLT AND ASP.NET

FIGURE 7.4

280

XML for ASP.NET Developers

In practice, however, it’s highly recommended that you leverage code-behind techniques to keep your ASP.NET code more maintainable. For this example, a file named xsltGolfer.aspx.cs contains all the programming code for the listings that follow, and xsltGolfer.aspx contains the HTML. The XSLT style sheet used for the application is named xsltGolfer.xsl. Let’s start by examining what code is executed when the ASP.NET page first loads (the Page_Load event). As you’ll see in Listing 7.10, this code takes care of loading all the firstName element values found in the XML document into a drop-down box. LISTING 7.10 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20:

The Page_Load Event and FillDropDown() Method (xsltGolfer.aspx.cs)

private void Page_Load(object sender, System.EventArgs e) { if (!Page.IsPostBack) { FillDropDown(“firstName”); } } private void FillDropDown(string element) { string name = “”; this.ddGolferName.Items.Clear(); XmlTextReader reader = new XmlTextReader(xmlPath); object firstNameObj = reader.NameTable.Add(“firstName”); while (reader.Read()) { if (reader.Name.Equals(firstNameObj)) { name = reader.ReadString(); ListItem item = new ListItem(name,name); this.ddGolferName.Items.Add(item); } } reader.Close(); }

You can see that the XmlTextReader and XmlNameTable classes are used to efficiently parse the XML data and add it to the drop-down box (ddGolferName). Both classes were discussed in Chapter 5, “Using the XmlTextReader and XmlTextWriter Classes in ASP.NET.” After the user selects a specific golfer from the drop-down box and clicks the button, the event is fired. The code within this event takes care of getting the selected golfer name value from the drop-down box and passes it into the XSLT style sheet by using the XsltArgumentList class. The style sheet then takes care of transforming the selected golfer’s XML data into HTML, as shown earlier in Figure 7.5. Listing 7.11 shows the code involved in this process. btnSubmit_Click

Transforming XML with XSLT and ASP.NET CHAPTER 7

LISTING 7.11

281

Transforming XML to HTML Using XSLT (xsltGolfer.aspx.cs)

Although this doesn’t show much in the way of new classes, it does show how the different classes discussed in earlier sections can be tied together to create an ASP.NET application that leverages XML and XSLT.

7 TRANSFORMING XML WITH XSLT AND ASP.NET

1: protected void btnSubmit_Click(object sender, System.EventArgs e) { 2: string xslPath = Server.MapPath(“xsltGolfer.xsl”); 3: XmlTextReader xmlReader = null; 4: StringBuilder sb = new StringBuilder(); 5: StringWriter sw = new StringWriter(sb); 6: 7: try { 8: xmlReader = new XmlTextReader(xmlPath); 9: //Instantiate the XPathDocument Class 10: XPathDocument doc = new XPathDocument(xmlReader); 11: 12: //Instantiate the XslTransform Classes 13: XslTransform transform = new XslTransform(); 14: transform.Load(xslPath); 15: 16: //Add Parameters 17: XsltArgumentList args = new XsltArgumentList(); 18: args.AddParam(“golferName”,””, 19: this.ddGolferName.SelectedItem.Value); 20: 21: //Call Transform() method 22: transform.Transform(doc, args, sw); 23: 24: //Hide-Show ASP.NET Panels in xsltGolfer.aspx 25: this.pnlSelectGolfer.Visible = false; 26: this.pnlTransformation.Visible = true; 27: this.divTransformation.InnerHtml = sb.ToString(); 28: } 29: catch (Exception excp) { 30: Response.Write(excp.ToString()); 31: } 32: finally { 33: xmlReader.Close(); 34: sw.Close(); 35: } 36: }

282

XML for ASP.NET Developers

Using Extension Objects with XSLT While looking through the methods exposed by the XsltArgumentList class back in Table 7.8, you may have wondered how the extension object methods could be used to enhance XSLT/ ASP.NET applications. Using these methods is surprisingly easy and can provide your XSLT style sheets with even more power and flexibility. Keep in mind that by using extension objects in XSLT, you may render your XSLT unusable on other platforms or by other languages simply because extensions are not a part of the XSLT 1.0 specification (the XSLT 1.1 working draft does include extension elements and functions, however). If your application will be the only one that uses a particular XSLT style sheet and you need additional functionality not in the XSLT 1.0 specification, extension objects may be the answer. Some other benefits of using extension objects include: • Methods on classes within other namespaces (other than System namespaces) can be called. • Extension functions allow better encapsulation and reuse of classes. • Style sheets can be kept smaller and more maintainable. What exactly is an extension object? Think of it as an external class that can be referenced and used within an XSLT style sheet. By using extension objects, you can get the current date and time, query a database to do a lookup based on a value found in the XML source document, hit a Web service, or trigger another application to begin running. All of this and much more can be done from within an XSLT style sheet. To see how this works in practice, the next code sample shown in Listing 7.12 builds on the previous one shown in Listing 7.11 to add the capability to write out the current date/time of the server from a specific location within the style sheet. Let’s first look at the class that will be instantiated and used as an extension object. LISTING 7.12

The Date/Time Extension Class (xsltDateObject.cs)

1: namespace XsltTransformation.ExternalObjects { 2: using System; 3: 4: public class XsltDateTime { 5: DateTime _date; 6: public XsltDateTime() { 7: _date = DateTime.Now; 8: } 9: public DateTime GetDateTime() { 10: return _date; 11: } 12: } 13: }

Transforming XML with XSLT and ASP.NET CHAPTER 7

283

This class (named XsltDateTime) does nothing more than return the current system date and time. It must be instantiated within an ASP.NET page and then added to the external object collection of the XsltArgumentList class. You may be wondering if it would be easier to pass the date and time into the style sheet using a regular XSLT parameter. The answer is “yes”; it would be easier because no external objects would be needed from within the style sheet. However, by calling the extension object from within the XSLT style sheet, a more up-to-date date/time value will be returned (assuming that accuracy matters in the application). And let’s face it, the demo code wouldn’t be as cool if a regular XSLT parameter was used, especially because you know all about those at this point!

LISTING 7.13

Adding an External Object to the XsltArgumentList Class (xsltExtension.aspx.cs) 1: protected void btnSubmit_Click(object sender, System.EventArgs e) { 2: 3: string xslPath = Server.MapPath(“xsltExtension.xsl”); 4: XsltDateTime xsltExtObj = new XsltDateTime(); //The Extension Object 5: XmlTextReader xmlReader = null; 6: StringBuilder sb = new StringBuilder(); 7: StringWriter sw = new StringWriter(sb); 8: 9: try { 10: xmlReader = new XmlTextReader(xmlPath); 11: 12: //Instantiate the XPathDocument Class 13: XPathDocument doc = new XPathDocument(xmlReader); 14: 15: //Instantiate the XslTransform Classes 16: XslTransform transform = new XslTransform(); 17: transform.Load(xslPath); 18: 19: //Add Parameters and Extension Object to the Collection 20: XsltArgumentList args = new XsltArgumentList(); 21: args.AddParam(“golferName”,””, 22: this.ddGolferName.SelectedItem.Value); 23: //Add the namespaceURI and object to the object collection 24: args.AddExtensionObject(“urn:xsltExtension-DateTime”, 25: xsltExtObj); 26: 27: //Call Transform() method

TRANSFORMING XML WITH XSLT AND ASP.NET

Listing 7.13 demonstrates how to pass an extension object into an XSLT style sheet using the XsltArgumentList class. The lines of code relating to the extension object use are shown in bold.

7

284

XML for ASP.NET Developers

LISTING 7.13 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: }

continued transform.Transform(doc, args, sw); //Hide ASP.NET Panels this.pnlSelectGolfer.Visible = false; this.pnlTransformation.Visible = true; this.divTransformation.InnerHtml = sb.ToString(); } catch (Exception excp) { Response.Write(excp.ToString()); } finally { xmlReader.Close(); sw.Close(); }

The XSLT style sheet obviously needs to be able to reference the XsltDateTime object that is passed in and call its GetDateTime() method. This is accomplished by adding the proper namespace prefix and URI into the style sheet. For this example, a namespace URI of urn:xsltExtension-DateTime is used along with a namespace prefix of dateTimeObj. Any namespace URI can be used as long as it is consistent between the ASP.NET page and the XSLT style sheet. Listing 7.14 shows the complete style sheet and highlights where the external object is referenced and used. LISTING 7.14

Calling External Objects Within an XSLT Style Sheet (xsltExtension.xsl)

1: 2: 4: 5: 6: 7: 9: 10: 11: 12: 13: 14:

16: 17:

Transforming XML with XSLT and ASP.NET CHAPTER 7

LISTING 7.14

continued

7 TRANSFORMING XML WITH XSLT AND ASP.NET

18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61:

285

286

XML for ASP.NET Developers

LISTING 7.14

continued

62: 65: 68: 71: 72: 73:

Skill:	color:#ff0000;font-weight:bold; color:#005300; color:#000000; color:#000000;	Handicap:	Clubs:

Favorite Courses
63: City: 64:	66: State: 67:	69: Course: 70:

74:

75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85: 86: 87: 88: 89: 90: 91: 92: 93: 94: 95: 96: 97: 98: 99: 100: 101: 102: 103: 104: List Course Information 105: 106:

Transforming XML with XSLT and ASP.NET CHAPTER 7

287

How is the GetDateTime() method called on the XsltDateTime object that is passed into the style sheet? This is accomplished by referencing the namespace prefix (dateTimeObj) associated with the namespace URI assigned to the object in the ASP.NET page (urn:xslt Extension-DateTime). The prefix is declared in line 3 and then used to call the GetDate Time() method in line 75. Although this is a fairly straightforward example of using external objects within XSLT style sheets, much more complicated functionality, such as querying databases or calling Web services, can be accomplished with XSLT external objects. Before this chapter ends, the next section will show how to create a reusable XSLT class that can be used within ASP.NET applications and demonstrate the asp:Xml Web control.

By now you should feel comfortable working with the different classes within the System.Xml assembly that can be used to perform XSL transformations. However, wouldn’t it be nice if you could write a generic class that doesn’t require any knowledge of the XPathDocument or XslTransform classes (and their supporting classes) to be used? Not only would such a class provide more productive programming, but it would also allow your ASP.NET applications to leverage all the benefits offered by following object-oriented programming techniques. The code in Listing 7.15 shows a generic class that allows an ASP.NET programmer to transform an XML document using XSLT without any knowledge of XSLT-specific classes. This code leverages well-known classes such as HashTable to accomplish the transformation. LISTING 7.15

A Reusable XSLT Transformation Class (xsltTransform.cs)

1: namespace XsltTransformation { 2: 3: using System; 4: using System.Xml; 5: using System.Xml.XPath; 6: using System.Xml.Xsl; 7: using System.Collections; 8: using System.IO; 9: using System.Text; 10: 11: /// 12: /// A generic XSL Transformation Class for use in ASP.NET pages 13: /// 14: public class XsltTransform { 15: 16: public static string TransformXml(string xmlPath,string xsltPath, 17: Hashtable xsltParams,Hashtable xsltObjects) {

TRANSFORMING XML WITH XSLT AND ASP.NET

Creating a Reusable XSLT Class

7

288

XML for ASP.NET Developers

18:

LISTING 7.15

continued

19: StringBuilder sb = new StringBuilder(); 20: StringWriter sw = new StringWriter(sb); 21: try { 22: XPathDocument doc = new XPathDocument(xmlPath); 23: XsltArgumentList args = new XsltArgumentList(); 24: XslTransform xslDoc = new XslTransform(); 25: xslDoc.Load(xsltPath); 26: 27: //Fill XsltArgumentList if necessary 28: if (xsltParams != null) { 29: IDictionaryEnumerator pEnumerator = 30: xsltParams.GetEnumerator(); 31: while (pEnumerator.MoveNext()) { 32: args.AddParam(pEnumerator.Key.ToString(),””, 33: pEnumerator.Value); 34: } 35: } 36: if (xsltObjects != null) { 37: IDictionaryEnumerator pEnumerator = 38: xsltObjects.GetEnumerator(); 39: while (pEnumerator.MoveNext()) { 40: args.AddExtensionObject(pEnumerator.Key.ToString(), 41: pEnumerator.Value); 42: } 43: } 44: xslDoc.Transform(doc,args,sw); 45: return sb.ToString(); 46: } 47: catch (Exception exp) { 48: return exp.ToString(); 49: } 50: finally { 51: sw.Close(); 52: } 53: } 54: } //XsltTransform 55: } // XsltTransformation namespace

Having a reusable class for XSL transformations results in much cleaner ASP.NET code, as Listing 7.16 shows.

Transforming XML with XSLT and ASP.NET CHAPTER 7

LISTING 7.16

289

Using the XsltTransform Class in ASP.NET (xsltTransform.aspx)

public void Page_Load(object sender, System.EventArgs e) { string xmlPath = Server.MapPath(“Listing7.1.xml”); string xslPath = Server.MapPath(“xsltExtension.xsl”); //Create the External Object XsltDateTime xsltExtObj = new XsltDateTime();

//Fill the Hashtables with the params and external objects xsltParams.Add(“golferName”,”Heedy”); xsltObjects.Add(“urn:xsltExtension-DateTime”,xsltExtObj); //Call the custom XsltTransform class’s TransformXml method string xsl = XsltTransform.TransformXml(xmlPath,xslPath, xsltParams,xsltObjects); Response.Write(xsl); }

As this book was going to press, I wrote a new article demonstrating how the techniques shown in Listing 7.15 can be used to create an ASP.NET server control geared at targeting multiple devices using XML and XSLT. This article will appear in the premier issue (September 2001) of Visual Studio Magazine (http://www.devx.com), and the code can be downloaded from the DevX site or from the CodeBank section of http://www.TomorrowsLearning.com.

The Asp:Xml Web Control The .NET framework also comes with a prebuilt Web control that can be used for doing simple XSL transformations in ASP.NET pages. This control allows the XML document source and XSLT style sheet source to be set using attributes. Listing 7.17 shows how the control is used. LISTING 7.17

Using the asp:Xml Web Control

1: 2: 3: 6: 7: 8:

In situations where the values of the DocumentSource and/or TransformSource attributes are not known until runtime, they can be assigned dynamically, as Listing 7.18 shows. LISTING 7.18 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11:

Dynamically Assigning Source Documents to the asp:Xml Web Control

void Page_Load(object sender, System.EventArgs e) { xslTransform.DocumentSource = “Listing7.1.xml”; xslTransform.TransformSource = “Listing7.2.xsl”; }

The asp:Xml server control also allows DOM structures to be passed into it programmatically using the Document and Transform properties: 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18:

void Page_Load(object sender, System.EventArgs e) { XmlDocument doc = new XmlDocument(); doc.Load(Server.MapPath(“Listing7.1.xml”)); XslTransform trans = new XslTransform(); trans.Load(Server.MapPath(“Listing7.2.xsl”)); xslTransform.Document = doc; xslTransform.Transform = trans; }

Transforming XML with XSLT and ASP.NET CHAPTER 7

291

Summary Although XSLT is a very big topic that can’t possibly be covered in a single chapter, you have been exposed to some of the more important aspects of the language that will get you started transforming XML documents in ASP.NET applications. XSLT provides a cross-platform, language-independent solution that can used to transform XML documents into a variety of structures.

In the next chapter, you’ll be provided with an in-depth look at the different XML features found in ADO.NET.

7 TRANSFORMING XML WITH XSLT AND ASP.NET

The .NET platform provides several classes developed specifically for doing XSLT transformations, including the XslTransform and XPathDocument classes. By using these and other classes, you have the ability to leverage the complete XSLT language in your ASP.NET applications.

CHAPTER

Leveraging ADO.NET’s XML Features Using ASP.NET

8

IN THIS CHAPTER • Introducing ADO.NET

294

• Comparing Classic ADO with ADO.NET • ADO.NET Basics • The DataSet Class

295 308

• Working with the DataSet and XmlDataDocument Classes 324

294

294

XML for ASP.NET Developers

Introducing ADO.NET ADO.NET represents the next evolutionary step in working with data located in local or distributed data stores. Although its name is very similar to the ActiveX Data Objects (ADO) of old, ADO.NET brings an abundance of new features to the table. In fact, ADO.NET has been rewritten from the ground up to make working with all types of data (including data in the form of XML) easier and more manageable. This chapter discusses many of ADO.NET’s new features and shows you how straightforward it is to work with data structured as XML. If you’re already familiar with “classic” ADO, you’re likely interested in knowing how it differs from ADO.NET. Let’s start things off by comparing the two.

Comparing Classic ADO with ADO.NET If you’ve had the opportunity to work with ADO much, you know it represents an excellent way of retrieving and manipulating data from a variety of data stores. Whether you’re hitting SQL Server, Oracle, DB2, or even a nonrelational store, ADO provides many interfaces that allow you to effectively integrate data into your applications. ADO even allows for the automatic generation of XML, although this feature didn’t appear until ADO 2.5. Because of XML’s more recent emergence as a power player among the world’s programming languages, however, it was an afterthought in ADO and not truly integrated from the ground up. This doesn’t infer that the architects of ADO didn’t plan properly for the future. It simply exemplifies how fast technology changes!

XML Integration ADO.NET flips the scale as far as XML integration goes. No longer are you restricted to converting a Recordset to XML using adPersistXml or some other manual means. In ADO.NET, XML is a first-class citizen, and its integration is apparent from the start. What does this mean for your ASP.NET projects? Quite simply, you no longer have to worry about which way you’d like to work with data. If you would rather work with a standard relational view, you can. If you need to work with XML natively, you can do that as well. Changing between these different views can be accomplished with a call to a single property. We’ll talk more about this in a moment.

What Happened to the RecordSet Object? XML’s tight integration with ADO.NET isn’t the only big change that has been made. You may be surprised to know that the RecordSet object no longer exists in ADO.NET! Wait, you say, what happened to the RecordSet object? Wasn’t it one of the main objects in ADO? Although the RecordSet is very useful, it has been replaced with a more functional and robust class

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

295

called the DataSet. Although we’ll discuss the DataSet in more detail later in this chapter, some of its new features include support for hierarchical relationships between tables, the capability to add constraints, and much more. This means that you can now relate a database’s Customers table to the Orders table all within the same object. This hierarchical association is done without resorting to shape commands. The RecordSet object also has another inherent problem that could haunt you, depending on the context it was being used in. For example, if you attempt to pass a RecordSet between objects living on opposite sides of a firewall, a potential problem could arise if the RecordSet was blocked from passing through. With ADO.NET, this problem is alleviated because the DataSet class is based in XML. Because XML can ride on top of protocols such as HTTP, exchanging data records between objects living virtually anywhere in the world is now possible.

Disconnected Versus Connected

Another important point that can be made about ADO.NET is that DataSets are always disconnected, which results in connections being released earlier. Looping through a DataSet can be done without any connection being open to the data source. Although this can be done using the disconnected RecordSet in ADO, disconnected Recordsets are still subject to the inefficiencies found in COM marshaling, as mentioned earlier. Although many other benefits are associated with ADO.NET, we’ll limit the scope of our discussions to topics relating specifically to ADO.NET, XML, and ASP.NET in this chapter. However, if you have no experience working with ADO.NET, there’s no need to worry. The next few sections cover enough of the basics to get you up to speed quickly. After the basics are covered, you’ll see how XML can be used in conjunction with ADO.NET.

ADO.NET Basics If you have experience working with “classic” ADO, you’ll be happy to know that much of what you already know can be applied to ADO.NET. Although the RecordSet object no longer exists, you’ll find that ADO.NET’s Connection, Command, and DataSet classes are still based on many principles you’re already familiar with. One big change that you’ll see in the examples that follow is that ADO.NET is much more object oriented than ADO was. Even declaring

8 LEVERAGING ADO.NET’S XML FEATURES

The DataSet class shifts ADO.NET away from the connection-based model exposed by ADO and toward a more message-like model. This change offers many improvements, including the capability to send data through firewalls, the elimination of type conversions in COM, and a truly disconnected way of working with data. ADO.NET’s basis in XML means that virtually any data type can now be supported and passed. This is in contrast to the limited set of data types exposed by COM marshaling. The elimination of type conversions results in an increase in scalability and efficiency.

296

XML for ASP.NET Developers

a data type is accomplished through the use of objects. To prepare you for working with the new ADO.NET classes, the next section covers the different managed providers that can be used to connect to a data source.

ADO.NET Managed Providers ADO used providers such as Jet and OLE DB for accessing different data stores. Although both still can play a role in ADO.NET, the choice of which managed provider to use when working with the .NET platform is broken into two basic choices. These are • SQL Managed Provider—This provider is used only if connecting to a SQL Server 7.0 or later database. Direct communication with SQL Server can be achieved through the use of the Tabular Data Stream (TDS) protocol. This presents an efficient means of accessing SQL Server because OLE DB is bypassed. • OLE DB Managed Provider—This provider allows for access to all other data sources, including Access, Sybase, Oracle, DB2, and so on. It can also be used to access SQL Server 7.0 or later, although using the SQL managed provider is more efficient in this scenario. If you’re wondering why the word “managed” is being used to describe a provider, you need to take into consideration how the .NET platform works. With the introduction of languages such as C# and the Common Language Runtime, data or memory used within the .NET platform is allocated and released automatically using a garbage collection system. The .NET framework provides a runtime environment that manages code execution and many other services for you. If you’re coming from a C++ background, you know that the process of having memory and objects cleaned up for you isn’t normally found within the C++ language environment. Memory must be allocated and managed by the programmer rather than by a system or platform. The managed providers in ADO.NET simply leverage .NET’s managed environment so that many coding details are taken care of for you in the background. This doesn’t preclude you from implementing sound programming practices, but it does eliminate many complexities. Different ADO.NET classes are used, depending on which managed provider you choose. The code written to use either provider is remarkably similar in many cases, however. The next two sections will introduce how you can establish a connection to a data source using either the SqlConnection and OleDbConnection classes.

SQL Managed Provider Connection Class When using the SQL Managed Provider, the System.Data.SqlClient namespace must be referenced in your ASP.NET page. Although not necessary for basic ADO.NET functionality, it’s also wise to import the System.Data namespace because it will come into play when using type information for stored procedure parameters, and so on. After these namespaces have been

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

297

imported, initiating a connection to a SQL Server database is as easy as creating an instance of the SqlConnection class, as shown next: void Page_Load(Object Src, EventArgs E) { string connStr = “server=localhost;uid=sa;pwd=;database=northwind”; SqlConnection conn = new SqlConnection(connStr); Response.Write(“Connection established!”); }

Alternatively, the connection string can also be set using the ConnectionString property:

As shown, the main class used in the preceding samples is the SQLConnection class.

OLE DB Managed Provider Connection Class Now that you’ve seen how to use the SQL managed provider, learning how to use the OLE DB managed provider will be a snap. Very few differences exist between the two providers as far as instantiating connections to data sources. One change that must be made is importing the System.Data.OleDb namespace into your ASP.NET page rather than the System.Data. SqlClient namespace. The following code shows how to use the OleDbConnection class to hit the Northwind database: void Page_Load(Object Src, EventArgs E) { string connStr = @”Provider=SQLOLEDB.1;Data Source=(local); uid=sa;pwd=;Initial Catalog=northwind”; OleDbConnection conn = new OleDbConnection(); conn.ConnectionString = connStr; Response.Write(“Connection established!”); }

8 LEVERAGING ADO.NET’S XML FEATURES

void Page_Load(Object Src, EventArgs E) { string connStr = “server=localhost;uid=sa;pwd=;database=northwind”; SqlConnection conn = new SqlConnection(); conn.ConnectionString = connStr; Response.Write(“Connection established!”); }

298

XML for ASP.NET Developers

Comparing the SQL to the OLE DB managed provider, you can see that each imports a different namespace and uses the appropriate connection class to attach to a data source. Apart from these differences, the code is virtually the same.

The Command Class After you have connected to a data source, you’ll more than likely want to either select data or perform some other operation such as an update, insert, or delete. ADO.NET handles this type of functionality through the Command class. The use of the word “Command” is generic because the actual type of command that you use will depend on which ADO.NET managed provider you use to connect to the data store. For example, if you’ll be using the SQL managed provider, you’ll want to use the SqlCommand class. If you’ll be using the ADO managed provider, you’ll want to use the OleDbCommand class. To see how this class is instantiated and used, take a look at the samples that follow. Listing 8.1 and Listing 8.2 both instantiate the appropriate Command class on Line 9, respectively. LISTING 8.1

Using the SQL Managed Provider Command Class

1: public class SqlConnect { 2: private SqlConnection dataConn = null; 3: private SqlDataReader reader = null; 4: 5: public string openConnection(HttpResponse Response, 6: string dbConnectString,string cmdString) { 7: try { 8: dataConn = new SqlConnection(dbConnectString); 9: SqlCommand sqlCmd = new SqlCommand(cmdString,dataConn); 10: dataConn.Open(); 11: reader = sqlCmd.ExecuteReader(); 12: Response.Write(“

” + 13: “”); 14: while (reader.Read()) { 15: Response.Write(“”); 16: Response.Write(“”); 18: Response.Write(“”); 20: Response.Write(“”); 21: } 22: Response.Write(“

ID	Name
” + reader[“CategoryID”].ToString() + 17: “	” + reader[“CategoryName”].ToString() + 19: “

”); 23: return “

Sql Server Data Connection Opened”; 24: } 25: catch (Exception e) { 26: return(e.ToString());

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

LISTING 8.1 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: }

299

continued } finally { if (reader != null) { reader.Close(); } if (dataConn != null) { dataConn.Close(); } }

}

LISTING 8.2

Using the OLE DB Managed Provider Command Class

8 LEVERAGING ADO.NET’S XML FEATURES

1: public class OleDbConnect { 2: private OleDbConnection dataConn = null; 3: private OleDbDataReader reader = null; 4: 5: public string openConnection(HttpResponse Response, 6: string dbConnectString,string cmdString) { 7: try { 8: dataConn = new OleDbConnection(dbConnectString); 9: OleDbCommand oleDbCmd = new OleDbCommand(cmdString,dataConn); 10: dataConn.Open(); 11: reader = oleDbCmd.ExecuteReader(); 12: Response.Write(“

” + 13: “”); 14: while (reader.Read()) { 15: Response.Write(“”); 16: Response.Write(“”); 18: Response.Write(“”); 20: Response.Write(“”); 21: } 22: Response.Write(“

ID	Name
” + reader[“CategoryID”].ToString() + 17: “	” + reader[“CategoryName”].ToString() + 19: “

”); 23: return “

OleDb Server Data Connection Opened”; 24: } 25: catch (Exception e) { 26: return(e.ToString()); 27: } 28: finally { 29: if (reader != null) {

300

XML for ASP.NET Developers

LISTING 8.2 30: 31: 32: 33: 34: 35: 36: 37: }

continued reader.Close(); } if (dataConn != null) { dataConn.Close(); } }

}

Both examples exemplify passing the command string and a Connection object as arguments to the appropriate Command class’s constructor. Several other constructors can be used to instantiate a Command, but we’ll forgo that discussion because the .NET documentation details each constructor well. After the Command object has been created, the connection’s Open() method is called and the appropriate Command is executed. Assuming that the following SQL string is passed to the openConnection() method found in both listings, all fields existing in the Categories table will be returned: “SELECT * FROM Categories”

Having all the fields in the Categories table is certainly a step forward (you have to start somewhere, right?), but what can we do with them? Both listings access the different fields by using the DataReader class (SqlDataReader or OleDbDataReader). As each field is accessed, information about it is written out to a Web page using the Response object. Although little focus will be placed on the DataReader in this chapter, it’s important to understand that because of the read-only, forward-only architecture it provides, the DataReader class offers the best performance for your ASP.NET applications in cases where data simply need to be displayed. The DataReader works in a manner similar to the XmlTextReader discussed in Chapter 5, “Using the XmlTextReader and XmlTextWriter Classes in ASP.NET,” and is very efficient when dealing with multiple records because it does not buffer a large amount of data at any given time. Several other classes and ASP.NET objects can be used to work with data returned from a data source, which you’ll learn about later in this chapter.

Accessing Stored Procedures with the Command Class Building scalable and robust ASP.NET applications involves taking advantage of any possible gain in speed or efficiency. Accessing data using the SqlCommand or OleDbCommand classes is no exception. Although getting data can be done with regular SQL statements, stored procedures should be used whenever possible because they are compiled and they create a map specifying the quickest route to the data.

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

301

The code used with the ADO.NET Command class to access a stored procedure is much like the code used to do the same using the Command object in ADO. A few differences exist in how data types are declared, but for the most part the parameters passed into or out of a stored procedure are created much like they used to be in ADO. Listing 8.3 shows an example of accessing a stored procedure using the SQL managed provider. LISTING 8.3

public class SqlConnect { private SqlConnection dataConn = null; private SqlDataReader reader = null; public string OpenConnection(HttpResponse Response, string dbConnectString,string cmdString, string paramName, string paramValue) { try { dataConn = new SqlConnection(dbConnectString); SqlCommand sqlCmd = new SqlCommand(cmdString,dataConn); sqlCmd.CommandType = CommandType.StoredProcedure; SqlParameter param = sqlCmd.Parameters.Add(new SqlParameter(paramName,SqlDbType.Char, 5)); param.Direction = ParameterDirection.Input; sqlCmd.Parameters[paramName].Value = paramValue; dataConn.Open(); reader = sqlCmd.ExecuteReader(); Response.Write(“

”); Response.Write(“”); while (reader.Read()) { Response.Write(“”); Response.Write(“”); Response.Write(“”); } Response.Write(“

Product Name	Total
”+reader[“ProductName”].ToString()); Response.Write(“	”+reader[“Total”].ToString()); Response.Write(“

”); return “

Stored Procedure called successfully!”; } catch (Exception e) { return(e.ToString()); }

8 LEVERAGING ADO.NET’S XML FEATURES

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37:

Accessing Stored Procedures Using the SQL Provider

302

XML for ASP.NET Developers

LISTING 8.3

continued

38: finally { 39: if (reader != null) { 40: reader.Close(); 41: } 42: if (dataConn != null) { 43: dataConn.Close(); 44: } 45: } 46: } 47: } // SqlConnect 48: 49: public void Page_Load(Object Src, EventArgs E) { 50: string connStr = “server=localhost;uid=sa;pwd=;database=Northwind”; 51: string sql = “CustOrderHist”; 52: //Open Sql Connection 53: SqlConnect sqlconn = new SqlConnect(); 54: sqlconn.OpenConnection(Response, connStr,sql,”@customerID”,”ALFKI”); 55: } 56:

This example hits the Northwind sample database’s CustOrderHist stored procedure, which accepts the customer ID as an input parameter. Although very limited in functionality (especially because it allows for only one parameter), the SqlConnect class takes care of executing the CustOrderHist procedure by first setting the newly instantiated Command object’s CommandType property to CommandType.StoredProcedure (line 14). The following types exist in the CommandType enumeration: •

StoredProcedure

•

TableDirect

•

Text

After the CommandType is specified, lines 16–20 take care of adding the appropriate parameter to be used with the stored procedure and specify its direction. You’ll notice that the data type of the parameter uses another enumeration named SqlDbType rather than simply listing adChar as in ADO. The SqlDbType enumeration contains the following data types: BigInt

NVarChar

Binary

Real

Bit

SmallDateTime

Char

SmallInt

DateTime

SmallMoney

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8 Decimal

Text

Float

TimeStamp

Image

TinyInt

Int

UniqueIdentifier

Money

VarBinary

NChar

VarChar

NText

Variant

303

After the name, data type, and size of the parameter are created, the procedure’s value is set in line 20 and the connection is opened. The remainder of the class uses the DataReader mentioned earlier in the chapter to write data out to the ASP.NET page. As previously mentioned, the code to accomplish this task looks much like the code used to do the same in ADO, even though ADO.NET introduces a few new classes and enumerations. If you’re using the ADO managed provider, the type of the parameter can be set using the OleDbType enumeration. This enumeration contains the following data types: LongVarBinary

Binary

LongVarChar

Boolean

LongVarWChar

BSTR

Numeric

Char

PropVariant

Currency

Single

Date

SmallInt

DBDate

TinyInt

DBTime

UnsignedBigInt

DBTimeStamp

UnsignedInt

Decimal

UnsignedSmallInt

Double

UnsignedTinyInt

Empty

VarBinary

Error

VarChar

Filetime

Variant

Guid

VarNumeric

IDispatch

VarWChar

Integer

WChar

IUnknown

8 LEVERAGING ADO.NET’S XML FEATURES

BigInt

304

XML for ASP.NET Developers

The connection class shown in Listing 8.3 would look like Listing 8.4 when using the OLE DB managed provider. LISTING 8.4

Accessing Stored Procedures Using the OLE DB Provider

1: 2: 3: 4: public class OleDbConnect { 5: private OleDbConnection dataConn = null; 6: private OleDbDataReader reader = null; 7: public string OpenConnection(HttpResponse Response, 8: string dbConnectString,string cmdString, 9: string paramName,string paramValue) { 10: try { 11: dataConn = new OleDbConnection(dbConnectString); 12: OleDbCommand oleDbCmd = new OleDbCommand(cmdString,dataConn); 13: oleDbCmd.CommandType = CommandType.StoredProcedure; 14: OleDbParameter param = null; 15: param = oleDbCmd.Parameters.Add(paramName, OleDbType.Char, 5); 16: param.Direction = ParameterDirection.Input; 17: oleDbCmd.Parameters[paramName].Value = paramValue; 18: dataConn.Open(); 19: reader = oleDbCmd.ExecuteReader(); 20: Response.Write(“

” + 21: “”); 22: while (reader.Read()) { 23: Response.Write(“”); 24: Response.Write(“”); 26: Response.Write(“”); 28: Response.Write(“”); 29: } 30: Response.Write(“

Product Name	Total
” + reader[“ProductName”].ToString() + 25: “	” + reader[“Total”].ToString() + 27: “

”); 31: return “

OleDb Server Data Connection Opened”; 32: } 33: catch (Exception e) { 34: return(e.ToString()); 35: } 36: finally { 37: if (reader != null) { 38: reader.Close(); 39: } 40: if (dataConn != null) { 41: dataConn.Close();

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

LISTING 8.4 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55:

305

continued

} } } //OpenConnection } //OleDbConnect public void Page_Load(Object Src, EventArgs E) { string connStr = @”Provider=SQLOLEDB.1;Data Source=(local); uid=sa;pwd=;Initial Catalog=Northwind”; string sql = “CustOrderHist”; //Open Sql Connection OleDbConnect oleDbconn = new OleDbConnect(); oleDbconn.OpenConnection(Response, connStr,sql,”@customerID”,”ALFKI”); }

If you don’t feel like typing all the parameter information, you can always call the procedure directly passing the appropriate parameters. This would be similar to calling the stored procedure using the SQL Server Query Analyzer:

Working with Output and Return Values If a stored procedure you’re working with passes back output or return values, the following lines can be added as appropriate to the code shown in Listings 8.3 and 8.4 to handle these values. SQL Managed Provider Output Value: param = sqlCmd.Parameters.Add(new SqlParameter(“@output”, SqlDbType.Int)); param.Direction = ParameterDirection.Output; // ......Additional code here Response.Write(sqlCmd.Parameters[“@output”].Value);

OLE DB Managed Provider Output Value: param = oleDbCmd.Parameters.Add(“@output”,OleDbType.Integer); param.Direction = ParameterDirection.Output; // . . . . . . . . . . . . Response.Write(oleDbCmd.Parameters[“@output”].Value);

If you need to access a return value from a stored procedure, use code similar to the following code segments: SQL Managed Provider Return Value:

8 LEVERAGING ADO.NET’S XML FEATURES

string cmdString = “exec CustOrderHist @customerID = ‘ALFKI’”; SQLCommand sqlCmd = new SQLCommand(cmdString,dataConn);

306

XML for ASP.NET Developers

param = sqlCmd.Parameters.Add(new SqlParameter(“RT_VAL”, SqlDbType.Int)); param.Direction = ParameterDirection.ReturnValue; . . . . . . . . . . . . Response.Write(sqlCmd.Parameters[“RT_VAL”].Value);

OLE DB Managed Provider Return Value: param = oleDbCmd.Parameters.Add(“RETURN_VALUE”, OleDbType.Integer); param.Direction = ParameterDirection.ReturnValue; . . . . . . . . . . . . Response.Write(oleDbCmd.Parameters[“RETURN_VALUE”].Value);

The SqlDataAdapter and OleDbDataAdapter Classes The Command class discussed in the previous section is very useful for performing direct inserts, updates, and deletes to a data source, and it can be used in combination with the DataReader class to select and view data. However, nothing we’ve seen thus far allows us to work natively with XML unless we use the DataReader to manually create the XML. Because ADO.NET supposedly makes it easy to work with XML, what can we do? Enter the data adapter classes. Each managed provider has its own data adapter class that can be used to work with data in a disconnected and more message-based manner. The SQL managed provider uses an adapter named SqlDataAdapter, whereas the OLE DB managed provider uses the OleDbDataAdapter. For the sake of clarity, the next sections focus mainly on the SqlDataAdapter. However, both adapters are intended to accomplish the same end result, so what you learn about one will be applicable to the other in many cases. On its own, the SqlDataAdapter class can’t work with XML, but it acts as a gateway to accessing the DataSet class, which makes it easy to work with XML. The SqlDataAdapter class also makes it possible to completely disconnect DataSets from the data source because it takes care of all the interaction with the appropriate managed provider. The SqlDataAdapter inherits from a base data adapter class named DataAdapter that provides the bridge between a data source and a DataSet object. Here’s an example of using it to select data using a SQL managed provider: SqlDataAdapter sqlAdapter = new SqlDataAdapter(cmdString,dataConn);

The same thing can be accomplished with the OLE DB managed provider: OleDbDataAdapter oleDbAdapter = new OleDbDataAdapter(cmdString,dataConn);

This code looks very similar to the code used to work with the command classes in Listings 8.1 and 8.2, doesn’t it? The different data adapter classes have constructors that accept the SQL string to execute and the connection object. We won’t discuss them here, but several other constructors can be used, as well.

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

307

The similarities between the command and data adapter classes stop when you take the retrieved data and place it into a DataSet. Although the command classes have no methods for filling a DataSet, the adapter classes expose the Fill() method. You’ll see this method in action after the DataSet class has been defined more in the next section. The DataSet section contains a discussion on how to work with data returned from a data source using XML. The data adapter classes also allow you to define what stored procedures (or SQL string) to use for doing inserts, updates, and deletes. This process occurs by assigning values to different properties. After the properties have been set, you can call the Update() method on the appropriate data adapter class to execute the stored procedures or SQL strings. Any changes made to the DataSet will then be updated in the data source, depending on what stored procedures you specified. To see this in action, take a look at the following code. An example shown later in the chapter shows how to use these in the context of a real application.

After the stored procedures to use are established, the data adapter’s Update() method can then be called. This will cause any records deleted from a DataSet to be deleted from the data source. Likewise, any updates or inserts to the DataSet will also be updated or inserted, as appropriate, into the data source. Some of the stored procedures previously shown (sp_UpdateOrder, for instance) may require that you pass in certain input parameters. For example, you may desire to update specific fields in the data source rather than the entire row. Adding parameters to the appropriate insert, update, or delete command can be accomplished by adding the parameter name, type and value. The following code will set the @warehouse input parameter’s value: sqlAdapter.UpdateCommand = new SqlCommand(“sp_UpdateOrder”,conn); sqlAdapter.UpdateCommand.CommandType = CommandType.StoredProcedure; sqlAdapter.UpdateCommand.Parameters.Add(new SqlParameter(“@warehouse”, SqlDbType.NChar, 5)); sqlAdapter.UpdateCommand.Parameters[0].Value = “main”; sqlAdapter.Update(DataSetObjectName);

Now that you’ve had a chance to get your feet wet with ADO.NET, let’s begin our discussion on using ADO.NET and the DataSet class to work with XML data.

8 LEVERAGING ADO.NET’S XML FEATURES

SqlDataAdapter sqlAdapter = new SqlDataAdapter(sql,conn); // Insert Command sqlAdapter.InsertCommand = new SqlCommand(“sp_InsertOrder”,conn); sqlAdapter.InsertCommand.CommandType = CommandType.StoredProcedure; // Update Command sqlAdapter.UpdateCommand = new SqlCommand(“sp_UpdateOrder”,conn); sqlAdapter.UpdateCommand.CommandType = CommandType.StoredProcedure; // Delete Command sqlAdapter.DeleteCommand = new SqlCommand(“sp_DeleteOrder”,conn); sqlAdapter.DeleteCommand.CommandType = CommandType.StoredProcedure;

308

XML for ASP.NET Developers

The DataSet Class ADO.NET introduces a brand-new way of working with data in ASP.NET applications. Rather than being connection based, a new messagelike mechanism has been developed that leverages a class called the DataSet. Before learning more about the benefits that the DataSet class can bring your ASP.NET applications, let’s look at a few limitations of the “classic” ADO Recordset. The RecordSet is one of the main objects used to work with data in ADO. Using a RecordSet, data can be selected from a data source and placed into an ASP page or manipulated using filters or sorts. Although the RecordSet object is certainly very useful, it does have a few limitations. One of these limitations (discussed earlier in the chapter) is linked to the difficulty of passing RecordSet objects through firewalls. Although poking a hole in a firewall may be an option within your organization (if you have an extremely lenient LAN manager), exchanging Recordsets with other companies becomes next to impossible with the presence of many potential firewalls. Another limitation is that RecordSets (even disconnected RecordSets) are subject to COM marshaling, which creates inefficiencies as data types in the RecordSet are converted to COM data types. In this world of distributed systems, the capability to support a wide range of data types is paramount to interoperate with other systems and applications. The RecordSet object also relies on a connection-based model by default and lacks integrated support for working with XML and XML schemas. The DataSet class strives to remedy some of the limitations found in the Recordset and add additional functionality to enable distributed applications to communicate more effectively. The following list details some of the improvements found in the DataSet class: • The DataSet is completely disconnected and has no knowledge of the data source. All communication with the data source is done through the managed provider. • The DataSet can easily be viewed as an XML document and queried using XPath. This XML basis means that it can pass through firewalls by riding on top of the HTTP protocol or be integrated into Web services. • The DataSet allows multiple tables to be added, along with relationships and constraints between the tables. • Because DataSets are XML aware, more robust data types can be described, and inefficiencies associated with COM marshaling are eliminated. •

DataSets

can be mapped to XML schemas that can be used to create an initial structure.

To better understand how DataSets can be used in ASP.NET applications, let’s take a look at a sample shown in Listing 8.5 that uses the data adapter classes to fill a DataSet with data from SQL Server’s Northwind database.

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

LISTING 8.5

Filling the DataSet Class with Data

public class SqlConnect { public string OpenConnection(HttpResponse Response, string dbConnectString,string cmdString) { try { DataSet dsOrders = new DataSet(); SqlConnection dataConn = new SqlConnection(dbConnectString); SqlDataAdapter sqlAdapter = new SqlDataAdapter(cmdString,dataConn); sqlAdapter.Fill(dsOrders,”Orders”); // Loop through DataSet “Orders” table Response.Write(“

”); foreach (DataRow Order in dsOrders.Tables[“Orders”].Rows) { Response.Write(“”); Response.Write(“”); Response.Write(“”); } Response.Write(“

Order ID

” + Order[“OrderId”].ToString() + “

”); return “

Sql Server Data Connection Opened”; } catch (Exception e) { return(e.ToString()); } } } public class OleDbConnect { public string OpenConnection(HttpResponse Response, string dbConnectString,string cmdString) { try { DataSet dsOrders = new DataSet(); OleDbConnection dataConn = new OleDbConnection(dbConnectString); OleDbDataAdapter oleDbAdapter = new OleDbDataAdapter(cmdString,dataConn); oleDbAdapter.Fill(dsOrders,”Orders”);

8 LEVERAGING ADO.NET’S XML FEATURES

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44:

309

310

XML for ASP.NET Developers

LISTING 8.5 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76:

continued // Loop through DataSet “Orders” table Response.Write(“

”); foreach (DataRow Order in dsOrders.Tables[“Orders”].Rows) { Response.Write(“”); Response.Write(“”); Response.Write(“”); } Response.Write(“

Order ID

” + Order[“OrderId”].ToString() + “

”); return “

OleDb Server Data Connection Opened”; } catch (Exception e) { return(e.ToString()); }

} } public void Page_Load(Object Src, EventArgs E) { string SqlconnStr = “server=localhost;uid=sa;pwd=;database=Northwind”; string OleDbconnStr = @”Provider=SQLOLEDB.1;Data Source=(local); uid=sa;pwd=;Initial Catalog=Northwind”; string sql = “SELECT OrderID FROM Orders”; Response.Write(“SQL Managed Provider DataSet:”); SqlConnect sqlConn = new SqlConnect(); sqlConn.OpenConnection(Response,SqlconnStr,sql); Response.Write(“

OleDb Managed Provider DataSet:”); OleDbConnect oleDbConn = new OleDbConnect(); oleDbConn.OpenConnection(Response,OleDbconnStr,sql); }

Listing 8.5 shows how both managed providers can be used to fill a DataSet object with data. The discussion that follows will focus on the SQL managed provider code found in the SqlConnect class. When the ASP.NET page is first loaded, Page_Load is called, which takes care of instantiating the SqlConnect class and calling its OpenConnection() (lines 68 and 69). This method accepts the Response object, the connection string, and the SQL statement to execute against the data source. Looking at line 11, you’ll notice that a DataSet class is instantiated and then filled with the results of the SQL query. This is accomplished by calling the SqlDataAdapter’s Fill() method (line 16).

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

311

The Fill() method has several overrides. The one shown here passes the DataSet to fill and the name of the table that is being filled in the DataSet (Orders in this example) as arguments. Because only one table is being added to the DataSet, the second argument is optional. Another version of the method allows the DataSet and table name to be passed as arguments along with the record number to start with and the maximum number of records to include. This allows you to say, “Fill the DataSet but start with row 25 and include the next 10 rows that follow” by using this code: sqlAdapter.Fill(dsOrders,25,10,”Orders”);

Viewing DataSets as XML DataSets make it very easy to work with relational data and perform all types of manipulations. However, many ASP.NET applications require data found within a DataSet to be converted to XML so that it can be passed to an XML-aware application, transformed using XSLT, or have some other action performed on it. Listing 8.6 shows one way of viewing DataSet data as XML, but to make things more interesting, it fills a DataSet with two different tables from the Northwind database. It then relates the two tables to each other based on the CustomerID field. An explanation of the code follows.

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21:

Filling a DataSet with Multiple Tables

public class SqlConnect { public DataSet ReturnDataSet(string dbConnectString, string table1,string table2) { DataSet dsTables = new DataSet(); dsTables.DataSetName = “CustomersData”; SqlConnection dataConn = new SqlConnection(dbConnectString); SqlDataAdapter customersAdapter = new SqlDataAdapter(table1,dataConn); SqlDataAdapter ordersAdapter = new SqlDataAdapter(table2,dataConn); customersAdapter.Fill(dsTables,”Customers”); ordersAdapter.Fill(dsTables,”Orders”); dsTables.Relations.Add(“CustomerOrders”, dsTables.Tables[“Customers”].Columns[“CustomerId”], dsTables.Tables[“Orders”].Columns[“CustomerId”]);

LEVERAGING ADO.NET’S XML FEATURES

LISTING 8.6

8

312

XML for ASP.NET Developers

LISTING 8.6

continued

22: return(dsTables); 23: } 24: } 25: public void Page_Load(Object Src, EventArgs E) { 26: string SqlconnStr = “server=localhost;uid=sa;pwd=;” + 27: “database=Northwind”; 28: string table1 = @”SELECT * FROM Customers WHERE CustomerID LIKE ‘h%’ 29: ORDER BY ContactName”; 30: string table2 = “SELECT * FROM Orders WHERE CustomerID LIKE ‘h%’”; 31: StringBuilder output = new StringBuilder(); 32: DataRow[] rows; 33: //Open Sql Connection 34: SqlConnect Sqlconn = new SqlConnect(); 35: DataSet TablesDataSet = Sqlconn.ReturnDataSet(SqlconnStr, 36: table1,table2); 37: 38: foreach (DataRow Customer in TablesDataSet.Tables[“Customers”].Rows){ 39: output.Append(“”); 41: output.Append(“”); 44: output.Append(“

” + 49: “

” + 46: “Customer Name: “); 47: output.Append(Customer[“ContactName”].ToString() + “

”); 48: output.Append(“

”); 50: output.Append(“”); 51: output.Append(“”); 54: // Iterate over orders data 55: rows = Customer.GetChildRows( 56: TablesDataSet.Relations[“CustomerOrders”]); 57: if (rows.Length > 0) { 58: foreach (DataRow Order in rows) { 59: output.Append(“Order: #” + 60: Order[“OrderId”].ToString()); 61: output.Append(“ Shipping Address:” + 62: Order[“ShipAddress”].ToString()); 63: } 64: } else {

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

LISTING 8.6

313

continued

This example shows how you can walk relationships between tables. It also gives a quick glimpse into how easy it is to view data held within a DataSet as XML. When the page first loads, a class named SqlConnect is instantiated and its ReturnDataSet() method is called (lines 34–36). The ReturnDataSet() method accepts a connection string and

8 LEVERAGING ADO.NET’S XML FEATURES

65: output.Append(“No Records”); 66: } 67: output.Append(“”); 68: } 69: content.InnerHtml = output.ToString(); 70: XmlDataDocument dataDoc = new XmlDataDocument(TablesDataSet); 71: xml.Text = dataDoc.OuterXml; 72: } 73: 74: 75: 76: function showDetails(id) { 77: var loc = document.all(id); 78: if (loc.style.display == ‘none’) { 79: loc.style.display = ‘block’; 80: } else { 81: loc.style.display = ‘none’; 82: } 83: 84: } 85: 86: 87: 88: 89: Walking Multiple DataSet Tables 90: 91: 92:

93: 94:

95: XML Data: 96: 97: 99: 100:

314

XML for ASP.NET Developers

two SQL queries as arguments. The method works by first creating a DataSet object named dsTables (line 10). SqlConnection and SqlDataAdapter objects are then created and the SqlDataAdapter objects are used to query the database and hold the results of data from two SQL queries passed into the method (lines 13–16). Two tables within the DataSet (dsTables) are then filled with data from the two data adapters by calling each data adapter’s Fill() method (lines 17 and 18). This method has several overrides that can be used. When the two tables within the DataSet are filled, a relationship is established between the tables, using the Relations property (lines 19–21). This associates both tables based on their CustomerID fields and makes it possible to create a parent/child relationship within the DataSet. After all this has been done, the DataSet is returned to the caller of the ReturnDataSet method. When the filled DataSet is ready to use, each row of the Customers table (within the DataSet) is looped through using a foreach loop (lines 38–68). Before moving to the next row, the current CustomerID is used to find all the orders for the appropriate customer in the Orders table of the DataSet. These rows are then looped through with an additional foreach loop (lines 58–63). The entire process adds data to a StringBuilder class named output that is written out to the ASP.NET page on completion of the looping process. Line 70 shows one potential way of viewing the data held within the DataSet as XML. It creates an XmlDataDocument class and passes in the DataSet (TablesDataSet in this example) to its constructor. The XmlDataDocument class extends the XmlDocument class detailed in Chapter 6, “Programming the Document Object Model (DOM) with ASP.NET,” and provides a way to work with data using the Document Object Model (DOM). This is a very powerful feature because it means you can perform XPath queries or do XSLT transformations directly on data received from a data source. You’ll see how to use this class in greater detail later in the chapter. The end result of the code in Listing 8.6 is a page that allows the end user to see what orders each customer has placed without having to leave the page. A screen shot of this is shown in Figure 8.1. The next sample (Listing 8.7) follows along the lines of the previous example, except that it uses one of the DataSet’s methods to access the DataSet as XML rather than creating an XmlDataDocument object. The resulting XML document is placed into an XML Data Island in the browser and queried on the client side using XPath.

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

315

FIGURE 8.1. Relating the Customers and Orders tables to create an ASP.NET page.

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18:

Viewing a DataSet as XML

public class SqlConnect { public DataSet ReturnDataSet(string dbConnectString,string table1, string table2,string key1, string key2) { DataSet dsTables = new DataSet(); SqlConnection dataConn = new SqlConnection(dbConnectString); SqlDataAdapter dsCmdCustomers = new SqlDataAdapter(table1,dataConn); SqlDataAdapter dsCmdOrders = new SqlDataAdapter(table2,dataConn); dsCmdCustomers.Fill(dsTables,”Table1”); dsCmdOrders.Fill(dsTables,”Table2”); dsTables.Relations.Add(“Relation1”, dsTables.Tables[“table1”].Columns[key1], dsTables.Tables[“table2”].Columns[key2]);

LEVERAGING ADO.NET’S XML FEATURES

LISTING 8.7

8

316

XML for ASP.NET Developers

LISTING 8.7 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64:

continued return(dsTables); }

} public void Page_Load(Object Src, EventArgs E) { string xmlString; string connStr = “server=localhost;uid=sa;pwd=;database=Northwind”; string sCustomers = “SELECT * FROM Customers WHERE CustomerID” + “ LIKE ‘f%’ ORDER BY ContactName”; string sOrders = “SELECT * FROM Orders WHERE CustomerID LIKE ‘f%’”; SqlConnect Sqlconn = new SqlConnect(); DataSet TablesDataSet = Sqlconn.ReturnDataSet(connStr,sCustomers, sOrders,”CustomerID”,”CustomerID”); xmlString = TablesDataSet.GetXml(); XmlContents.InnerHtml = xmlString; stats.InnerHtml = “XML Data” + “ Island Filled with DataSet Records”; xml.Text = xmlString; } function showXml() { var doc = document.all(“XmlContents”).XMLDocument; output = “

Starting to gather information on client-side..”; var node1 = doc.documentElement.selectNodes(“//Table1”); var node2 = doc.documentElement.selectNodes(“//Table2”); var stats = document.all(“stats”); output += “Information gathered! Totals follow:”; output += “Number of Customers: “ + node1.length; output += “Number of Orders: “ + node2.length; + “”; stats.innerHTML = stats.innerHTML + “” + output; }

XML Data: 66: 67:

This example shows another way that data within a DataSet can be viewed as XML. The SqlConnect class functions much the same as the SqlConnect class shown in Listing 8.6. After calling this class and getting a DataSet back, the DataSet’s GetXml() method is called and the resulting XML data is placed within an XML Data Island in the ASP.NET page. Calling the DataSet’s GetXml() method yields a string containing the XML schema and XML data retrieved from the Northwind database tables. Alternatively, if you want only the XML schema, you can call the GetXmlSchema() method.

FIGURE 8.2. Passing data within a DataSet to the browser as XML.

8 LEVERAGING ADO.NET’S XML FEATURES

After this data has been added to the ASP.NET page, client-side script takes care of executing a few XPath statements to determine the total number of customers and orders contained within the XML Data Island (lines 46 and 47). Doing this allows some of the processing burden to be removed from the server and placed on the client. Although the example is very simple, the client-side code could bind tables to the XML Data Island to allow records to be updated, deleted, or inserted. The data found within the XML Data Island could then be posted back to the server and the original data store (or another) could be updated. You’ll see how XML data can be read into a DataSet later in the chapter. Figure 8.2 shows the results that the code in Listing 8.7 returns.

318

XML for ASP.NET Developers

Loading DataSets with XML Aside from allowing relational or XML data views, the DataSet class can also be loaded with XML data. As an ASP.NET programmer, you should certainly appreciate this feature because it makes programming much simpler. For example, a DataSet can be loaded with data from an XML document and then bound to an ASP.NET DataGrid WebControl. Doing this simplifies development because the looping and manipulation of the data is taken care of for you by the WebControl. The capability to load DataSets with data marked up as XML also allows data coming in from a variety of applications or devices to be updated more easily into a data store. Loading XML data from an XML document or stream into a DataSet can be accomplished by using the DataSet’s ReadXml() method. This method has several overrides that allow a variety of arguments, including a string or a stream. Listing 8.8 instantiates a StreamReader class and passes it to the ReadXml() method. After the DataSet is filled with the data from the XML file, a DataView object is created from the DataSet and bound to a DataGrid WebControl. As an added feature, the DataGrid is set up to allow the end user to sort based on a particular field. LISTING 8.8

Binding a DataSet to a DataGrid

1: 2: 3: 4: public class DSReadXml { 5: public static DataSet ReturnDataSet(string path) { 6: DataSet dsTables = new DataSet(); 7: FileStream fs = null; 8: StreamReader reader = null; 9: try { 10: fs = new FileStream(path,FileMode.Open,FileAccess.Read); 11: reader = new StreamReader(fs); 12: dsTables.ReadXml(reader); 13: return dsTables; 14: } 15: finally { 16: fs.Close(); 17: reader.Close(); 18: } 19: } 20: } 21: public void Page_Load(Object Src, EventArgs E) { 22: BindIt(“CustomerID”); 23: }

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

LISTING 8.8

319

continued

The ReadXml() method reads in an XML document’s schema and data. Line 12 shows how the method can be used to read from a stream. To read in only the schema associated with an XML document, the ReadXmlSchema() method can be called when working with the DataSet class. The capability to dynamically create the structure of a DataSet class (including tables, relationships, and so on) based on an XML schema opens up a new set of possibilities for working with data in a disconnected manner.

8 LEVERAGING ADO.NET’S XML FEATURES

24: public void OrdersDataGrid_Sort(Object Src, 25: DataGridSortCommandEventArgs sort) { 26: BindIt(sort.SortExpression); 27: } 28: public void BindIt(string field) { 29: DataSet ds = DSReadXml.ReturnDataSet( 30: Server.MapPath(“customerList.xml”)); 31: DataView view = ds.Tables[0].DefaultView; 32: view.Sort = field; 33: OrdersDataGrid.DataSource = view; 34: OrdersDataGrid.DataBind(); 35: } 36: 37: 38: 39: 40: 55: 56: 57:

320

XML for ASP.NET Developers

Saving DataSets as XML can also write the data they contain along with the XML schema that describes their structure to a file for later use. This is accomplished by making a call to the WriteXml() or WriteXmlSchema() methods. Listing 8.9 shows how these methods can be used to write a DataSet’s XML data and schema information to a file. DataSets

LISTING 8.9 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38:

Writing a DataSet’s XML Data and Schema to a File

public class SqlConnect { public DataSet ReturnDataSet(string dbConnectString, string table1,string table2) { DataSet dsTables = new DataSet(); dsTables.DataSetName = “CustomersData”; SqlConnection dataConn = new SqlConnection(dbConnectString); SqlDataAdapter customersAdapter = new SqlDataAdapter(table1,dataConn); SqlDataAdapter ordersAdapter = new SqlDataAdapter(table2,dataConn); customersAdapter.Fill(dsTables,”Customers”); ordersAdapter.Fill(dsTables,”Orders”); dsTables.Relations.Add(“CustomerOrders”, dsTables.Tables[“Customers”].Columns[“CustomerId”], dsTables.Tables[“Orders”].Columns[“CustomerId”]); return(dsTables); } } public void Page_Load(Object Src, EventArgs E) { string sqlConnStr = “server=localhost;uid=sa;pwd=;” + “database=Northwind”; string sqlCustomers = “SELECT * FROM Customers”; string sqlOrders = “SELECT * FROM Orders”; SqlConnect sqlConnect = new SqlConnect(); DataSet ds = sqlConnect.ReturnDataSet(sqlConnStr, sqlCustomers,sqlOrders); //Save data and schema information to a file ds.WriteXml(Server.MapPath(“Listing8.10.xml”), XmlWriteMode.IgnoreSchema); ds.WriteXmlSchema(Server.MapPath(“Listing8.11.xsd”)); Response.Write(“DataSet XML data and schema information saved.”); }

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

321

Listing 8.10 shows the results of calling the WriteXml() method on the DataSet just created. LISTING 8.10

XML Data Generated by the DataSet’s WriteXml() Method

8 LEVERAGING ADO.NET’S XML FEATURES

1: 2: 3: 4: ALFKI 5: Alfreds Futterkiste 6: Maria Anders 7: Sales Representative 8: Obere Str. 57 9: Berlin 10: 12209 11: Germany 12: 030-0074321 13: 030-0076545 14: 15: 16: ANATR 17: Ana Trujillo Emparedados y helados 18: Ana Trujillo 19: Owner 20: Avda. de la Constitución 2222 21: México D.F. 22: 05021 23: Mexico 24: (5) 555-4729 25: (5) 555-3745 26: 27: 28: 29: 30: 31: 11076 32: BONAP 33: 4 34: 1998-05-06T07:00:00 35: 1998-06-03T07:00:00 36: 2 37: 38.28 38: Bon app’ 39: 12, rue des Bouchers 40: Marseille 41: 13008 42: France 43:

322

XML for ASP.NET Developers

LISTING 8.10

continued

44: 45: 11077 46: RATTC 47: 1 48: 1998-05-06T07:00:00 49: 1998-06-03T07:00:00 50: 2 51: 8.53 52: Rattlesnake Canyon Grocery 53: 2817 Milton Dr. 54: Albuquerque 55: NM 56: 87110 57: USA 58: 59: 60: 61: 62:

Listing 8.11 shows what a schema generated by calling the DataSet’s WriteXmlSchema() method looks like. This schema follows the standards found in the W3C schema specification discussed in Chapter 4, “Understanding DTDs and XML Schemas”. LISTING 8.11

XML Schema Generated by the DataSet’s WriteXmlSchema() Method

1: 2: 7: 8: 9: 10: 11: 12: 13: 15: 17: 63: 65: 67: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83:

Although the DataSet has many more features that haven’t been covered, you’ve been exposed to a few of the different ways it can be used to work with relational and XML data formats. The next section shows how the DataSet class can further be extended to work with XML data using DOM properties and methods.

Working with the DataSet and XmlDataDocument Classes Up to this point in the chapter, you’ve been exposed to how data contained within a DataSet can be accessed as XML data. You’ve also seen how XML data can be read into a DataSet and written out to a file. Although the DataSet methods that allow for this type of functionality are very useful, they don’t allow you to create or add new nodes into data using DOM properties and methods. To emulate this type of functionality, you could always load the XML from a DataSet into an perform the necessary manipulations, and then read the data back into the DataSet using its ReadXml() method. Although this would certainly work, there’s a more efficient way to manipulate data within a DataSet using DOM properties and methods normally associated with the XmlDocument. In addition, data found in a DataSet can be queried using XmlDocument,

Leveraging ADO.NET’s XML Features Using ASP.NET CHAPTER 8

325

XPath statements and can be transformed using XSLT. How is this accomplished? The answer lies with the XmlDataDocument class that you were briefly introduced to earlier. This class is designed to work hand-in-hand with the DataSet class to allow you to manipulate data using regular XML-style programming. It can be thought of as a DataSet-aware XmlDocument. Figure 8.3 shows the relationship between the DataSet and XmlDataDocument classes in the .NET framework. XSL/T, X-Path Validation, etc

Controls Designers Code-gen, etc

XmlDataDocument

DataSet Sync

8 XmlReader

Managed Provider

XmlTextReader XmlNodeReader

XmlTextReader XmlNodeReader

FIGURE 8.3. Passing data within a DataSet to the browser as XML.

The most important concept shown in Figure 8.3 is that changes made to a DataSet are automatically made in the corresponding XmlDataDocument as well. This automatic syncing between the classes gives you the choice of working with data as XML or as a standard relational view! However, syncing between the XmlDataDocument and DataSet classes may not be possible in cases where a node is added to the DOM tree that does not fit into a row found in the DataSet’s relational structure. For complete syncing to occur, nodes added into the DOM tree must match up with a row in the DataSet. To see the XmlDataDocument in action, Listing 8.12 contains an example that utilizes code shown earlier in Chapter 6. The code simply walks through the XML and displays it in the browser. LISTING 8.12 1: 2: 3: 4:

Using the XmlDataDocument Class

LEVERAGING ADO.NET’S XML FEATURES

XmlReader

326

XML for ASP.NET Developers

LISTING 8.12 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: } 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49:

continued

string output = “”; int indent = 1; public class SqlConnect { public DataSet ReturnDataSet(string dbConnectString,string table1, string table2,string key1,string key2) { DataSet dsTables = new DataSet(); SqlConnection dataConn = new SqlConnection(dbConnectString); SqlDataAdapter dsCmdCustomers = new SqlDataAdapter(table1,dataConn); SqlDataAdapter dsCmdOrders = new SqlDataAdapter(table2,dataConn); dsCmdCustomers.Fill(dsTables,”Table1”); dsCmdOrders.Fill(dsTables,”Table2”); dsTables.Relations.Add(“Relation1”, dsTables.Tables[“Table1”].Columns[key1], dsTables.Tables[“table2”].Columns[key2]); return dsTables; } public class WriteXmlText { private string m_Document = “”; string output = “”; int indent = 1; public string ParseDoc(XmlDataDocument document) { XmlNode oNode = document.DocumentElement; writeNodeName(oNode,0); XmlNodeList oNodeList = oNode.ChildNodes; for (int i=0;i

356

XML for ASP.NET Developers

You’ll notice that as HTTP queries become more complex, URL encoding them can be difficult to do by hand. Listing 9.1 shows how to make this process easier by using the ASP.NET Server object’s UrlEncode() method. It allows a regular SQL query to be entered and outputs either a URL-encoded string version of the query or executes the query and returns the resulting XML document. Using the same type of logic shown in this listing, you can automatically URL encode SQL queries in your ASP.NET pages. LISTING 9.1 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36:

SQL Query URL-Encoding Utility

void SubmitButton_Click(Object Src, EventArgs E) { String sql = sqlBox.Text; String root = txtRoot.Text; if (root.Length == 0) root = “root”; if (sql.Length > 0) { String encodedSql = Server.UrlEncode(sql); if (rdoChoice.SelectedIndex == 0) { lblErrors.Text = encodedSql; } else { lblErrors.Text = “”; Response.Redirect(@”http://localhost/northwind?sql=” + encodedSql + “&root=” + root); } } else { lblErrors.Text = “You did not enter a SQL query.”; } }

Root Name:

SQL Query:

SQL Server 2000, XML, and ASP.NET CHAPTER 9

LISTING 9.1

357

continued

37: 38: 40:

41: 43: 44: Return Encoded SQL 45: 46: Execute SQL Statement 47: 48:

49: 51: 52: 53:

Virtually any query can be executed using HTTP. For example, assume a particular application has a stored procedure named sp_GetXml, as shown next: CREATE (

PROCEDURE sp_GetXml @CustomerID varchar(5)

) AS

To execute this procedure and pass in the appropriate argument, the following HTTP query can be used: http://localhost/northwind?sql=exec+sp_GetXml+’A’&root=root

This same logic applies to more advanced stored procedures and allows for dynamic substitution of the argument values (“A” in this case), depending on the results that the end user wants to see. At this point you may be wondering why you would ever use an HTTP query to obtain XML data from a database located on SQL Server 2000? Because it returns XML data directly to the

9 SQL SERVER 2000, XML, AND ASP.NET

BEGIN SELECT CustomerID, CompanyName, ContactName FROM Customers WHERE CustomerID LIKE @CustomerID + ‘%’ FOR XML AUTO END

358

XML for ASP.NET Developers

browser, what good is it? Thinking back to Chapter 7, “Transforming XML with XSLT and ASP.NET,” you’ll remember that the XPathDocument class has several constructors that can be used to load an XML document. One of those constructors accepts a string specifying the path to the XML document. This presents an excellent opportunity to obtain an XML document directly from a SQL Server database. The next listing shows how data from SQL Server 2000 can be loaded directly into an class and then transformed into HTML using the XslTransform class. Listing 9.2 shows this process. XPathDocument

Listing 9.2

Loading XML Data Directly from SQL Server 2000 into the XPathDocument Class

void Page_Load(object sender, EventArgs e) { string sql = Server.UrlEncode(@”SELECT Customers.CustomerID, Customers.ContactName, Orders.OrderID, Orders.CustomerID FROM Customers INNER JOIN Orders ON Customers.CustomerID = Orders.CustomerID FOR XML AUTO”); string url = “http://localhost/northwind?sql=” + sql + ➥“&root=Northwind”; try { XPathDocument xmlDoc = new XPathDocument(url); XslTransform xslDoc = new XslTransform(); xslDoc.Load(Server.MapPath(“customers.xsl”)); xslDoc.Transform(xmlDoc,null,Response.Output); } catch (Exception exc) { Response.Write(exc.ToString()); } }

Listing 9.3 follows along the lines of the previous listing but shows how XML data from SQL Server 2000 can be loaded directly into a DataSet class using its ReadXml() method. LISTING 9.3

Loading XML Data Directly from SQL Server 2000 into the DataSet Class

1: 2: 3:

SQL Server 2000, XML, and ASP.NET CHAPTER 9

LISTING 9.3

continued

public void Page_Load(Object Src, EventArgs E) { string sql = Server.UrlEncode(@”SELECT Customers.CustomerID, Customers.ContactName, Orders.OrderID, Orders.CustomerID FROM Customers INNER JOIN Orders ON Customers.CustomerID = Orders.CustomerID WHERE Customers.CustomerID = ‘ALFKI’ FOR XML AUTO”); string schemaFile = Server.MapPath(“httpSelect.xsd”); DataSet ds = new DataSet(); //**** Load the Schema File and XML ds.ReadXmlSchema(schemaFile); ds.ReadXml(“http://localhost/northwind?sql=” + sql + “&root=Northwind”); //**** Add Two Rows to the DataSet DataRow row = ds.Tables[0].NewRow(); row[“CustomerID”] = “DLWID”; row[“ContactName”] = “Dan Wahlin”; DataRow row2 = ds.Tables[1].NewRow(); row2[“OrderID”] = “11000”; row2[“CustomerID”] = “DLWID”; ds.Tables[0].Rows.Add(row); ds.Tables[1].Rows.Add(row2); // Code to actually insert row goes here..... DataView view = new DataView(ds.Tables[0]); view.Sort = “CustomerID ASC”; Customers.DataSource = view; Customers.DataBind(); view.Table = ds.Tables[1]; Orders.DataSource = view; Orders.DataBind(); //Let’s look at the schema schemaDiv.InnerHtml = ds.GetXmlSchema(); }

9 SQL SERVER 2000, XML, AND ASP.NET

4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47:

359

360

XML for ASP.NET Developers

LISTING 9.3

continued

48: XML Data Loaded Directly from SQL Server 2000 into a DataSet 49: 62:

63: 76:

77: 78: 79: 80:

Lines 5–11 start things off by URL encoding a SQL statement that will be executed using an HTTP query. After this string is created, it is used to hit the database and generate XML data that is then loaded into the DataSet (lines 17 and 18). You’ll notice that an XSD schema is also loaded into the DataSet so that the data read from the database is structured correctly (line 16). Lines 21–30 take care of adding two new rows. One row is added to the Customers XML information (table[0]) and another row is added to the Orders XML information (table[1]). After this operation is complete, two DataViews are created based on the two tables and then bound to an ASP.NET DataGrid. Figure 9.4 shows what the code generates in the browser.

SQL Server 2000, XML, and ASP.NET CHAPTER 9

361

FIGURE 9.4 HTML generated by Listing 9.3.

The XML generated by this process is shown next:

The first thing that stands out is that the newly added Order row isn’t placed into the XML document as a child of the Customers element that it relates to (CustomerID=”DLWID”), as is the case with the other Orders elements. This is because the new Orders row was added to the Orders table (table[1]) and therefore has no relationship with the newly added Customers row. Although a relationship between the CustomerID attribute in the Customers element and the CustomerID attribute in the Orders element can be created using the DataRelation class along with the DataSet’s Relations property, there is another way to accomplish this task with the DataSet class. Looking back at Figure 9.4, you’ll see an interesting feature of the DataSet. Each bound table shows a Customers_id field that was not a part of the original SQL statement executed using

9 SQL SERVER 2000, XML, AND ASP.NET

362

XML for ASP.NET Developers

the HTTP query. Where did this mysterious field come from? Because the XML information for Orders is subordinate to the Customers XML information, the DataSet automatically added an identity field to help track which Orders are associated with which Customers. Looking at the second DataGrid on the page, you can see that several of the orders have the same Customers_id number. These different Orders elements show up under the same Customers element. However, the newly added Orders row doesn’t have any value in its Customers_id field. This is because the DataSet doesn’t know that it is related to a specific Customers element. To put the newly created Order row under the appropriate Customer element in the DataSet, the following line of code can be added after line 30 in Listing 9.3: ds.Tables[1].Rows[ds.Tables[1].Rows.Count-1][“Customers_id”] = ds.Tables[0].Rows[ds.Tables[0].Rows.Count-1][“Customers_id”];

This line of code makes the new Orders row a child element of the proper Customers element by relating their Customers_id fields. Adding this one line of code results in the following XML fragment:

You can see that the newly added Order is now a child element of the new Customer element because the DataSet now knows that the two elements are related. A more correct way to relate the newly added order to the customer is to associate the rows using the SetParentRow() method: ds.Tables[1].Rows[ds.Tables[1].Rows.Count-1].SetParentRow( ds.Tables[0].Rows[ds.Tables[0].Rows.Count-1])

Keep in mind that if nesting and relationships between tables wasn’t specified in advance, the SetParentRow() method would not do anything useful. Fortunately, the nesting was specified in the XML schema and in the structure of the XML data returned from SQL Server 2000 that was initially loaded into the DataSet. Because of this, the SetParentRow() method can be called when nesting among newly added rows needs to occur.

Using HTTP Queries to Return Elements and Schemas Thus far, all the examples involving HTTP queries have resulted in XML data being returned within attributes. What if you need some fields returned as elements instead? This can easily be accomplished by using a new keyword in SQL Server 2000 named ELEMENTS. To understand this keyword better, let’s take a look at a simple example that can be run directly in the browser: http://localhost/northwind?sql=SELECT+*+FROM+Customers+FOR+XML+AUTO%2c+ ELEMENTS&root=Northwind

SQL Server 2000, XML, and ASP.NET CHAPTER 9

363

This query results in the following XML fragment: ALFKI New Name Maria Anders Sales Representative Obere Str. 57 Berlin 12209 Germany 030-0074321 030-0076545

Use of the ELEMENTS keyword is restricted to cases where the FOR XML AUTO keywords are also used. Whenever data needs to be contained within elements rather than attributes, simply add FOR XML AUTO, ELEMENTS to the end of the SQL SELECT statement or stored procedure. The FOR XML AUTO keywords can also be followed by the XMLDATA and BINARY BASE64 keywords. The XMLDATA keyword instructs the database to return an inline XDR schema along with the XML data. The BINARY BASE64 keywords are used to BASE64 encode binary columns that would otherwise contain illegal characters. More details about working with binary data can be found in the SQL Server 2000 documentation.

The capability to query SQL Server 2000 directly through HTTP by embedding SQL directly into the query string is certainly a powerful and useful feature. However, it can represent a potential security risk even if the URL being used to query the database is embedded within a compiled ASP.NET page. After one end user learns about the capability to query the database directly using the browser, data within the database could be compromised. To allow for more secure HTTP-based queries, SQL Server 2000 introduces the concept of XML templates. These templates can be used in a manner similar to the HTTP queries shown earlier. In fact, templates can be embedded into the query string if desired, as shown next: http://localhost/northwind?template= SELECT+*+FROM+Customers+

9 SQL SERVER 2000, XML, AND ASP.NET

Querying SQL Server 2000 Through HTTP with XML Templates

364

XML for ASP.NET Developers

FOR+XML+AUTO

Querying the database in this manner still poses a potential security risk because an end user with knowledge of templates could use them on the query string to manipulate data in the database. And it’s obviously not the easiest way to write out a query. To combat the potential problem with security, SQL Server virtual directories (discussed earlier) can be configured to block HTTP URL queries. Instead, queries can be directed toward XML template files that contain the desired SQL query. Before discussing template specifics, let’s revisit the SQL Server virtual directory administration console discussed earlier. As a refresher, you can reach this tool by going to the Start, Programs, Microsoft SQL Server program group and selecting the Configure SQL XML Support in IIS option. Open up the computer hierarchy to reveal the default Web site. Click this, and in the right pane you’ll see the Northwind virtual directory created earlier in the chapter. Right-click this virtual, choose Properties, and then go to the Settings tab. The first check box, Allow URL Queries, should be checked. To prevent users from accessing the database through a URL query, uncheck the box. This will only allow SQL HTTP queries to be executed against the database that are XML templates, XPath queries, or form template posts. HTTP URL queries will be blocked completely. To allow XML templates to perform SQL queries, go to the Virtual Names tab and click the New button. Although the virtual name can be anything you like, the examples that follow will use a name of Templates. Enter this name, and in the drop-down box named Type, select Template. Next, either type in a path to where your XML templates will be stored or click the Browse button. A path of d:\inetpub\wwwroot\testbed\chapter9 was used for the examples that follow, although the path can point to anywhere you would like. After you have supplied all the necessary information, click the Save button. Now that a virtual has been mapped to a folder designated to hold XML query templates, let’s take a look at how to create a valid template that can be used to execute SQL queries. Listing 9.4 shows a sample template. It uses a namespace prefix of sql with a URI of urn:schemasmicrosoft-com:xml-sql. One of the elements is named query. It serves the rather obvious purpose of marking up SQL query statements located within the template file. LISTING 9.4

A Sample XML Template File

1: 2: 3: SELECT Customers.CustomerID, Customers.ContactName, 4: Orders.OrderID, Orders.CustomerID

SQL Server 2000, XML, and ASP.NET CHAPTER 9

LISTING 9.4

365

continued

5: FROM Customers 6: INNER JOIN Orders 7: ON Customers.CustomerID = Orders.CustomerID 8: FOR XML AUTO 9: 10:

After the template is saved to the proper directory, you can test it by going to the following URL: http://localhost/northwind/templates/listing9.4.xml

Breaking the URL down into individual pieces, you can see that the Northwind virtual root is first specified (case does not matter here). Within this virtual, the templates virtual name is then used. It maps to the physical templates directory that was configured earlier. Finally, the name of the template is specified (listing9.4.xml). Executing this template using a browser results in an XML document containing different Orders elements nested under Customers elements, as shown earlier in the chapter. Several advantages exist to using templates as compared to URL queries. First of all, an end user now has no control over changing the SQL statements. By removing access to SQL Server through URL queries, only an individual with write access to the template file can make changes. This prevents inserts, updates, or deletes from being performed in an unauthorized manner. Second, XML templates support the dynamic inclusion of parameters. This allows you to change the value of a SQL WHERE clause without having to make adjustments to the actual template file. Working with parameters is as simple as including an XML header element, as shown in Listing 9.5:

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12:

Specifying Parameters in an XML Template

A SELECT Customers.CustomerID, Customers.ContactName, Orders.OrderID, Orders.CustomerID FROM Customers INNER JOIN Orders ON Customers.CustomerID = Orders.CustomerID WHERE Customers.CustomerID LIKE @CustomerID + ‘%’ FOR XML AUTO

SQL SERVER 2000, XML, AND ASP.NET

LISTING 9.5

9

366

XML for ASP.NET Developers

LISTING 9.5 13: 14:

continued

Within the header element, a param element has been defined with a name attribute equal to CustomerID. This parameter is given a default value of A. You can use the parameter in the template just like you would in a stored procedure. Simply append the “@” character to the front of the parameter and then place it in within the SQL statement or stored procedure. For this example, the CustomerID parameter is used in the WHERE clause. If the parameter is set to “B”, the SQL statement will return all rows from the Customers and Orders tables with a CustomerID that starts with “B.” Calling this template and passing the correct CustomerID parameter value is as simple as adding the parameter name and value on the end of the query string, as shown next: http://localhost/northwind/templates/listing9.5.xml?CustomerID=B

NOTE Parameters used in XML templates are case sensitive just as XML is. If customerID was used as the parameter name on the query string instead of CustomerID, the default value of “A” would be used no matter what value was passed in.

Templates can also be used to execute stored procedures. Listing 9.6 shows an example of calling the sp_GetXml procedure shown earlier in the chapter: LISTING 9.6

Using an XML Template to Call a Stored Procedure

1: 2: 3: 4: 5: 6: EXEC sp_GetXml @CustomerID 7: 8:

Using templates to load an XPathDocument or DataSet class within an ASP.NET page is as simple as supplying the URL to the template file in the XmlPathDocument’s constructor or the DataSet’s ReadXml() method. Listing 9.7 shows the process of loading each of these classes with XML data obtained from SQL Server 2000 templates.

SQL Server 2000, XML, and ASP.NET CHAPTER 9

LISTING 9.7

Using XML Templates in ASP.NET

void Page_Load(object sender, EventArgs e) { if (!IsPostBack) { BindDropDown(); } } void SubmitButton_Click(object sender, EventArgs e) { string CustID = customers.SelectedItem.Value; string url = “http://localhost/northwind/templates/” + “listing9.5.xml?CustomerID=” + CustID; StringBuilder sb = new StringBuilder(); StringWriter sw = new StringWriter(sb); XmlTextWriter writer = new XmlTextWriter(sw); try { XPathDocument xmlDoc = new XPathDocument(url); XslTransform xslDoc = new XslTransform(); xslDoc.Load(Server.MapPath(“customers.xsl”)); xslDoc.Transform(xmlDoc,null,writer); transform.InnerHtml = sb.ToString(); } catch (Exception exc) { Response.Write(exc.ToString()); } } void BindDropDown() { string url = “http://localhost/northwind/” + “templates/getCustomerID.xml”; DataSet ds = new DataSet(); ds.ReadXml(url); customers.DataTextField = “CustomerID”; customers.DataSource = ds.Tables[0].DefaultView; customers.DataBind(); } Select a CustomerID to View:

9 SQL SERVER 2000, XML, AND ASP.NET

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44:

367

368

XML for ASP.NET Developers

LISTING 9.7

continued

45: 47:

48: 49: 50: 51:

This simple example doesn’t introduce anything new in the way of classes or methods. In fact, everything just shown was covered in Chapters 6–8. However, it does show different ways you can interact with data in SQL Server 2000 using ASP.NET.

Querying SQL Server 2000 Through HTTP Using Templates, XPath, and XDR Schemas Aside from containing SQL statements and parameters, SQL Server 2000 template files can also contain XPath queries. Why would you ever want to query the database using XPath when T-SQL can be used instead? The capability to use XPath can be beneficial in situations where individuals desiring to get XML data from the database have little or no T-SQL experience. Assuming they know how to use XPath queries, they can query the database and treat it like they would any other XML document. Using XPath also allows database tables and their associated fields to be treated as an XML document rather than as relational entities. Although many types of queries can be accomplished using XPath, SQL Server 2000 currently supports a subset of the W3C XPath specification. As such, the following limitations apply: • Root queries (/) are not supported. • Because document order is not determined when performing an XPath query in SQL Server 2000, axes using document order and predicates involving numeric values are not supported. The following axes are not currently supported: ancestor, ancestor-or-self, descendant, descendant-or-self (//), following, following-sibling, namespace, preceding, preceding-sibling. • The following string functions are not currently supported: string(), concat(), starts-with(), contains(), substring-before(), substring-after(), substring(), string-length(), normalize(), translate(). • The lang() Boolean function is not supported. • The following numeric functions are currently not supported: sum(), floor(), ceiling(), round().

SQL Server 2000, XML, and ASP.NET CHAPTER 9

369

Keep in mind that as different service packs and “Web Releases” are released, this information may change. To stay up to date with the different SQL Server 2000 XML features, visit http://msdn.microsoft.com/sqlserver.

SQL Server 2000 Schemas and Annotations Having seen the current limitations, let’s take a look at how you can use XPath queries to return XML information from a SQL Server 2000 database. First, an XPath statement must be used along with an XDR schema (XSD schema support was being released as this book went to print). Chapter 4, “Understanding DTDs and XML Schemas,” covers the specifics of XDR schemas. For an XDR schema to be used with XPath query in SQL Server 2000, it must contain specific schema annotations. These annotations allow tables and fields within a database to be mapped to attributes or elements. They also allow for additional pieces of functionality, including the establishment of relationships between tables. Table 9.1 shows the available SQL Server 2000 XDR schema annotations. TABLE 9.1

Annotations to XDR Schemas

Description

sql:field

Used to map elements or attributes to specific fields within a table. Used in mapping a particular element or attribute to a database table or view. This annotation is very useful when a table name such as Order Details needs to be mapped to an XML element. Because Order Details is not valid in XML because of the space, a different name can be assigned to the XML element that relates to the Order Details table. When specified on an element, the scope of the annotation applies to all attributes and child elements. Used on elements that do not map to a specific table or field. The annotation value can be a Boolean. Uses of this annotation include specifying top-level nodes in an XML document or container nodes. XML items with this annotation will show in the output. Specifies that the element or attribute is the primary key that uniquely identifies a row in a table. Used to create a valid XML ID, IDREF, or IDREFS attribute type. Because these types must start with an alphabetic character or underscore character, a valid prefix is specified that will be used to start the ID, IDREF, or IDREFS type attribute.

sql:relation

sql:is-constant

sql:key-fields sql:id-prefix

9 SQL SERVER 2000, XML, AND ASP.NET

Annotation

370

XML for ASP.NET Developers

TABLE 9.1

continued

Annotation

Description

sql:target-namespace

Places elements and attributes normally in the default namespace into a different namespace for query results. Used to establish relationships between different XML elements. The key, key-relation, foreign-key and foreignrelation attributes are used to establish the relationship. Specifies that an element is a CDATA type. Used to specify that an element or attribute’s value should be URL encoded. This is normally used with BLOB fields. Specifies the database field that contains overflow data. Allows fields to be filtered based on specific values.

sql:relationship

sql:use-cdata sql:url-encode sql:overflow-field sql:limit-field limit-value

and sql:

Without the schema and associated SQL Server annotations, it would be very difficult to match up the tables and fields within a database to different elements and attributes within an XML document. How could an XPath statement possibly return results from the database if it had no idea what fields to look for when an attribute or element is used in an XPath query? The obvious answer is that XPath queries cannot access the database on their own. They must be used with schemas to identify the structure of the data within the database. The best way to learn about using the annotations within a schema is to see an example of them in action. Listing 9.8 contains a modified version of the XDR schema used in the SQL Server 2000 documentation. It can be used to query the Northwind database using XPath. LISTING 9.8

Northwind Mapping Schema

1: 2: 5: 6: 7: 8: 9: 10: 11: 12: 13:

SQL Server 2000, XML, and ASP.NET CHAPTER 9

LISTING 9.8

continued

63: 64: 65: 66: 68: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 82: 83: 84: 86: 87: 88: 88: 89: 90: 91: 92: 93: 94:

The first thing you’ll notice when looking at Listing 9.8 is that it follows the XDR specification by declaring element and attribute types. These declarations are used to define the structure of data within the database. The schema annotations are integrated directly into the schema as attributes (except in the case of the relationship element, which is discussed later). Each annotation is associated with the sql namespace prefix. The URI for this

SQL Server 2000, XML, and ASP.NET CHAPTER 9

373

namespace references urn:schemas-microsoft-com:xml-sql. This URI must be used exactly as shown for the annotations to work properly with SQL Server 2000. Line 6 contains the first annotation (sql:relation), which is used to specify that the Customer element and its attributes reference the Customers table. Alternatively, each attribute could have used the sql:field annotation to specify what field they are associated with. However, because all the attribute names correspond to a field in the Customers table, this is unnecessary. In cases where element or attribute names differ from the actual field name, the sql:field annotation can be used as follows:

Line 12 contains an attribute declaration named Orders that has an IDREFS data type. To ensure that the data returned from the database follows the IDREFS naming restrictions, the sql:id-prefix annotation is used. This dynamically adds the value “Ord-” to each referenced IDREF value. Lines 20–24 contain the only element annotation that SQL Server 2000 uses. This annotation, named relationship, is used to specify which IDREF values should be added as values for the Orders attribute. It automatically associates each order a customer places with the appropriate OrderID by using the key-relation, key, foreign-relation, and foreign-key attributes. The key-relation attribute specifies the primary relation table; Customers, in this example. The key attribute then locates the primary key within this table (CustomerID). These two attributes are followed by the foreign-relation attribute, which references the foreign relation table (Orders). The foreign-key attribute then identifies the primary key within this table (CustomerID). The end result of using these various annotations on the Orders attribute is a list of IDREF values each prefixed with “Ord-.”

Although Listing 9.8 does not show how to use each annotation listed in Table 9.1, it gives you a good feel for how annotations can be used to map database table fields to XML items and create relationships among different tables. For more information on the annotations that were not covered, refer to the SQL Server 2000 documentation. After a schema is created and annotations are added, it can be saved in two ways. First, it can be saved in the same folder as the XML template files were saved. Doing this allows templates to reference the schema based on its relative path. This process will be discussed in a moment. Second, the schema can be saved in a folder specially designed to hold schemas. Referring back to our discussion on setting up the Northwind SQL Server virtual directory earlier in the

9 SQL SERVER 2000, XML, AND ASP.NET

Jumping to line 58 in Listing 9.8, another annotation named key-fields is used to identify what UnitPrice and Quantity fields should be pulled from the Order Details table. The key-fields annotation specifies that the OrderID and ProductID fields are used to uniquely identify a given row in the table.

374

XML for ASP.NET Developers

chapter, you’ll remember that when XML templates needed to be used, a special folder was configured for this purpose. This was done by going to the Virtual Settings tab of the virtual directory’s properties sheet. Following the same steps outlined earlier, a schema folder can be created by clicking the Add button on the Virtual Settings tab, giving the folder to hold schemas a virtual name (“Schemas” is always a good name), selecting schema from the dropdown box, and then specifying the physical path to the schemas folder. Note that a schema virtual name can also point to a particular schema file. Pointing to a file can hide the fact that the returned data is actually coming from a database. Schemas present an excellent opportunity to define custom XML structures that can then be returned from the database using XPath queries. Although an alternative to creating complex XML document structures exists in the form of EXPLICIT mode queries (discussed later), schemas present a straightforward way of creating XML structures that fit a specific mold used by ASP.NET applications. To see how this works, let’s take a look at how XPath queries can use schemas to return XML documents.

Using XPath Queries and Schemas in a URL After a schema directory has been successfully configured, the following URL can be executed in the browser. It leverages the schema shown in Listing 9.8 along with an XPath statement to return XML data: http://localhost/northwind/schemas/listing9.8.xdr/Customer [@CustomerID=’ALFKI’]/Order?root=Northwind

This XPath query results in the following XML document being returned: 0.25 0.25 0.25

SQL Server 2000, XML, and ASP.NET CHAPTER 9

375

The first thing you’ll notice is that the XPath query immediately follows the schema filename in the URL (listing9.8.xdr). The XPath query finds all Order elements that have a parent element named Customer with a CustomerID attribute equal to ALFKI. It should be noted that the query is case sensitive. Typing /customer[@customerID=’ALFKI’]/Order will result in an error being returned because the case of the element and attribute being named does not match the case specified in the schema. It’s also important to note that a root element name must be supplied after the XPath query, as shown, for a well-formed XML document to be returned. Turning off URL querying capability (through the virtual directory’s Settings tab) will not affect XPath queries, because they are treated separately. In cases where querying the database through the use of XPath queries is undesirable, an administrator can disable them by unchecking the Allow XPath option on the Settings tab of the appropriate virtual directory’s property sheet. Any attempts to use them after they have been disabled will result in the following error condition: ERROR: 400.100 Bad Request HResult: 0x80004005 Source: Microsoft SQL isapi extension Description: XPath queries are not allowed.

Although useful, querying via XPath queries embedded in a URL can be problematic because of URL-encoding issues. The next section demonstrates how to embed XPath queries directly into XML template files.

Using XPath Queries, Schemas, and Templates

LISTING 9.9

Embedding an XPath Query into an XML Template

1: 2: 3: /Customer[@CustomerID=’ALFKI’]/Order 4: 5:

Like the SQL queries embedded in XML template files earlier in the chapter, XPath queries use the urn:schemas-microsoft-com:xml-sql URI along with the sql prefix to identify custom elements and attributes used in the template. For XPath queries, an element named xpath-query is used to mark up the query syntax. This element also has an attribute named

9 SQL SERVER 2000, XML, AND ASP.NET

Like SQL queries, XPath queries can also be embedded within an XML template file. Listing 9.9 exhibits a simple XML template containing an XPath query. This query uses the schema shown in Listing 9.8 to return all orders placed by a customer with a CustomerID equal to ALFKI.

376

XML for ASP.NET Developers

mapping-schema that is used to identify the path to the appropriate schema file (listing9.8.xdr in this case) used to map tables and fields to specific XML items.

Listing 9.10 shows another template file that uses a more complex XPath query. LISTING 9.10

Embedding an XPath Query into an XML Template

1: 2: 3: /Customer[@CustomerID=’ALFKI’]/Order/Employee[@LastName=’Suyama’] 4: 5:

When executed, the XPath query returns which employee was involved with handling a specific order placed by a customer, as shown next:

XPath queries used within template files can also accept parameters. This process functions in a manner similar to parameters used in XSLT style sheets. Like XSLT, the $ character is used to designate a variable. Listing 9.11 shows how to incorporate variables into templates containing XPath queries. LISTING 9.11

Using Parameters with XPath Query Templates

1: 2: 3: 4: 5: 6: /Customer/Order[@OrderID=$ID] 7: 8:

Passing a parameter to the template can be accomplished by passing the parameter name along with its associated value in the URL as shown next: http://localhost/northwind/templates/listing9.11.xml?ID=ORD-10643

As was shown earlier in the chapter, passing the preceding URL to the XPathDocument class constructor (or the Load() method of an XmlDocument class) or to the ReadXml() method of the DataSet class results in ASP.NET pages that access XML data directly. For an example of doing this, please refer back to Listing 9.7.

SQL Server 2000, XML, and ASP.NET CHAPTER 9

Using

EXPLICIT

377

Mode Queries

Schemas present an excellent way to customize and mold the structure of XML data returned from SQL Server 2000. By mapping specific database tables and fields to different XML elements and attributes, virtually any structure can be created. However, using schemas requires that the schema annotations be included for the mapping to work correctly. For individuals who do not feel comfortable writing XDR schemas or using the SQL Server 2000 schema annotations, there is another alternative to creating a custom XML structure. This alternative comes in the form of EXPLICIT mode queries. Although they can be more complex than writing XDR schemas, EXPLICIT mode queries provide a lot of power for shaping XML documents in a custom fashion. In general, EXPLICIT mode queries also offer better performance as compared to XPath queries, especially because they can be included within stored procedures. EXPLICIT mode queries are best understood by thinking in terms of hierarchical relationships among XML elements. Figure 9.5 shows how EXPLICIT mode queries would classify the following XML document’s structure:

Northwind Parent = Null, Tag = 1

Order Parent = 2, Tag = 3

OrderDetails Parent = 3, Tag = 4

FIGURE 9.5 Understanding EXPLICIT mode query hierarchies.

As you can see, EXPLICIT mode queries assign a tag number and a parent value to every XML element within a document. This allows relationships between elements to be established and

9 SQL SERVER 2000, XML, AND ASP.NET

Customer Parent = 1, Tag = 2

378

XML for ASP.NET Developers

XML structures to be created based on these relationships. For example, the OrderDetails element in Figure 9.5 has a tag number of 4 because it’s the fourth tag listed in the document. When doing a query against the database, this element can be nested as a child of the Order element by identifying that its parent tag number is 3. Had the application required the OrderDetails tag to be a child element of the Customer element, a parent tag number of 2 could have been identified. Now that you have a feel for how EXPLICIT mode queries use tag numbers to create hierarchical XML document structures, Listing 9.12 demonstrates a query that returns the following XML document:

LISTING 9.12 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18:

EXPLICIT Mode Query Example

SELECT

1 as Tag, NULL as Parent, Customers.CustomerID as [MyCustomer!1!CustID], NULL as [MyCustomerOrder!2!OrdID] FROM Customers WHERE Customers.CustomerID=’ALFKI’ UNION ALL SELECT

2, 1, Customers.CustomerID, Orders.OrderID FROM Customers, Orders WHERE Customers.CustomerID = Orders.CustomerID AND Customers.CustomerID = ‘ALFKI’ ORDER BY [MyCustomer!1!CustID], [MyCustomerOrder!2!OrdID] FOR XML EXPLICIT

At first glance, this SQL query may look rather strange. After all, it uses ! characters and strangely named field aliases. However, when you break the query down into small pieces, the purpose and reason for the oddities become more clear and understandable.

SQL Server 2000, XML, and ASP.NET CHAPTER 9

379

Let’s first examine lines 1 through 6, which are used to build the MyCustomer element. If you’ve worked with SQL much, you’ll recognize this as a fairly simple SELECT query, except that it has a few odd characters mixed in it. This first SELECT query serves the purpose of defining all elements and attributes that will be returned in the XML document. Lines 1 and 2 create two metadata fields named Tag and Parent. These fields are used to track node position and hierarchical relationships, as shown earlier in Figure 9.5. Because the MyCustomer element appears first in the XML document, it has a parent value of null. This is because it is the root of the tree and therefore has no parent. The tag number for the MyCustomer element is given a value of 1 because it is the first element tag in the XML document. Line 3 then selects the CustomerID field from the Customers table and assigns it a special alias that contains three pieces of information, all separated by the ! character. This alias is based on a special format recognized by SQL Server 2000: ElementName!TagNumber!AttributeName!Directive

The first part of the alias is the name of the element that the field will be associated with. In this case, it gets associated with the MyCustomer element. The second piece of information is the tag number of the element it will be associated with, which is 1. The third piece of information is the name of the attribute that will show in the XML document. In this example, CustID is specified as the attribute name. It’s important to realize that all field aliases are designed to be attributes by default. To change them to elements, the element directive must be specified in the Directive section of the alias. We’ll discuss directives a little later in the chapter.

Line 8 tells the query to perform a Union operation by using the UNION ALL SQL keywords. Union operators serve the purpose of combining all fields from two or more SQL SELECT statements into one. For this operation to work correctly, each of the SELECT statements involved in the union must contain the same number of fields. These fields must also be named the same

9 SQL SERVER 2000, XML, AND ASP.NET

Line 4 goes through the same process as outlined previously. It selects NULL and gives it a special alias. First it assigns the field to the MyCustomerOrders element, which has a tag value of 2 because it is the second element tag in the XML document. Next, it gives the attribute a name of OrdID. Why is this field being created in the resultset when it is assigned a NULL value? A little earlier it was mentioned that this first SELECT statement contains all the elements and attributes that will be returned in the XML document. Because the OrderID field’s value will be returned, a place for it must be reserved initially for a union operation to occur (discussed later). This is accomplished by defining that there will be an XML attribute named OrdID but that the attribute doesn’t have a value yet (it is NULL). This will become more clear as you look at the second SELECT statement in Listing 9.12. After the four fields are defined, the final part of the SELECT statement is shown in line 6. This SQL code simply ensures that only the customer associated with the unique CustomerID field will be returned.

380

XML for ASP.NET Developers

and must appear in the same order in every SELECT statement. To better understand how a union operation works, Figure 9.6 provides a graphical representation. SELECT 1

SELECT 2

ID

Name

ID

Name

123

NULL

234

Dan

UNION

ID

Name

123

NULL

234

Dan

FIGURE 9.6. Graphical representation of a Union operation involving two SELECT statements.

As shown, the Union operation simply combines the two SELECT statements. This is possible because the fields are named the same and appear in the same order. Getting back to Listing 9.12, the UNION ALL statement combines the first SELECT statement with the one that follows. The first SELECT statement begins the process of building the MyCustomers element (tag 1). Because of the aliases assigned to each field in this first statement, you can see that the CustID attribute is the only one that should be associated with the MyCustomers element. Although the OrdID attribute is also listed, remember that it isn’t associated with tag 1. Its association is with tag 2 as shown in its alias. The second SELECT statement begins the process of building the MyCustomerOrders element (tag 2). This element contains the OrdID attribute. We know from the first SELECT statement that OrdID is associated with tag 2. Although the CustomerID field is listed in this second select statement (line 12), it is not included as an attribute of the MyCustomerOrders element because its alias points to tag 1 (the MyCustomer element). It is listed to allow the union operation to combine the two SELECT statements as mentioned earlier. Any value can actually be put in for the CustomerID value in this second statement as long as the value can be converted to the proper data type defined for the CustomerID field (nvarchar in this case). Line 17 finishes off the SQL statement by determining how to order the results, and line 18 uses the magical FOR XML EXPLICIT keywords. These keywords are necessary for XML to be

SQL Server 2000, XML, and ASP.NET CHAPTER 9

381

returned from the database in the structure specified by the two SELECT statements. By using the EXPLICIT keyword, you are telling the database to evaluate the values of the Tag and Parent metadata fields to organize the resulting XML document’s structure. Table 9.2 shows all the fields and their respective values after the two SELECT statements have been executed and combined using the UNION All syntax. TABLE 9.2

Result of the Union Operation

Tag

Parent

MyCustomer!1!CustID

MyCustomerOrder!2!OrdID

1 2 2 2 2 2 2

NULL 1 1 1 1 1 1

ALFKI ALFKI ALFKI ALFKI ALFKI ALFKI ALFKI

NULL 10643 10692 10702 10835 10952 11011

Using Directives in EXPLICIT Mode Queries Now that the code shown in Listing 9.12 has been described in detail, let’s take a look at some more advanced capabilities of EXPLICIT mode queries. Directives are the last item that can be specified when defining a field’s alias (ElementName!TagNumber!AttributeName!Directive). Table 9.3 contains a list of the possible directive statements. TABLE 9.3

SQL Server 2000 EXPLICT Mode Query Directives

Description

ID

Used to represent an attribute ID type. This can be used with IDREF and IDREFS to build relationships. This directive is useful only when FOR XML EXPLICIT, XMLDATA is specified in the query. Used to represent an attribute IDREF type. This can be used with IDREF and IDREFS to build relationships. This directive is useful only when FOR XML EXPLICIT, XMLDATA is specified in the query. Used to represent an attribute IDREFS type. This can be used with IDREF and IDREFS to build relationships. This directive is useful only when FOR XML EXPLICIT, XMLDATA is specified in the query. This attribute is not displayed when the hide directive is specified. This is useful when you need to order the results by an attribute that you do not want to appear in the XML document.

IDREF

IDREFS

hide

SQL SERVER 2000, XML, AND ASP.NET

Directive

9

382

XML for ASP.NET Developers

TABLE 9.3

SQL Server 2000 EXPLICT Mode Query Directives

Directive

Description

element

Use of this directive results in a contained element as opposed to an attribute. Any entity characters found within the data (such as < or >) will automatically be encoded. This directive functions the same as an element directive, except that characters that are normally encoded (such as < or >) will be left intact. This cannot be used with any other directive except for hide. This directive is used to store overflow XML data stored in a field by OPENXML (discussed later). This directive wraps data in a CDATA section. It can be used only with the hide directive and the AttributeName must not be specified.

xml

xmltext cdata

The directives listed previously can be used to gain more control over what type of content is returned by SQL Server 2000. Listing 9.13 builds on the previous query by using ID, IDREF, element, and cdata directives to build a more detailed XML document structure. The entire SQL statement is embedded within an XML template file. LISTING 9.13

Using Directives in EXPLICIT Mode Queries in XML Templates

1: 2: 3: SELECT 1 as Tag, 4: NULL as Parent, 5: C.CustomerID as [Customer!1!cid], 6: C.ContactName as [Customer!1!name], 7: NULL as [Order!2!id], 8: NULL as [Order!2!date], 9: NULL as [Order!2!RepID], 10: NULL as [OrderDetails!3!id!id], 11: NULL as [OrderDetails!3!pid!idref], 12: NULL as [OrderDetails!3!total!element] 13: FROM Customers C 14: WHERE C.CustomerID = ‘ALFKI’ 15: UNION ALL 16: SELECT 2 as Tag, 17: 1 as Parent, 18: C.CustomerID, 19: NULL, 20: O.OrderID, 21: O.OrderDate, 22: O.EmployeeID,

SQL Server 2000, XML, and ASP.NET CHAPTER 9

LISTING 9.13 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49:

383

continued NULL, NULL, NULL FROM Customers C INNER JOIN Orders O ON O.CustomerID = C.CustomerID AND C.CustomerID = ‘ALFKI’ UNION ALL SELECT 3 as Tag, 2 as Parent, C.CustomerID, NULL, O.OrderID, NULL, NULL, OD.OrderID, OD.ProductID, (‘$’ + CAST(((OD.UnitPrice - OD.Discount) * OD.Quantity) as varchar(10))) FROM Customers C INNER JOIN Orders O ON O.CustomerID = C.CustomerID INNER JOIN [Order Details] OD ON OD.OrderID = O.OrderID AND C.CustomerID = ‘ALFKI’

ORDER BY [Customer!1!cid], [Order!2!id] FOR XML EXPLICIT, XMLDATA

Executing the query in Listing 9.13 results in the following XML document (only part of the document is shown). It’s interesting to note that the inline schema doesn’t fully define the structure of the XML document. Looking at the schema contents, you can see that the ElementType named Customer does not include the Order and OrderDetails ElementTypes. It’s clear that the schema is based on the three distinct SELECT statements included in EXPLICIT mode query rather than the XML that is generated.

9 SQL SERVER 2000, XML, AND ASP.NET

The concepts used to build this query are the same as those discussed in Listing 9.12. However, this query uses directives in lines 10 and 11 to specify that the attributes are ID and IDREF types, respectively. To ensure that these tags are used properly in the XML document, the FOR XML EXPLICIT keywords are followed by another keyword named XMLDATA. This tells SQL Server to place an inline schema in the resulting XML document. Line 12 uses the element directive to place the result of (UnitPrice-Discount)*Quantity into an element named total. This query also adds one more hierarchical level of tags by going out to tag number 3.

384

XML for ASP.NET Developers

$680.25 $372.75 $23.5

You can obtain these XML results by navigating to the following URL: http://localhost/northwind/templates/listing9.13.xml

SQL Server 2000, XML, and ASP.NET CHAPTER 9

385

Using OPENXML to Manipulate XML SQL Server 2000’s OPENXML is a rowset provider that allows XML documents placed in memory to be treated as rowset data. This feature can be very useful when you would like to send an XML document in as a parameter to a SQL statement or stored procedure and then insert the data found in the document into the appropriate relational tables. The process of taking information from the XML document and placing it into relational database tables is referred to as “shredding XML into tables.” To provide rowset functionality, the XML document must first be parsed using a specific system stored procedure named sp_xml_preparedocument. This procedure takes a single input parameter (the source XML document) and returns a single output parameter representing a handle to the parsed XML document. After parsing has completed, queries can be executed against the XML document using normal SQL and XPath statements. This allows data to be selected from the document and then inserted into a database table. After processing has completed on the XML document, another system stored procedure named sp_xml_removedocument must be called to remove the document from memory. This procedure accepts a single input parameter, which is the handle of the XML document originally generated by the sp_xml_preparedocument procedure. Listing 9.14 shows an example of using the OPENXML rowset functionality to select values from an existing XML document. As outlined previously, the document is loaded into memory and parsed. On completing the parsing operation, data is extracted and formatted into a rowset. Finally, the memory allocated to hold the XML document is released. LISTING 9.14

Using OPENXML to Shred an XML Document

9 SQL SERVER 2000, XML, AND ASP.NET

1: DECLARE @docID int 2: DECLARE @XmlDoc varchar(2000) 3: SET @XmlDoc =’ 4: 5: 6: 8: 9: 10: 11: 12: 13: 15: 16:

386

XML for ASP.NET Developers

LISTING 9.14 17: 18: 19: 20: 21: 22: 23: 24: 25: 26:

continued

’ EXEC sp_xml_preparedocument @docID OUTPUT, @XmlDoc SELECT * FROM OPENXML (@docID, ‘/ROOT/Customer’,1) WITH (CustomerID varchar(10), ContactName varchar(20), OrderDate DateTime ‘./Order/@OrderDate’, ProductID int ‘./Order/OrderDetail/@ProductID’) EXEC sp_xml_removedocument @docID

This query can be executed by placing it into SQL Query Analyzer or a similar tool. Doing so returns the following results: CustomerID

ContactName

OrderDate

ProductID

DLWID JJDID

Dan Wahlin John Doe

2000-09-09 00:00:00.000 2000-09-04 00:00:00.000

11 72

Let’s break Listing 9.14 into pieces to better understand how OPENXML works. After defining variables in lines 1 and 2, the XML document that will be parsed is loaded into the XmlDoc variable. Line 19 makes a call to the sp_xml_preparedocument stored procedure, which loads the XML document into memory and parses it. Next, a SELECT statement is created that uses OPENXML to query the XML data. The handle to the XML document (@docID) is passed in along with an XPath statement that identifies the nodes that will be converted to a rowset. Finally, a flag is passed in to specify that the data for the fields in the rowset will be found in attributes within the XML document. Table 9.4 shows the possible flag values. TABLE 9.4

OPENXML Flag Values

Value

Description

0 1

Defaults to attribute-centric mapping. This flag specifies attribute-centric mapping. It can also be used with XML_ ELEMENTS, which will apply attribute-centric mapping first followed by elementcentric mapping for columns that have not been dealt with yet. This flag specifies element-centric mapping. It can also be used with XML_ELEMENTS, which will apply element-centric mapping first followed by attribute-centric mapping for columns that have not been dealt with yet. This flag allows XML_ATTRIBUTES or XML_ELEMENTS.

2

8

SQL Server 2000, XML, and ASP.NET CHAPTER 9

387

Lines 22–25 create the schema declaration that is used to map attributes located within @XmlDoc to fields that will be found in the rowset. This SQL code dictates that four fields will be contained within the rowset. This is accomplished by listing the field name, data type, and location within the XML document (an XPath statement). After these fields are configured and the rowset is generated, the handle to @XmlDoc (named @docID) is passed to the sp_xml_removedocument stored procedure to remove the XML document from memory. is most useful when you need to insert data located within an XML document into relational tables. Listing 9.15 builds on the previous listing by allowing multiple inserts to occur. OPENXML

LISTING 9.15

SQL Code for Inserting XML Data into Tables Using OPENXML

The SQL code shown in Listing 9.15 performs the simple function of inserting the CustomerID, ContactName, and Address information found in the XML document into the Customers table in the Northwind database. This process is kicked off by an ASP.NET page that presents the user with a form containing three fields. Upon submitting the form, the ASP.NET page processes the values entered in the form fields and creates an XML document. This document is then passed as a parameter to the template shown in Listing 9.15. The XML result returned from the template is loaded into an XmlDocument class and then written out to the page. Listing 9.16 shows the ASP.NET page.

9 SQL SERVER 2000, XML, AND ASP.NET

1: 2: 3: 4: 5: 6: 7: DECLARE @docID int 8: EXEC sp_xml_preparedocument @docID OUTPUT, @XmlDoc 9: INSERT INTO Customers 10: SELECT * 11: FROM OPENXML(@docID, ‘//Customers’) 12: WITH Customers 13: IF @@ERROR > 0 14: SELECT ‘Error’ 15: ELSE 16: SELECT ‘Success’ 17: EXEC sp_xml_removedocument @docID 18: 19: 20:

388

XML for ASP.NET Developers

LISTING 9.16 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42:

ASP.NET Page Used to Send Information to the XML Template

void SubmitButton_Click(Object sender, EventArgs e) { Response.ContentType = “text/xml”; string xmlDoc = “”; string url = “http://localhost/northwind/templates/” + “listing9.15.xml?XmlDoc=” + Server.UrlEncode(xmlDoc); XmlDocument doc = new XmlDocument(); doc.Load(url); Response.Write(doc.DocumentElement.OuterXml); Response.End(); }

SQL Server 2000, XML, and ASP.NET CHAPTER 9

LISTING 9.16

389

continued

43: 47: 48: 49: 53: 54:

CustomerID:
Name:
Company Name:	44: 46:
50: 52:

55: 56: 57:

XML Updategrams—Update, Insert, and Delete Database Records with XML Using ASP.NET Up to this point in the chapter, you’ve seen several ways to select data from SQL Server 2000. These range from URL queries to templates to templates with embedded XPath statements. You have also seen how data within an XML document can be inserted into the database using OPENXML. Although you can perform updates, inserts, or deletes using XML template files or URL queries, SQL Server 2000 also allows this type of functionality to be performed by using Updategrams. At the time this section was written, Updategrams were in their first Web release. As such, the information that follows may change in future releases.

LISTING 9.17 1: 2:

Updategram Structure

9 SQL SERVER 2000, XML, AND ASP.NET

work by presenting a before and after view of data that is marked up using XML syntax. If data in the before view is different from the data in the after view, an update is performed to the appropriate fields. For example, if the before view of a record shows a value of Paul Allsing for the ContactName field, but the after view shows a value of Lance Edwards, the Updategram will know that the ContactName field needs to be updated because the values have changed. If the before view contains data, but the after view is empty, the appropriate row will then be deleted. To understand this more fully, let’s take a look at how Updategrams are structured in Listing 9.17. Updategrams

390

XML for ASP.NET Developers

LISTING 9.17

continued

3: 4: 5: 6: 7: 9: 10: 11:

The first thing you should notice is that Updategrams look a lot like the XML templates discussed earlier in the chapter. They start with a root element tag and are followed by a namespace declaration (line 1). However, instead of using the sql prefix, Updategrams use the updg prefix and tie it to a URI of urn:schemas-microsoft-com:xml-updategram. Line 2 introduces a new element tag named sync, which acts a container for the before and after views of the data being evaluated. The sync block defines the boundaries for transactions. If any statements within the sync block fail, the transaction will be rolled back. The before and after data views are enclosed within the sync block using the before and after element tags (lines 3–9). The table within the database that will be changed is used as the element name in both the before and after data views (lines 4 and 7). The table name element is followed by attributes that list the columns (and their respective values) that will be used to determine whether an insert, update, or delete operation should be performed. The table name may also be followed by an id attribute in the case of before views and an id and/or at-identity attribute in after views. The id attribute can be used to identify elements within the before and after data view sections in cases where more than one insert, update, or delete is being performed in the Updategram. By manually specifying a unique id for each element, the elements within the before and after data sections will be matched up properly. The at-identity attribute can be used along with an attribute named returnid to return the identity of a newly inserted record. Using this attribute is similar to calling @@Identity in a stored procedure following the insertion of a new row. Performing an insert, update, or delete to a database table using Updategrams is as simple as providing the proper information to the before and after data sections. Table 9.5 gives an overview of how to accomplish each operation using Updategrams. Let’s take a look at performing an insert, update, and delete to the Customers table of the database. Listings 9.18, 9.19, and 9.20 show each operation.

Northwind

SQL Server 2000, XML, and ASP.NET CHAPTER 9

TABLE 9.5

391

Performing Inserts, Updates, or Deletes Using Updategrams

Operation

Before and After Section Status

Insert

The before view is empty, whereas the after view contains the name of the table to insert into along with the appropriate columns to be inserted. Because no data exists initially, SQL Server 2000 knows to perform an insert. The before view contains the initial data (only the primary key for the row is absolutely necessary). The after view contains the columns to be updated. The before view contains the initial data (only the primary key for the row is absolutely necessary). The after view is left empty. Because the after view is empty, SQL Server 2000 knows to delete the row.

Update Delete

LISTING 9.18

Performing an Insert Using Updategrams

1: 2: 3: 4: 5: 6: 7: 8: 9:

Hitting the URL for the template shown in Listing 9.18 results in an insert being performed into the Customers table of the Northwind database because data does not appear in the before section but does appear in the after section.

SQL SERVER 2000, XML, AND ASP.NET

In cases where a table’s primary key is determined by an auto-incrementing field, the identity of a newly added row can be obtained by adding the returnid attribute to the sync element and the at-identity attribute to the appropriate table element, as shown next:

9

392

XML for ASP.NET Developers

The identity of the newly added record will be returned in the following format: 404

LISTING 9.19

Performing an Update Using Updategrams

1: 2: 3: 4: 5: 6: 7: 8: 9: 10:

Referring back to Table 9.5, you can see that an update is performed when there is data within the before and after sections. Listing 9.19 first uniquely identifies a row in the Customers table by listing the CustomerID attribute’s value in the before section of the template. The after section contains only the name and value of the field in the database that should be updated. Because the CustomerID value was provided in the before section, it is automatically used in the after section. Although this example shows only one column being updated, others can be listed as necessary. LISTING 9.20

Performing a Delete Using Updategrams

1: 2: 3: 4: 5: 6: 7: 8: 9:

Using Updategrams to perform deletes is as simple as providing the table name along with the value of the table’s primary key in the before data section. By leaving the after data section blank, the database knows that this row should be deleted.

SQL Server 2000, XML, and ASP.NET CHAPTER 9

393

Although the examples shown to this point have shown how easy it is to work with Updategrams to perform inserts, updates, or deletes, they haven’t been very practical. How many times have you found it useful to hard-code a value into a SQL statement or stored procedure to perform an insert, update, or delete? This is because insert, update, and delete operations are normally designed to accept variable input parameters. Like XML templates, Updategrams also allow parameters to be passed in. Listing 9.21 shows how to use parameters in Updategrams to update a record. LISTING 9.21

Using Parameters in Updategrams

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14:

http://localhost/northwind/templates/listing9.21.xml?CustomerID=DLWID& CompanyName=Wahlin+Consulting

Several more advanced aspects of Updategrams have not been covered in this section. For example, multiple updates, inserts, or deletes can be performed in a single Updategram, and updates involving multiple tables can be performed with the aid of mapping schemas. Updategrams are a promising technology that can provide additional flexibility to ASP.NET applications. can be especially useful in applications where end users do not always have connectivity to the network or database (traveling sales representatives, for example). By storing

Updategrams

9 SQL SERVER 2000, XML, AND ASP.NET

Lines 2–5 take care of adding two input parameters named CustomerID and CompanyName. These parameters are then dynamically added to the before and after data sections by appending them with the $ character, as shown in lines 8 and 11. Passing the parameters into the Updategram is accomplished in the same manner as passing parameters to regular template files:

394

XML for ASP.NET Developers

the necessary database changes in the form of Updategram files, when the user can connect to the network, any database changes can be sent and processed automatically by the SQL Server 2000 database. There are, of course, many other potential uses; the sky’s the limit!

Using ADO.NET with SQL Server 2000 You may work on different ASP.NET projects that require ADO.NET be used to query SQL Server rather than HTTP. In these situations, how can you leverage the XML features found in SQL Server 2000? Fortunately, you can still retrieve XML directly from the database by using the FOR XML keywords in your queries. However, the XML data returned from these types of queries will not be well formed because the returned XML will not have a single root tag wrapping all elements. To work with non–well-formed XML returned from FOR XML queries, ADO.NET’s SqlCommand class contains a method, named ExecuteXmlReader(), designed for this purpose. This method returns an XmlReader object that can be used to parse through the XML, as shown back in Chapter 5, “Using the XmlTextReader and XmlTextWriter Classes in ASP.NET” Listing 9.22 demonstrates how to use this method. LISTING 9.22 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23:

Using the ExecuteXmlReader() Method with FOR XML Queries

private void Page_Load(object sender, System.EventArgs e) { Response.ContentType = “text/xml”; string sql = “SELECT * FROM Customers FOR XML AUTO”; string connStr =”server=localhost;uid=sa;pwd=;database=Northwind”; SqlConnection sqlConn = new SqlConnection(connStr); sqlConn.Open(); SqlCommand cmd = new SqlCommand(sql,sqlConn); XmlReader reader = cmd.ExecuteXmlReader(); Response.Write(“”); Response.Write(“”); while (reader.Read()) { Response.Write(“”); 25: } 26: Response.Write(“”); 27: sqlConn.Close(); 28: if (reader != null) reader.Close(); 29: } 30:

The code in Listing 9.22 creates well-formed XML that is simply written out to the browser. This same type of process can be made more useful by dynamically loading the XML fragment returned from SQL Server 2000 into an XPathDocument class and then transforming it using XSLT. Listing 9.23 shows how this is accomplished. LISTING 9.23

Transforming XML data returned by the ExecuteXmlReader() Method

9 SQL SERVER 2000, XML, AND ASP.NET

1: 2: 3: 4: 5: 6: 7: 8: private void Page_Load(object sender, System.EventArgs e) { 9: string sql = @”SELECT * FROM Customers 10: INNER JOIN Orders 11: ON Customers.CustomerID = Orders.CustomerID 12: FOR XML AUTO”; 13: string connStr =”server=localhost;uid=sa;pwd=;database=Northwind”; 14: SqlConnection sqlConn = new SqlConnection(connStr); 15: sqlConn.Open(); 16: SqlCommand cmd = new SqlCommand(sql,sqlConn); 17: XmlTextReader reader = (XmlTextReader)cmd.ExecuteXmlReader(); 18: //XPathDocument will add a root node for us 19: XPathDocument xmlDoc = new XPathDocument(reader); 20: XslTransform xslDoc = new XslTransform(); 21: xslDoc.Load(Server.MapPath(“customers.xsl”)); 22: xslDoc.Transform(xmlDoc,null,Response.Output); 23: sqlConn.Close(); 24: if (reader != null) reader.Close(); 25: } 26:

396

XML for ASP.NET Developers

Because the SQL query can return many customer records, you would think that these records need to be wrapped with a root node before the XML could be passed to the XPathDocument’s constructor. Fortunately, the XPathDocument class will take care of adding a root node automatically, making it easy to transform the XML via XSLT.

The XmlParserContext Class In cases where the XML data returned from a FOR XML query depends on portions of a DTD, such as an entity definition, for instance, the XmlParserContext class can be used. One of this class’s constructors allows internal DTD subsets to be “hooked up” with the XML fragment returned from the SQL server query. In more understandable terms, a subset is simply part of a DTD, such as an entity definition () that must exist for the XML fragment to be used properly. The .NET SDK defines one of the XmlParserContext class’s constructors in the following manner: public XmlParserContext( XmlNameTable nt, XmlNamespaceManager nsMgr, string docTypeName, string pubId, string sysId, string internalSubset, string baseURI, string xmlLang, XmlSpace xmlSpace );

When namespace URIs not included in the XML fragment must be identified as the XML fragment is parsed, the XmlNamespaceManager class can be created, filled, and passed in as an argument. If this (along with other classes such as the XmlNameTable class) is not needed by the application, NULL can be passed instead (in C#). For our purposes, we’ll focus specifically on the docTypeName and internalSubset arguments. The docTypeName argument defines the DOCTYPE name. The internalSubset argument defines one or more parts of a DTD that may be referenced by the XML fragment. The code shown in Listing 9.24 shows how the XmlParserContext class can be used to define an entity named contact that is referenced by the XML fragment returned from the FOR XML query. This entity definition is created in a string named entityString (line 10) that is added to the constructor for the XmlParserContext class (lines 31–33). Any entity definitions in the XML that are defined as &contact; will be resolved to a value of Anders.

SQL Server 2000, XML, and ASP.NET CHAPTER 9

LISTING 9.24

Using the XmlParserContext Class

private void Page_Load(object sender, System.EventArgs e) { //Define the entity returned by the data string entityString = “”; string sql = @”SELECT * FROM Customers INNER JOIN Orders ON Customers.CustomerID = Orders.CustomerID WHERE Customers.CustomerID = ‘ALFKI’ FOR XML AUTO”; string connStr=”server=localhost;uid=sa;pwd=;database=Northwind”; SqlConnection sqlConn = new SqlConnection(connStr); sqlConn.Open(); SqlCommand cmd = new SqlCommand(sql,sqlConn); XmlReader reader = cmd.ExecuteXmlReader(); reader.MoveToContent(); //SQL 2000 will automatically escape & with & //so do a replace string xmlString = new StringBuilder(reader.ReadOuterXml()).Replace(“&”, “&”).ToString(); //Create the parser context. This specifies that the //DOCTYPE root is Customers and the subset to add in //(entityString in this case) XmlParserContext xmlContext = new XmlParserContext(null, null, “Customers”, null, null, entityString,””, “”, XmlSpace.None); XmlValidatingReader xmlReader = new XmlValidatingReader(xmlString,XmlNodeType.Element, xmlContext); xmlReader.ValidationType = ValidationType.None; XmlDocument xmlDoc = new XmlDocument(); XmlElement root = xmlDoc.CreateElement(“Northwind”); xmlDoc.AppendChild(root); while (!xmlReader.EOF) { root.AppendChild(xmlDoc.ReadNode(xmlReader)); }

9 SQL SERVER 2000, XML, AND ASP.NET

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44:

397

398

XML for ASP.NET Developers

LISTING 9.24

continued

45: //Do Transformation 46: XslTransform xslDoc = new XslTransform(); 47: xslDoc.Load(Server.MapPath(“customers.xsl”)); 48: xslDoc.Transform(xmlDoc,null,Response.Output); 49: sqlConn.Close(); 50: if (xmlReader != null) xmlReader.Close(); 51: if (reader != null) reader.Close(); 52: } 53:

Summary SQL Server 2000 provides a rich set of useful features dedicated to working with data in the form of XML. Through leveraging these features, layers of ASP.NET code can be eliminated. Direct access to the database can be accomplished via URL queries, templates, XPath queries, and through OPENXML and Updategrams. This allows XmlDocument, XPathDocument, or DataSet objects to be loaded directly without going through the SQL managed provider. When used with XSLT, this presents an efficient solution that can simplify your ASP.NET application development. In the next chapter, you’ll be presented with an in-depth look at Simple Object Access Protocol (SOAP) and see how Web services can be created to expose your data or services as XML to interested parties anywhere in the world. You’ll also see how you can utilize external Web services to enhance your ASP.NET applications.

Working with ASP.NET, XML, SOAP, and Web Services

IN THIS CHAPTER Understanding SOAP

400

Understanding Web Services

421

Retrieving Customer Orders Through a Web Service 444

CHAPTER

10

400

XML Related Technologies

Understanding SOAP Making calls to distributed objects to obtain data or perform specific functions has not been an easy task in the past. For example, if your application needs to obtain address or credit card information found on a remote system, accessing the appropriate object or objects on that system has been somewhat problematic. Add the fact that many remote systems rely on a specific vendor technology or language, and the problem is compounded. Many alternatives to this problem have been presented over the years, including CORBA (Common Object Request Broker Architecture), DCOM (Distributed Common Object Model), and Java RMI (Remote Method Invocation), but none have resulted in simplifying remote object calls without inventing some type of new technology or relying on vendor-specific technology. With the introduction of version 1.0 of the Simple Object Access Protocol (SOAP) in September of 1999, a new mechanism for making Remote Procedure Calls (RPC) emerged that combines the power of XML with the HTTP protocol. Version 1.1 of SOAP provides more flexibility in working with other types of wire transport protocols, including FTP and SMTP. In this chapter we’ll take a look at the importance of the SOAP specification and detail how SOAP can be used in ASP.NET to provide applications with more power and flexibility. This discussion includes information about the SOAP specification itself, alternatives to SOAP, and what role SOAP plays in Web services. By the end of the chapter you’ll have a good understanding of how you can consume and expose a variety of services using SOAP along with other description languages built in to the .NET platform. Before formally introducing SOAP, let’s take a look at a few alternatives.

Alternatives to SOAP The SOAP protocol is the latest in many attempts to simplify the process of making calls to objects found in distributed environments. In this section we’ll take a high-level look at a few of the alternative protocols to give you a better perspective on why the SOAP protocol is so promising. Let’s start off by examining a protocol many Microsoft developers are already familiar with: DCOM.

Distributed Component Object Model (DCOM) When Microsoft first introduced the DCOM, it provided a tightly coupled component model system that allowed client programs to make calls to objects located in remote network locations. This is accomplished by looking up the object’s location through calling a Service Control Manager (SCM) or a system Registry. The functionality provided by DCOM is needed by developers to allow for easier maintenance of COM-based applications and incorporation of a tiered approach to application development. Although DCOM works well in a Windows environment (a few non-Windows implementations of DCOM also exist), it is generally not

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

401

considered to be a scalable solution because of how it handles garbage collection and connection management. DCOM clients instantiate a connection to a remote object by using a proxy. After a reference to the object has been obtained, clients send ping messages to let the object know that they are still acting as a consumer. This creates scalability problems as the number of clients sending ping messages across the network increases. DCOM also presents challenges dealing with firewalls and state management. With regard to firewalls, if the firewall administrator has not opened ports used to pass through DCOM marshaling calls, the calls will likely be blocked and therefore fail before reaching the intended recipient object. DCOM also relies on state management to know when a particular client is no longer connected (the pinging mechanism). This makes using it in a stateless arena such as the Web more difficult. For more information concerning DCOM, visit http://www.microsoft.com/com/tech/ dcom.asp.

Common Object Request Broker Architecture (CORBA) CORBA offers another way of calling remote objects from a client. As with DCOM, CORBA is connection based, making it less scalable and more difficult to work with in a stateless Web environment. In general, CORBA works by sending a LocateRequest message across the wire (IIOP is used with TCP/IP wire transmissions) to an information repository called an ORB to determine an object’s location. After this location is determined, direct communication between the client and remote object can occur. Although many implementations of the ORB exist on a variety of systems, CORBA is subject to many of the same problems that restrict DCOM from excelling in a platform-neutral distributed environment. For more information concerning CORBA, visit http://www.corba.org.

Java Remote Method Invocation (RMI) From a high-level perspective, Java RMI works in a manner similar to both DCOM and CORBA in that it connects a client with a remote object and works by using a distributed object architecture. The location of the object is found by making a call to an RMI Registry. This registry must be known to clients and have a specific place on the network. When the remote object location is found, the client can download a stub used to access the object. After the stub has been downloaded to the client, access to the object’s properties and methods is then available.

For more information concerning Java RMI, visit http://java.sun.com/products/jdk/rmi/.

10 ASP, NET, XML, SOAP, AND WEBSERVICES

Compared to both DCOM and CORBA, Java RMI arguably represents a more scalable solution because of its capability to use HTTP tunneling. However, because it focuses on the Java language, it doesn’t present an optimal solution for exposing services to clients written using other languages.

402

XML Related Technologies

XML-RPC XML-RPC was one of the first specifications to use XML structures in making remote calls. It allows calls to ride on top of HTTP, which allows them to pass through firewalls on port 80. The XML-RPC Specification revolves around the HTTP POST to transmit XML structures to and from different distributed systems. Many high-level concepts described by XML-RPC have been adopted into the SOAP protocol. An example of a simple remote method call using XMLRPC is shown next: GetName ALFKI

Looking at this, you can see that it is an extremely verbose way of marking up or “serializing” a method call. On the other hand, it’s very easy to understand and parse. However, you’ll see in the next few sections that SOAP extends many of the XML-RPC concepts and minimizes some of the more verbose XML-based calls. SOAP also refines data typing by leveraging the W3C Schema Part II specification. Although XML-RPC does present a good starting point for using XML in distributed environments, it has several areas that can be improved on. Sometimes more is less. This is especially true when it comes to transmitting data over the wire with HTTP. For more information concerning XML-RPC, including information on where to download XML-RPC–compatible implementations for a variety of platforms, visit http:// www.xmlrpc.com.

What Is SOAP? Aside from XML-RPC, the SOAP alternatives previously listed (as well as many others that were not covered) rely on complex distributed object architectures installed on tightly integrated systems. SOAP provides a much simpler architecture. In fact, SOAP is simply a wire protocol that can be used to transfer information between a client and a server using XML to maintain structure. It does not rely on complex object architectures to make calls between distributed objects. Rather, SOAP provides a framework for exchanging messages between distributed environments without relying on a particular operating system, a programming

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

403

language, or an object model architecture. The authors of the SOAP version 1.1 protocol provide the following definition: SOAP provides a simple and lightweight mechanism for exchanging structured and typed information between peers in a decentralized, distributed environment using XML. SOAP does not itself define any application semantics such as a programming model or implementation specific semantics; rather it defines a simple mechanism for expressing application semantics by providing a modular packaging model and encoding mechanisms for encoding data within modules. This allows SOAP to be used in a large variety of systems ranging from messaging systems to RPC. One of the design goals first identified by the SOAP authors was to develop a protocol that invented no new technology. After all, with the rise of XML and HTTP over the years, an excellent foundation already existed that could be leveraged by the SOAP authors. As a result, SOAP relies on XML and a variety of other protocols including HTTP to exchange calls between objects. SOAP works by serializing object calls into an XML structure that can then be passed to another machine using a protocol such as HTTP. “What is serialization?” you ask. You saw a simple example of this in the XML-RPC section, but let’s take a look at a more abstract sample. Assume a distributed object exposes the following method that is used to get a customer name from a database: GetName(int CustomerID) {}

Serializing this method call into an XML structure could result in the following XML fragment: 1234

As shown, serialization simply takes a given object and “serializes” particular aspects of the object into a structure that can be easily transported to a remote system. After the remote system receives it, processing must be done to extract the information, instantiate the correct object, make the appropriate method call, and return a response to the caller.

ASP, NET, XML, SOAP, AND WEBSERVICES

Although the previous serialized XML structure may work for your own objects, how do other objects know how to work with it? And if the remote object is required to return a response, what structure should the response follow? This is where the SOAP protocol comes into play.

10

404

XML Related Technologies

It provides a standard way to serialize calls made to remote objects and retrieve results returned by the object. This allows any application with an understanding of SOAP to be accessed remotely, no matter what language or operating system it relies on. Imagine the possibilities! Before you jump into more specifics on the SOAP protocol, Listing 10.1 provides a quick look at how the GetName() method shown earlier can be serialized into a valid SOAP request structure. LISTING 10.1

Serialization of the GetName() Method into a SOAP Request Structure

1: 4: 5: 6: ALFKI 7: 8: 9:

Details on the different pieces used to create this SOAP request follow in the next few sections. After learning these details, you’ll see how SOAP can be used with Web services to enhance your ASP.NET applications.

NOTE Although the next few sections provide a detailed look at the different pieces that make up a SOAP request or response, a more thorough look at SOAP is provided by the book Understanding SOAP (ISBN 0-672-31922-5) by Kennard Scribner and Mark Stiver, Sams Publishing.

Analyzing SOAP’s Structure Now that you understand the basic purpose behind the SOAP protocol and have seen a few of the alternatives, let’s take a look at the different pieces that are needed to construct a valid XML-based SOAP request and response. Because SOAP relies on XML to serialize calls, many of the concepts you learned in prior chapters, including the rules associated with XML and the necessity of namespaces, will be applicable. You’ll find that your current knowledge of XML will make learning to work with SOAP rather easy.

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

405

SOAP messages can contain some or all of the following elements, depending on the functionality that a given SOAP structure includes: • Envelope • Header • Body • SOAP namespaces • Attributes • SOAP fault To fully understand these elements and how they relate to each other in a SOAP message, Listing 10.2 presents the schema that a SOAP message follows. Each of the items listed in the schema will be discussed in turn in the next few sections.

NOTE The schema shown in Listing 10.2 is based on an older schema specification. It is shown here only to help you understand the structure and contents of SOAP messages, not to demonstrate how to create XML schemas.

LISTING 10.2

The SOAP Message Schema (http://schemas.xmlsoap.org/soap/

envelope/)

10 ASP, NET, XML, SOAP, AND WEBSERVICES

1: 2: 3: 6: 9: 10: 11: 12: 13: 14: 15: 16: 17:

406

XML Related Technologies

LISTING 10.2 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61:

Continued

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

LISTING 10.2

407

Continued

62: 63: 64:

Let’s first take a look at the wrapper around SOAP messages: the Envelope.

The SOAP Envelope Because the SOAP protocol adheres to the XML version 1.0 specification, all SOAP XML structures must have a single root element that acts as a wrapper for all other content. The Envelope element serves as this single root in SOAP. Although some parts of a SOAP message are optional, the Envelope element is required and must appear for SOAP calls to function properly. The Envelope element may contain namespace declarations and attributes, although these items are optional. The following example shows the different elements that the Envelope element may wrap:

As shown, the Envelope element acts as a container for all content found within a SOAP message. Notice that the element contains a SOAP namespace named soap that points to a URI of http://schemas.xmlsoap.org/soap/envelop/ (the actual location of the SOAP message schema). It also contains namespace declarations relating to the XML schema specification and the schema instance. Although Envelope element attributes are optional, any attribute that does appear in the Envelope element must be namespace qualified. Before proceeding, let’s take a more in-depth look at Envelope namespaces and attributes.

The previous example of the SOAP message structure included the soap namespace. Looking back at Listing 10.2, you’ll notice that the Envelope element definition includes the tag (line 17). This allows for custom attributes to be added to the

ASP, NET, XML, SOAP, AND WEBSERVICES

SOAP Envelope Namespaces and Attributes

10

408

XML Related Technologies

element as necessary. As mentioned earlier, these attributes must be namespace qualified to be included in the SOAP message.

Envelope

With regard to namespaces, an interesting aspect of the soap namespace shown in the previous example is that it does not specify what version of SOAP we are working with. This is according to the SOAP version 1.1 specification. The specification states the following: SOAP does not define a traditional versioning model based on major and minor version numbers. A SOAP message MUST have an Envelope element associated with the “http:// schemas.xmlsoap.org/soap/envelope/” namespace. If a message is received by a SOAP application in which the SOAP Envelope element is associated with a different namespace, the application MUST treat this as a version error and discard the message. If the message is received through a request/response protocol such as HTTP, the application MUST respond with a SOAP VersionMismatch faultcode message (see section 4.4) using the SOAP “http://schemas.xmlsoap.org/soap/envelope/” namespace. What does this tell us about the namespace URI? To send properly structured SOAP messages, the namespace URI must be included on the Envelope element exactly as shown: http://schemas.xmlsoap.org/soap/envelope/

Keep in mind that as the SOAP specification goes through the W3C working group process, the namespace may eventually change. But for now, changing the URI will result in the remote application returning a faultcode message (discussed later). Although the example shown earlier used the soap namespace prefix, you are free to use your own prefix name as long as it points to the proper URI.

The SOAP Header Referring back to the SOAP schema shown in Listing 10.2, you can see that the Header element may optionally appear as the first child of the Envelope element. If it does appear, it must be the first child in the SOAP message. The specification states that only direct children of the Header element can be processed by an application. As is the case with the Head element in HTML, the Header element can be used to specify special information that needs to be embedded within the SOAP message. The SOAP version 1.1 specification shows an example of embedding transaction information within the Header element, as shown next: 5

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

409

This example shows how independent elements such as the Transaction element must be namespace qualified. Assuming the remote object being called understands the data contained within the Transaction element, the appropriate action can be taken. What happens if the object doesn’t understand how to deal with transactions properly? Should it go ahead and process the request? This is where the mustUnderstand attribute comes into play.

SOAP Header Attributes As with the Envelope element, the SOAP Header element schema definition contains the tag in its definition. This allows custom attributes to be used as long as they are namespace qualified. The SOAP version 1.1 schema also includes two global attribute definitions named mustUnderstand and actor, as shown next:

The global nature of these attributes allows them to be applied to any complexType definition within a SOAP message, meaning that it can be used on any element. However, they will normally be used within the Header element section of a SOAP message. When the mustUnderstand attribute is used on the Header element, the recipient of the message must “understand” how to process the information contained within the Header element. Because incorrect return values may result from a recipient that does not understand a particular section contained within the Header element, the mustUnderstand attribute provides a safety net. The SOAP specification says that any recipient that cannot understand the information within the Header element when the mustUnderstand attribute is true (1) must fail to process the message and return the SOAP-ENV:MustUnderstand fault (discussed later). If this attribute is not present, it defaults to a value of false (0).

An intermediary serves the dual purpose of receiving and forwarding SOAP messages. As a SOAP message starts along the path toward the final recipient, some of the message’s header information may be directed to a particular intermediary involved in the transferal process.

10 ASP, NET, XML, SOAP, AND WEBSERVICES

The actor attribute is used in cases where a SOAP message may pass through one or more intermediaries before reaching the final destination recipient. This attribute can contain a URI value type that is used to identify the recipient of the Header element. The specification provides a special URI with a value of http://schemas.xmlsoap.org/soap/actor/next for cases where a SOAP message header is intended for the first SOAP application that processes the message. A Header element containing no actor attribute automatically infers that the recipient is the end point or final recipient in the SOAP message path.

410

XML Related Technologies

After an intermediary receives a message with information directed to them (identified by the actor attribute’s URI value), the SOAP specification states that they may not pass this information along to other destinations in the path. This means that they may not forward the Header element after they’ve consumed it. The specification does allow for intermediaries to insert a new header element to pass along, but the “contract” for this newly added element will be between the intermediary and the intended recipient. The originator of the SOAP message will not have any knowledge nor ever see the newly added header.

The SOAP Body Now that you’ve seen how the Envelope element is used to wrap SOAP messages and how the Header element can be used to mark up special instructions, let’s introduce the focal point of the SOAP message: the Body element. As with HTML, the Body element contains the bulk of the information that is passed to a given SOAP recipient. Whereas the Header element is optional, the SOAP version 1.1 specification states that the Body element must be present for a SOAP message to be considered valid. Within the Body element, you can find all the information needed to call a method. This includes all the necessary parameter values that a particular method may be expecting. It is also designed to contain response information and, in the case of errors, fault information. Each of these different Body element types will be discussed in turn. Let’s first examine making a SOAP call.

The Call Element Serializing a given object’s information into a SOAP call is a fairly straightforward process. Immediately following the SOAP Body element, the method to be called must be included followed by any parameters that the method may be expecting. The following SOAP request revisits Listing 10.1 to show this process: ALFKI

Looking at the previous SOAP message, you can see that the GetName() method introduced earlier in the chapter is being called. The method name is listed immediately following the

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

411

element and is namespace qualified. The CustomerID parameter is then listed as a child element of the method name and contains the data to be passed to the method. Body

Listing 10.3 contains a slightly more complex method call. The method being serialized is shown next: GetOrders(string CustomerID,int SalesRepID,float OrderMax)

LISTING 10.3

Serializing the GetOrders() Method into a SOAP Message

1: 5: 6: 7: ALFKI 8: 85 9: 49.99 10: 11: 12:

The Body element structure for this method call is very similar to the structure shown earlier aside from the additional parameters.

The Response Element The capability to initiate calls to distributed objects by serializing them into SOAP messages would certainly be useless without the capability to access the information returned by the remote application. Listing 10.4 shows an example of a response generated by the SOAP application called using the SOAP message shown in Listing 10.3. LISTING 10.4

Serialized GetOrders() SOAP Response

10 ASP, NET, XML, SOAP, AND WEBSERVICES

1: 5: 6: 7: 8: 9: 10:

412

XML Related Technologies

LISTING 10.4

Continued

11: 12: 13: 14: 15:

Notice that the method name has been appended with the word “Response” to identify this SOAP message as a response. Immediately under the method response element (GetOrdersResponse), the return element is used to encapsulate the SOAP response. This example shows how data records can be serialized into an XML structure that can then be sent back to the calling SOAP application. A more simple SOAP response may have only a single return value, as follows: 1582

The return element must always be the first one listed under the method response element. If the method also contains out parameters, these elements may then follow the return element in the SOAP body.

The Fault Element Virtually any application has the potential to generate errors because of a variety of circumstances. This is especially true when calls are being made between distributed systems located anywhere in the world. A remote system may not be available, may have changed a given method’s signature, or may experience problems deserializing a SOAP message. Because of these problems, no RPC mechanism framework would be complete without a way to return errors that arise during the process. SOAP has a built-in mechanism to return any errors encountered while SOAP messages are transferred or manipulated. This is accomplished by embedding the Fault element within the body section of a SOAP message. Before examining the different information that may be contained when a fault occurs, let’s take a look at a sample SOAP message with embedded fault information. Listing 10.5 shows an example of a SOAP response that contains fault information. LISTING 10.5

A SOAP Response Message with Embedded Fault Information

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

LISTING 10.5

413

Continued

soap:Server Server Error Incorrect number of supplie parameters 624

When an error occurs, the SOAP application is required to place the Fault element as the first child of the Body element in the SOAP message. The Fault element may have some or all of the child elements listed in Table 10.1, depending on the nature of the error that occurred. TABLE 10.1

Fault Element Subelements

Description

faultcode

Provides a mechanism for identifying the fault. The faultcode element must be present as a child of the Fault element if a fault occurs and its value must be qualified. Table 10.2 shows the four fault code values defined by the SOAP specification. The faultstring element provides a human-readable version of the fault. If a fault occurs, this element must be present as a child of the Fault element. In cases where a fault was caused by an intermediary actor, the faultactor element provides information about the actor causing the fault. The value of the element will contain a URI that identifies the actor. An actor that is not the end-point destination for a SOAP message must provide this element as a child of the Fault element to let the calling application know where the fault was caused. The detail element provides application-specific information related to faults caused within the body section of a SOAP message. Faults caused by a header section of a SOAP message must not return a detail element as a child of the Fault element. This allows calling applications to know whether the body was processed. Children of the detail element are referred to in the SOAP version 1.1 specification as detail entries. These child elements must be namespace qualified.

faultstring

faultactor

detail

10 ASP, NET, XML, SOAP, AND WEBSERVICES

Element Name

414

XML Related Technologies

TABLE 10.2

Fault Codes Defined in the SOAP Specification

Name

Description

VersionMismatch

This code is used when an application finds an invalid namespace used for the SOAP Envelope. A child element of the Header element within a SOAP message was not understood by an application. This error specifies that the message was incorrectly formed or didn’t contain proper information. An example of when this fault code could be used is when information supplied by the client is not enough to authenticate with the remote SOAP application. This code normally indicates that a SOAP message will need to be changed to be successful.

MustUnderstand Client

Server

Well-formed and valid SOAP messages that are not processed correctly or are not able to be processed by the server application will result in this fault code. Although the server may be functioning properly, another “up-stream processor” queried by the server may not be accessible. Sending the message at a later time may result in success.

SOAP Encoding and Data Types Up to this point, you have seen the different elements that make up a SOAP message. Although these are very useful in providing a structure for a remote call, serialized method calls require that parameters be properly encoded to be successfully used by a remote SOAP application. In this section we’ll take a high-level look at the main encoding data types in the SOAP specification. For a complete listing of the data types, refer to the SOAP version 1.1 specification or the book Understanding SOAP (ISBN 0-672-31922-5) by Sams Publishing. Encoding parameters within the body of a SOAP message involves specifying what data type a parameter is associated with. What data types can be used, though? Can we arbitrarily pick a type, and if so, how can we guarantee that a remote system will know how to handle it? Fortunately, the SOAP specification includes a detailed section concerning this topic that is based upon the W3C XML Schema Part 2. Let’s first take a look at simple types.

SOAP Simple Types The SOAP version 1.1 specification includes the primitive and derived simple types defined in the W3C XML Schema Part 2 document mentioned previously. These include all the data types shown in Table 10.3.

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

TABLE 10.3

primitive

derived

415

SOAP Simple Data Types

Datatype

Numeric

string

false

boolean

false

float

true

double

true

decimal

true

duration

false

dateTime

false

time

false

date

false

gYearMonth

false

gYear

false

gMonthDay

false

gDay

false

gMonth

false

hexBinary

false

base64Binary

false

anyURI

false

QName

false

NOTATION

false

normalizedString

false

token

false

language

false

IDREFS

false

ENTITIES

false

NMTOKEN

false

NMTOKENS

false

Name

false

NCName

false

10

ID

false

IDREF

false

ENTITY

false

ASP, NET, XML, SOAP, AND WEBSERVICES

416

XML Related Technologies

TABLE 10.3

Continued

Datatype

Numeric

integer

true

nonPositiveInteger

true

negativeInteger

true

long

true

int

true

short

true

byte

true

nonNegativeInteger

true

unsignedLong

true

unsignedInt

true

unsignedShort

true

unsignedByte

true

positiveInteger

true

The SOAP specification allows for single and multiple references to a particular type. A single reference occurs when information appears only once within a SOAP message. All the previous SOAP message examples up to this point demonstrated single references. A multiple reference occurs when the same piece of information occurs more than once within a SOAP message. For example, if a string listed in two parameters contains the same value, each parameter can instead refer to a reference as shown next. Doing this conserves space by making the serialized call less verbose, especially when an information item may appear multiple times within a SOAP message: ALFKI

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

417

This example shows how the id and href attributes can be used to allow multiple parameters to reference the same piece of information.

SOAP Compound Types Although the encoding types shown in Table 10.3 will be sufficient in many situations, at times more complex structures may be needed to properly serialize and encode parameter types. After all, what if a remote SOAP application expects an array or struct to be passed to it? With simple types alone this cannot be accomplished. The SOAP authors were aware of this and included compound types in the SOAP specification. The SOAP specification defines an array as “a compound value in which ordinal position serves as the only distinction among member values.” In cases where an array needs to be serialized into a SOAP message, the following XML structure can be used: ALFKI GPKME DLWID PAAIQ

Notice that the array’s structure is qualified by the SOAP-ENC namespace (SOAP Encoding) and has an attribute named arrayType. This attribute’s value specifies the type of array and the number of members. After this information is specified, the actual members of the array are listed sequentially. The array structure is referenced by using the href and id attributes as shown earlier.

Sparse Array: Third row, third col Eighth row, third col

Partially Transmitted Array: The third element The fourth element

Multidimensional Arrays: r1c1 r1c2 r1c3 r2c1 r2c2 r2c3

In addition to arrays, the SOAP specification also allows compound types such as structs to be serialized. The specification defines a struct as “a compound value in which accessor name is the only distinction among member values, and no accessor has the same name as any other.” As an example, the SOAP version 1.1 specification provides the following example of serializing a struct named Book: Henry Ford Prefatory text This is a book.

A more complex example of using structs is shown next: My Life and Work

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

419

Henry Ford mailto:[email protected] http://www.henryford.com Samuel Crowther Martin Luther King Rd Raleigh North Carolina

Finally, both arrays and structs can coexist in a SOAP message structure: Henry Ford 5th Ave New York NY 10010 Apple 1.56 Peach 1.48

SOAP HTTP Headers 10 ASP, NET, XML, SOAP, AND WEBSERVICES

The HTTP protocol works in conjunction with TCP/IP through the use of headers that contain information and methods specific to a request or response. These headers provide necessary functionality that allows SOAP messages to be transported to and from distributed systems using HTTP. Within the headers, three methods can be used— GET, POST, and M-POST. Headers can also contain Content-Length, Content-Type, and name/value pair information specific to the request or response.

420

XML Related Technologies

The following example shows a simple HTTP POST request that contains the mandatory SOAPAction field. According to the SOAP version 1.1 specification, this field must be included within HTTP requests to allow firewalls to appropriately filter SOAP messages sent via HTTP. The value of this field normally contains a namespace URI followed by the # character and the name of the method being called within the SOAP body. A firewall can then match the namespace URI and method name with those specified within the SOAP message: POST /StockQuote HTTP/1.1 Content-Type: text/xml; charset=”utf-8” Content-Length: nnnn SOAPAction: “Some-URI#GetName” ALFKI

An HTTP response looks similar, although the status of the response needs to be returned to the client. In this case a success code of 200 is being returned, although you’re more than likely quite familiar with other return codes such as the infamous 404 Not Found error code: HTTP/1.1 200 OK Content-Type: text/xml; charset=”utf-8” Content-Length: nnnn

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

421

For more information concerning the HTTP protocol, visit http://www.normos.org/ietf/ rfc/rfc2616.txt.

Understanding Web Services Now that you’ve seen how SOAP messages are structured and the role that SOAP plays in integrating distributed applications, let’s take a look at how SOAP can be used with Web services. Web services can be described best as services or applications that expose programmatic functionality through the Internet. This functionality allows virtually any application to either expose or consume services that can perform a variety of tasks. For example, a Web service may perform the task of validating an address. An ASP.NET application could capture a customer’s shipping address through a Web form and send it to the address validation Web service. In response to receiving the address, the service can validate it and make any necessary adjustments to ensure that it follows local postal and shipping regulations. Another Web service may expose local weather data. By passing the service a regional identifier, a response can be generated that provides the current temperature, five-day forecast, and historical weather for the region. These are just two examples of Web services that can be used by ASP.NET applications to allow for the dynamic inclusion of data. In reality, there is no limit to the different types of Web services that can be developed for use today using the .NET platform. At this point you may wonder what the difference between a Web service and a regular HTML page is? After all, you can hit a site such as http://www.weather.com and get weather information! What advantages do Web services offer?

Web services allow you to work with objects and receive data in a nicely formatted XML structure. This means that you don’t have to employ costly string-parsing routines or resort

10 ASP, NET, XML, SOAP, AND WEBSERVICES

Although it’s true that you can get a lot of functionality out of regular HTML pages by using forms to post data to the Web server, Web sites are geared to work with display devices such as the browser. To manipulate the data contained within an HTML page and use it within your own site, you would need to use string manipulation routines to parse through the entire HTML page. Not only is this cumbersome (and similar to trying to find a needle in a haystack), it is certainly more complex than directly interacting with an object to extract data in a format that is easy to work with.

422

XML Related Technologies

to other screen-scraping methods. You simply invoke the remote object by sending a serialized request, get a response, deserialize the response message, and utilize that response data as appropriate.

NOTE To see just how much work can be involved when screen scraping an HTML file to gather the required data, take a look the following articles: http:// www.asptoday.com/articles/19991229.htm http://www.asptoday.com/ articles/19991231.htm.

Web Service Protocols (SOAP, HTTP-GET, HTTP-POST) Before analyzing how to create or consume a Web service, it’s important to know what protocols can be used for communication. Because the bulk of the chapter up to this point has focused on SOAP, you can bet that SOAP can be used in communicating with Web services. Aside from SOAP, Web services can also be exposed and consumed via HTTP-POST and HTTPGET commands. Offering these different protocols allows for a given Web service to maximize its flexibility in working with a variety of applications from large-scale servers to smaller PDA devices. You’ve already had the opportunity to see how SOAP can be used to work with distributed applications, but let’s take a quick look at the other two options. HTTP-GET You have more than likely been exposed to working with the GET verb in creating classic ASP applications that utilize forms containing the method=”get” attribute. Forms that use this method will pass all form values as name/value pairs on the QueryString. For example, a Web form containing first name and last name as inputs could yield the following QueryString when submitted: http://www.someServer.com/processForm.aspx?firstname=Dan&lastname=Wahlin

Using C# and ASP.NET, you can extract name/value pairs found in the QueryString by doing the following: public void Page_Load(Object sender, EventArgs E) { Response.Write(“First Name: “ + Request.QueryString[“firstname”]); Response.Write(“”); Response.Write(“Last Name: “ + Request.QueryString[“lastname”]); }

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

423

When used with Web services, a QueryString containing the necessary name/value pairs can be passed to the service. In response, the XML structure will contain return values wrapped within XML elements that specify the value’s data type. For example, the following structure could represent a response to an HTTP-GET request when first and last names are passed to a Web service that returns the number of orders placed: 4

Although HTTP-GET requests are limited to name/value pairs, HTTP-GET does support returning any COM+ type as a return value. This means that types such as arrays, structs, DataSets, and arrays of structs can be returned. The following call to a Web service shows how an array of names can be sent using name/value pairs: http://www.someSite.com/arrays/returnArray?name=Dan&name=Todd&name=Elaine& name=Danny&name=Michelle

The returned structure would look as follows: Dan Todd Elaine Danny Michelle

HTTP-POST The HTTP-POST verb works in a manner similar to the HTTP-GET, except that the name/value pairs are not passed using the QueryString. Instead, this information is UUEncoded and passed within the body of the message sent to the Web service. Like HTTP-GET requests, the response contains return values wrapped within XML elements that specify the value’s data type. It’s important to note that both HTTP-GET and HTTP-POST Web service requests and responses are restricted to using name/value pairs. This is very limiting when more robust data types need to be sent. When these types are needed, SOAP must be used because it provides built-in support for sending complex types, as shown earlier in the chapter.

Web Service Architecture

ASP, NET, XML, SOAP, AND WEBSERVICES

Web services provide a fairly simple architecture that can be consumed to add additional functionality and power to ASP.NET applications. Using the .NET framework, Web services can also be written that non-Windows clients can consume using a variety of languages. Most of the more difficult parts associated with using Web services, including the serialization and

10

424

XML Related Technologies

deserialization of messages, occurs behind the scenes through using utilities provided by the .NET platform. These utilities (discussed later) automatically create the appropriate support files to expose or consume a Web service. So what pieces are needed for Web services to become functional? On the client side, a proxy can be created that allows the client application to serialize and send messages to the Web service. This proxy must also be able to deserialize responses sent back by the Web service. Before this proxy can be created, however, the client must know where to find the Web service and know what interface(s) the Web service exposes, including what parameters must be passed to it. After these resources are known, the client proxy can be created and a request message can be sent to the Web service, which can then send back the appropriate response. The relationship between the client and the Web service is depicted in Figure 10.1. Notice that because messages are transmitted using HTTP and SOAP, firewalls become much less of an issue when compared to other technologies such as DCOM and CORBA.

WSDL Response

Client

Web Service Proxy

Request UDDI

Firewall

Firewall

FIGURE 10.1 Web service architecture.

In the next section, you’ll learn how to build the Web service portion shown in Figure 10.1.

Introducing Web Service Attributes When the architects and programmers at Microsoft developed the .NET platform, they realized that languages such as C# and VB.NET needed the capability to be extended to handle a variety of programmatic scenarios. Through the introduction of attributes, the .NET platform has been infused with the capability to handle many different tasks, including that of creating Web services. The .NET SDK documentation defines attributes in the following way: [.NET] provides a mechanism for defining declarative tags, called attributes, which you can place on certain entities in your source code to specify additional information. The

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

425

information that attributes contain can be retrieved at run time through reflection. You can use predefined attributes or you can define your own custom attributes. Using attributes and processing directives along with the System.Web.Services namespace, Web services can be constructed quite easily and existing ASP.NET code can quickly be converted into a Web service that can be consumed by others. The main class used for Web service specific attributes is named WebMethodAttribute. It contains the properties listed in Table 10.4. TABLE 10.4

WebMethodAttribute Class Properties

Description

BufferResponse

Determines whether the response from the Web service request is buffered. Setting this property to true (the default) serializes the Web service response into a buffer. After the entire response is serialized, it is returned to the client. This property should be set to false only when large messages must be serialized. Determines the number of seconds the Web service response should be held in the cache. The default value is 0, which results in no caching at all. In cases where a Web service’s return value may not need to be completely dynamic, using this property can result in increased performance and efficiency. For large responses, turning on caching can reduce available memory. This is useful for describing the Web service and methods it exposes on the service description page. Determines if session state is enabled for a Web service method. The default is false. This property provides the name used for the Web service method in the data passed to and returned from a Web service method. It can be useful for aliasing methods and properties and when overloaded methods exist in a Web service class. Used when a Web service method needs transaction support. This property is disabled by default. Values can be members of the TransactionOption enumeration: • Disabled • NotSupported • Supported • Required

CacheDuration

Description EnableSession MessageName

TransactionOption

•

RequiresNew

10 ASP, NET, XML, SOAP, AND WEBSERVICES

Property

426

XML Related Technologies

Another class, named WebServiceAttribute, can also be used to provide a description of the Web service and to provide a namespace in which the Web service operates. By walking you through several examples, the next few sections show you how to use these attribute classes and their properties.

Using Attributes and Directives in Web Services The WebMethodAttribute class can be applied to methods in a Web service by using the WebMethod keyword. For C#, the attribute needs to be wrapped in square brackets and placed directly above the method you are exposing in the Web service: [WebMethod] public int myMethod(){}

VB.NET wraps the WebMethod attribute with < and > brackets and places it before the method definition: Public Function MyMethod() as Integer End Function

By applying this attribute, the method is made publicly accessible through HTTP-GET, HTTPPOST, or SOAP requests. Aside from attributes, code destined to be used as a Web service must also use a special processing directive named WebService. The use of this directive as well as the WebMethod attribute is shown in Listing 10.6. This listing simply returns a string value based on the input that is provided. LISTING 10.6 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11:

The Greeting Web Service (Listing10.6.asmx)

using System.Web.Services; [WebService(Namespace=”http://www.TomorrowsLearning.com/Greeting”)] class Greeting: WebService { [WebMethod] public string Greet(string name) { return “Hi “ + name + “!”; } }

The WebService directive must be the first line of your Web service. It lets the compiler know what type of component it is so that it can be compiled properly. Although the code references a class within the asmx file, it could reference another class stored in the \bin directory, if desired, by listing the namespace that the external class resides in:

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

427

In the majority of applications, referencing external classes is recommended because it encourages code reuse. For the samples that follow, the code will be shown within the asmx file for simplicity. Line 4 shows the WebService attribute. This attribute allows a namespace to be declared in which the Web service is a member. The Greeting class derives from the WebService class found in the System.Web.Services namespace (line 5). Doing this gives the class access to intrinsic ASP.NET objects such as Application, Session, and Context. In the next few sections, you’ll see how these ASP.NET objects can be used in a Web service. The WebMethod attribute (line 7) is applied to the Greet() method to make the method available to clients that call the Web service. By referencing the System.Web.Services namespace as well as adding the necessary directive and attributes as shown in Listing 10.6, all serialization/deserialization of SOAP messages will be taken care of automatically.

Adding Descriptions to Web Service Classes and Methods Although optional, the WebService attribute has a property that can be used to provide a description for a Web service. A description can also be associated with the WebMethod attribute. The following code segment shows how to incorporate descriptions: using System.Web.Services; [WebService(Namespace=”http://www.TomorrowsLearning.com/Greeting”, Description=”This Web Service responds by saying ‘Hi’”)] class Greeting: WebService { [WebMethod(Description=”This method says ‘Hi’ and appends the input “ + “param to the response”)] public string Greet(string name) { return “Hi “ + name + “!”; } }

Each description acts as a property of the appropriate attribute.

Handling Overloaded Methods

10 ASP, NET, XML, SOAP, AND WEBSERVICES

In cases where a class has overloaded methods that need to be exposed to Web service clients, the potential name conflict that may arise when a client hits the Web service can be resolved by adding a MessageName property to the WebMethod attribute, as shown in Listing 10.7:

428

XML Related Technologies

LISTING 10.7 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14:

Providing Method Aliases to Overloaded Methods

using System.Web.Services; [WebService(Namespace=”http://www.TomorrowsLearning.com/Greeting”)] class Greeting: WebService { [WebMethod] public string Greet(string name) { return “Hi “ + name + “!”; } [WebMethod(MessageName=”GreetVerbose”)] public string Greet(string fname,string lname) { return “Hi “ + fname + “ “ + lname + “!”; } }

Failing to uniquely identify the second Greet() method by using the MessageName property would result in the following error: Both System.String Greet(System.String, System.String) and System.String Greet(System.String) use the message name ‘Greet.’ Use the MessageName property of the WebMethod custom attribute to specify unique message names for the methods.

Transaction Support in Web Services The WebMethod attribute also has a property named TransactionOption that can be used in situations where Web services must execute a method within the context of transaction. Adding this property is similar to adding the Description property shown earlier because you simply append it to the WebMethod attribute and then set it equal to a custom enumeration value (TransactionOption.RequiresNew, for example). Doing this causes the appropriate Web service method to execute within the context of a transaction, as shown in Listing 10.8. LISTING 10.8 1: 2: 3: 4: 5: 6: 7: 8: 9:

Transaction Support in Web Services

using using using using

System.Web.Services; System.EnterpriseServices; System.Data; System.Data.SqlClient;

[WebService(Namespace=”http://www.TomorrowsLearning.com/Greeting”)]

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

LISTING 10.8

429

Continued

10: class DeleteData: WebService { 11: [WebMethod(TransactionOption=TransactionOption.RequiresNew)] 12: public int Delete(string sql) { 13: string connStr =”server=localhost;uid=sa;pwd=;database=Northwind”; 14: SqlConnection dataConn = new SqlConnection(connStr); 15: SqlCommand cmd = new SqlCommand(sql,dataConn); 16: try { 17: cmd.ExecuteNonQuery(); 18: return 0; 19: } 20: catch { 21: ContextUtil.SetAbort(); 22: return 1; 23: } 24: finally { 25: if (dataConn != null) dataConn.Close(); 26: } 27: } 28: }

Notice that to use the TransactionOption property, you must reference the System. assembly and namespace.

EnterpriseServices

State Management in Web Services State is not maintained by default when calls are made to Web services. As a result, the state of variables or objects that are instantiated by the Web service are not maintained across multiple Web service calls. Each object is instantiated on request and destroyed after the response has been returned. In cases where state must be maintained, the Application and Session objects can be used. To use these objects, a Web service class must subclass the System.Web.Service.WebService class. This was shown in the previous code examples. Although there may be many reasons that require a Web service to have built-in state management, the .NET SDK documentation provides an example similar to that shown in Listing 10.9 that serves the purpose of updating a simple counter. LISTING 10.9

Accessing Application State from a Web Service

ASP, NET, XML, SOAP, AND WEBSERVICES

1: 2: using System; 3: using System.Web.Services; 4:

10

430

XML Related Technologies

LISTING 10.9

Continued

5: [WebService(Namespace=”http://www.TomorrowsLearning.com/Counter”)] 6: public class Counter : WebService { 7: [WebMethod] 8: public int UpdateAppCounter() { 9: if (Application[“HitCounter”] == null) { 10: Application[“HitCounter”] = 0; 11: } 12: else { 13: Application.Lock(); 14: Application[“HitCounter”] = ((int) Application[“HitCounter”]) 15: + 1; 16: Application.UnLock(); 17: } 18: return Convert.ToInt32(Application[“HitCounter”]); 19: } 20: }

Because the Counter class has been subclassed, it now has access to Application state. In cases where access to session state is needed with a Web service, the code shown in Listing 10.10 can be used: LISTING 10.10 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18:

Accessing Session State from a Web Service

using System; using System.Web.Services; [WebService(Namespace=”http://www.TomorrowsLearning.com/Counter”)] public class Counter : WebService { [WebMethod(EnableSession=true)] public int UpdateSessionCounter() { if (Session[“HitCounter”] == null) { Session[“HitCounter”] = 0; } else { Session[“HitCounter”] = ((int) Session[“HitCounter”]) + 1; } return Convert.ToInt32(Session[“HitCounter”]); } }

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

431

Line 8 shows a new attribute named EnableSession that is set to true. Because Session state will oftentimes not be needed in Web services, its default value is false. It’s important to keep in mind that state management is not a part of any Web service specification. Because your Web services can be hit by a variety of clients on a multitude of platforms, it is recommended that you use state-management techniques (such as the Session object) sparingly and keep your Web services stateless when possible.

The .asmx Extension Web services running within the .NET framework are associated with a special file extension value of asmx rather than the standard aspx extension used for ASP.NET pages. Files with the asmx extension reference the System.Web.Services namespace and contain special keywords that allow classes within the file to be exposed as a Web service. Making the Web services shown in the previous listings available to the rest of the world is accomplished by naming each file with the .asmx extension. This extension is mapped to the WebServiceHandlerFactory class in the machine.config file, which takes care of serializing and deserializing messages. The section of the machine.config file that contains the appropriate mapping is shown next:

When a request comes to the server containing a path of *.asmx, the WebServiceHandlerFactory class is instantiated to process the request. When Listing 10.6 is saved with an .asmx extension and run, the following screen appears:

10

The Web service test screen.

ASP, NET, XML, SOAP, AND WEBSERVICES

FIGURE 10.2

432

XML Related Technologies

Without any coding on your part, the asmx file is dynamically compiled and a test page is generated. To try out the Greeting Web Service, click the Greet link shown in Figure 10.2, and on the next screen enter a name into the input box and hit the Invoke button. Doing this should display a result similar to that shown in Figure 10.3.

FIGURE 10.3 Invoking a Web service.

TIP A template file named DefaultWsdlHelpGenerator.aspx is used to generate the Web service test screen shown in Figure 10.2. By editing this file, you can easily customize the test screen to fit into the look and feel of your Web site.

Web Service Description Language (WSDL) Exposing a Web service that client applications throughout the world can use is certainly useful and full of potential. However, a method for querying what programmatic interfaces the Web service exposes and what functions it is capable of performing is essential in order to be consumed by a client. After all, sending messages to a remote object you know nothing about would prove to be rather futile. What’s a Web service to do?

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

433

This problem is solved through using an XML grammar titled Web Service Description Language, or WSDL. WSDL provides consumers of the Web service with detailed information about binding to the service. It also details what methods are accessible and the parameters and data types expected by those methods. The data type(s) of the response issued from each Web service method are also described. So how is all this information structured? Using XML syntax, of course. Looking back to the test Web service page shown in Figure 10.2, you’ll notice that a link is provided to the WSDL document that describes the Greeting Web service. Clicking this link results in the document shown in Listing 10.11.

NOTE Direct access to a given Web service’s WSDL document can be obtained by adding ?WSDL after the name of the asmx file. For example, the following URL will pull up the WSDL document for the Web service shown in Listing 10.6: http://localhost/testbed/Chapter10/listing10.6.asmx?WSDL

LISTING 10.11

WSDL Document Describing the Greeting Web Service

10 ASP, NET, XML, SOAP, AND WEBSERVICES

1: 2: 11: 12: 15: 16: 17: 18: 20: 21:

434

XML Related Technologies

LISTING 10.11 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65:

Continued

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

LISTING 10.11

Continued

10 ASP, NET, XML, SOAP, AND WEBSERVICES

66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85: 86: 87: 88: 89: 90: 91: 92: 93: 94: 95: 96: 97: 98: 99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109:

435

436

XML Related Technologies

LISTING 10.11

Continued

110: 111: 113: 114: 115: 117: 118: 119: 121: 122: 123:

This document describes three ways for interacting with the Web service: • SOAP •

HTTP-GET

•

HTTP-POST

Although each of the three sections described in the WSDL document exhibit different ways of describing the service, they all serve the purpose of providing the structure for the Web service request and response. The Element The type element serves as a container for an XSD schema that is used to define parameter names and data types used in the Web service. The schema it wraps is referenced by other elements within the WSDL document, as shown in the next few sections. The Element The message element is used to describe the content of the messages sent to and from the Web service. For the SOAP request, lines 34–39 are used to describe the input and response parameters using the message and part elements: 34: 35: 36: 37: 38: 39:

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

437

Looking at this section of code, you’ll see that each part element references an element described in the XSD schema contained within the type element (lines 11–33). This allows parameter names and data types to be defined using the XML schema standard. The Element The portType element defines the different operations that are supported by the Web service along with the message(s) involved with each operation. Looking at lines 52–57 (shown below), you will see that the message elements are referenced by a adding a message attribute to elements named input and output. These elements are wrapped by an operation element that defines the name of the method being called (Greet, in this example). All this information is wrapped by a portType element that has a name attribute: 52: 53: 54: 55: 56: 57:

The Element The binding element serves the purpose of specifying the protocol to be used with operations defined in the portType element and how SOAP messages should look on the wire: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84:

10 ASP, NET, XML, SOAP, AND WEBSERVICES

In line 70, the binding element’s type attribute references the GreetingSoap portType defined earlier. Lines 71 and 72 define the type of transport to be used (HTTP) and the “style” of the SOAP message. For this example a document style is being defined which lends itself well to XML documents being embedded in SOAP messages. The alternative is rpc, which would actually work fine with this simple Web service.

438

XML Related Technologies

The soap:body element appears within the input and output elements and serves the purpose of describing the content within the body of the SOAP message. This element can have use, encodingStyle, parts, and namespace attributes. The use attribute determines whether the content of the body is encoded. Optionally, a soap:header element could be included as a child of the input and output elements as well. The Element The service element references the different portType elements defined in the WSDL document and provides the address for accessing each one. When Web services expose multiple methods, several different portType and service elements may exist. 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122:

Now that you see how a client can learn about what capabilities a Web service has, it’s time to see how to consume the services offered by the Web service.

NOTE You can find the WSDL specification at http://msdn.microsoft.com/xml/general/ wsdl.asp.

Consuming a Web Service from an ASP.NET File Connecting to a Web service from a client application involves knowing about the services that the Web service is capable of performing. As shown in the previous section, this is accomplished through the creation of the WSDL document. After you know what the Web service offers, how can you invoke the service and use it on the client end? As with many remotemessaging architectures, a proxy can be created that emulates the remote object exposed by

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

439

the Web service to marshal data back and forth between the client and the Web service. The client application actually knows nothing about the remote Web service. Instead, it treats the proxy as if it were the real object performing the task. In turn, the proxy contacts the Web service and then passes the response back to the client. The process of creating a client proxy is shown next.

Creating a Client Proxy to Consume a Web Service Creating a proxy that acts as the middleman between a client and a Web service is accomplished by using a command-line utility named WSDL.exe, which ships with the .NET platform. Although you could create a proxy by hand (if you were really bored!), the WSDL.exe utility will import a WSDL file and create the necessary proxy for you. To do this, you pass the path to the WSDL file and specify a few switch options: wsdl [options] {URL | path}

Table 10.5 shows the switch options documented in the .NET SDK documentation. TABLE 10.5

WSDL.exe Switch Options

Option

Description

/appsettingurlkey:key

Specifies the configuration key to use to read the default value for the URL property when generating code.

or

/urlkey:key /appsettingbaseurl:baseurl

or /baseurl:baseurl

/d[omain]:domain /l[anguage]:language

/n[amespace]:namespace

10 ASP, NET, XML, SOAP, AND WEBSERVICES

/no[backup]

Specifies the base URL to use when calculating the URL fragment. The tool calculates the URL fragment by converting the relative URL from the baseurl argument to the URL in the WSDL document. You must specify the /appsettingurlkey option with this option. Specifies the domain name to use when connecting to a server that requires authentication. Specifies the language to use for the generated proxy class. You can specify CS (C#; default), VB (Visual Basic), or JS (JScript) as the language argument. You can also specify the fully qualified name of a class implementing System.CodeDom.Compiler.CodeDomProvider. Specifies the namespace for the generated proxy or template. The default namespace is the global namespace. Overwrites the existing output file. The default is to produce a backup (.bak) file.

440

XML Related Technologies

TABLE 10.5

Continued

Option

Description

/nologo

Suppresses the Microsoft startup banner display. Specifies the file in which to save the generated proxy code. The tool derives the default filename from the Web service name. The tool saves generated datasets in different files. Specifies the password to use when connecting to a server that requires authentication. Specifies the protocol to implement. You can specify SOAP (default), HttpGet, HttpPost or a custom protocol specified in the configuration file. Specifies the URL of the proxy server to use for HTTP requests. The default is to use the system proxy setting. Specifies the domain to use when connecting to a proxy server that requires authentication.

/o[ut]:filename

/p[assword]:password /protocol:protocol

/proxy:URL /proxydomain:domain

or /pd:domain /proxypassword:password

or

Specifies the password to use when connecting to a proxy server that requires authentication.

/pp:password /proxyusername:username

or

Specifies the username to use when connecting to a proxy server that requires authentication.

/pu:username /server /u[sername]:username /?

Generates an abstract class for a Web service based on the contracts. The default is to generate client proxy classes. Specifies the username to use when connecting to a server that requires authentication. Displays command syntax and options for the tool.

To generate a proxy for the Web service shown back in Listing 10.6, the following commandline code can be used. Because no language switch is specified, C# code will be generated by default: wsdl /out:greetingProxy.cs ➥http://localhost/testbed/chapter10/listing10.6.asmx?WSDL ➥/n:Greeting

Executing this statement on the command line will result in the creation of the C# document shown in Listing 10.12.

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

LISTING 10.12

Proxy Code Generated by the WSDL Utility

//------------------------------------------------------------------// // This code was generated by a tool. // Runtime Version: 1.0.2914.11 // // Changes to this file may cause incorrect behavior and // will be lost if the code is regenerated. // //------------------------------------------------------------------// // This source code was auto-generated by wsdl, Version=1.0.2914.11. // namespace Greeting { using System.Diagnostics; using System.Xml.Serialization; using System; using System.Web.Services.Protocols; using System.Web.Services;

[System.Web.Services.WebServiceBindingAttribute(Name=”GreetingSoap”, Namespace=”http://www.TomorrowsLearning.com/Greeting”)] public class Greeting : System.Web.Services.Protocols.SoapHttpClientProtocol { [System.Diagnostics.DebuggerStepThroughAttribute()] public Greeting() { this.Url = “http://localhost/testbed/chapter10/listing10.6.asmx”; } [System.Diagnostics.DebuggerStepThroughAttribute()] [System.Web.Services.Protocols.SoapDocumentMethodAttribute( “http://www.TomorrowsLearning.com/Greeting/Greet”, RequestNamespace=”http://www.TomorrowsLearning.com/Greeting”, ResponseNamespace=”http://www.TomorrowsLearning.com/Greeting”, Use=System.Web.Services.Description.SoapBindingUse.Literal, ParameterStyle= System.Web.Services.Protocols.SoapParameterStyle.Wrapped)] public string Greet(string name) { object[] results = this.Invoke(“Greet”, new object[] { name}); return ((string)(results[0]));

10 ASP, NET, XML, SOAP, AND WEBSERVICES

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44:

441

442

XML Related Technologies

LISTING 10.12 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: }

Continued

} [System.Diagnostics.DebuggerStepThroughAttribute()] public System.IAsyncResult BeginGreet(string name, System.AsyncCallback callback, object asyncState) { return this.BeginInvoke(“Greet”, new object[] { name}, callback, asyncState); } [System.Diagnostics.DebuggerStepThroughAttribute()] public string EndGreet(System.IAsyncResult asyncResult) { object[] results = this.EndInvoke(asyncResult); return ((string)(results[0])); } }

Although the specifics of this file will not be discussed, you can see that the code specifies the URL of the Web service (line 30) and then emulates the remote Web service object by creating a Greet() method structure (lines 41–45). Depending on how complex the Web service is that you need to create a proxy for, you can see that the WSDL utility is a big time-saver after you know how to work with the switches! To compile the proxy code into an assembly that can be used within an ASP.NET page, the following statement can be run from the command line (C# compile switches shown): csc /t:library /r:system.web.services.dll /r:system.xml.dll ➥/out:d:\inetpub\wwwroot\testbed\bin\greetingProxy.dll greetingProxy.cs

TIP Although not shown in this section, the WSDL.exe utility can also be used to create a WSDL file and perform other tasks. This is accomplished by using the switches shown in Table 10.5.

Calling a Web Service from an ASP.NET Page After a proxy has been created that can connect a client to a Web service, it can be used within an ASP.NET page. Doing this simply requires that you import the proper namespace contained within the proxy assembly that was generated earlier (greetingProxy.dll, which has a Greeting namespace). Listing 10.13. shows how the proxy can be used to hit the Web service and then write out the return results to an ASP.NET page.

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

LISTING 10.13 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24:

443

Using the Proxy Assembly Within an ASP.NET Page

public void submitButton_Click(Object Src, EventArgs E) { Greeting.Greeting objGreet = new Greeting.Greeting(); wsResults.InnerHtml = objGreet.Greet(myName.Value); } Hitting the Greeting Web Service From an ASP.NET Page Enter your Name:

Value returned from Greeting Web Service:

On entering a value into the text box and hitting the Submit button, the submitButton_Click event handler is called (line 2). This handler instantiates the proxy created earlier and then passes the value in the text box to the Greet() method (lines 3 and 4). From here, the proxy takes care of serializing and deserializing the request and response message to and from the Web service. This is shown in Figure 10.4.

10

Hitting a Web service from an ASP.NET page.

ASP, NET, XML, SOAP, AND WEBSERVICES

FIGURE 10.4

444

XML Related Technologies

Web Service Discovery Now that you’ve seen the different steps that must be taken to create a Web service and client proxy, you may wonder how you can find someone else’s service to use within an ASP.NET application. For Web services to be useful, their service description document must be located. Although the .NET platform has support for the Discovery of Web Services (DISCO), Microsoft is now collaborating with more than 36 other companies to create a universal directory of Web services. This directory service is being termed Universal Description, Discovery, and Integration (UDDI). Although a complete discussion of UDDI is beyond the scope of this chapter, more information on this evolving specification can be found at http:// www.uddi.org. Now that you’ve seen all the pieces that come into play when building or consuming a Web service, the following section provides a simple example of how Web services can be used to solve legitimate business problems.

Retrieving Customer Orders Through a Web Service In this section of the chapter, you’ll be introduced to a fictitious Web service for a company named ACME Distribution. After the service’s purpose has been outlined, you’ll be provided with a description of the code used to construct it.

Web Service Description Wahlin’s Widgets sells a variety of products through its Web site. The site allows customers to browse through a product catalog, place orders, and check the status of orders. Rather than carrying an inventory and handling the shipment of customer orders, Wahlin’s Widgets has a contract with ACME Distribution, Inc., a distribution center that takes care of stocking and shipping the products. Accessing the catalog of products supplied by ACME Distribution is accomplished via FTP access to an XML document on a server owned by ACME Distribution. After the document is retrieved, the data within it is imported into a SQL Server 2000 database owned by Wahlin’s Widgets. This allows customers to access product information quickly and allows Wahlin’s Widgets to have complete control over how the products are presented to the customers. Because the product catalog is only updated on a weekly basis, this method is sufficient for the time being. After a customer views the products available on the Wahlin’s Widgets Web site, the customer can place an order for the item. This order is then transmitted via FTP to a server located at one of ACME’s distribution centers. Because of the time it takes to send this order information

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

445

between the companies, Wahlin’s Widgets is not able to provide customers with instant feedback on whether a particular product is in stock. As a result, customer orders for products that are not currently in stock at the distribution center may be delayed for lengthy amounts of time. When this situation occurs, Wahlin’s Widgets receives notification from an ACME distribution center and lets the customer know via e-mail that the shipment of their product may be delayed. Although this methodology works, there have been many customer complaints and order cancellations because of unsatisfied customers. To remedy this situation, Wahlin’s Widgets has worked with ACME Distribution to develop a new strategy for checking inventory in a more timely fashion. The two companies have also agreed to provide customers with the capability to check the status of orders and double-check that orders were shipped to the proper address. Because ACME Distribution acts as the distribution center for several other companies, it has agreed to create a Web service that can be used to check product availability and shipping status so that customers can get immediate feedback.

Creating the ACME Distribution, Inc. Web Service ACME realized that it needed to provide “live” feedback to different companies about the availability of specific products within its warehouse. While building the Web service to accomplish this task, ACME also provided functionality that allowed customers to check the status of an order. The implementation of these features into a Web service is shown in Listing 10.14. LISTING 10.14

using System.Data; using System.Data.SqlClient; using System.Web.Services; [WebService(Namespace=”http://www.ACMEDistribution.com/Products”)] public class ACMEProducts: WebService { [WebMethod(Description=”This method allows access “ + “ to product stock numbers”)] public DataSet CheckStock(int productID) { string sql = @”SELECT ProductName,UnitsInStock, UnitsOnOrder, Discontinued FROM Products WHERE ProductID = ‘“ + productID + “‘“; DataSet dsProductStatus = getDataSet(sql,”ProductQuantity”); return(dsProductStatus); }

10 ASP, NET, XML, SOAP, AND WEBSERVICES

1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17:

ACME Distribution Web Service

446

XML Related Technologies

LISTING 10.14 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61:

Continued

[WebMethod(Description=”This method allows access to “ + “ order status information”)] public DataSet GetOrders(string CustomerID) { string sql = @”SELECT ShipName,ShipAddress,ShipCity,ShippedDate FROM Orders WHERE CustomerID = ‘“ + CustomerID + “‘“; DataSet dsOrders = getDataSet(sql,”Orders”); return(dsOrders); } [WebMethod(Description=”This method allows selection of “ + “products by name”)] public DataSet GetProductByName(string productName) { string sql = @”SELECT ProductID,ProductName,UnitPrice, QuantityPerUnit FROM Products WHERE ProductName LIKE ‘“ + productName + “%’”; DataSet dsProducts = getDataSet(sql,”Products”); return(dsProducts); } [WebMethod(Description=”This method allows selection of “ + “products by ID”)] public DataSet GetProductByID(int id) { string sql = @”SELECT ProductID,ProductName,UnitPrice, QuantityPerUnit FROM Products WHERE ProductID = “ + id; DataSet dsProducts = getDataSet(sql,”Products”); return(dsProducts); } [WebMethod(Description=”This method allows selection of “ + “all products”,CacheDuration=120)] public DataSet GetProducts() { string sql = “SELECT ProductID,ProductName FROM Products”; DataSet dsProducts = getDataSet(sql,”Products”); return(dsProducts); } private DataSet getDataSet(string sql, string tableName) { string SQLconnStr = “server=localhost;uid=sa;” + “pwd=;database=Northwind”; DataSet ds = new DataSet(); SqlConnection dataConn = new SqlConnection(SQLconnStr); SqlDataAdapter dsAdapter = new SqlDataAdapter(sql,dataConn); dsAdapter.Fill(ds, tableName); dataConn.Close();

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

LISTING 10.14 62: 63: 64: }

447

Continued

return(ds); }

This Web service exposes several methods that return records from the ACME database, including: •

CheckStock()

•

GetOrders()

•

GetProducts()

•

GetProductByID()

•

GetProductByName()

Consuming the ACME Distribution, Inc. Web Service After ACME Distribution’s Web service was online and available to use, Wahlin’s Widgets ran the following statements at the command prompt. The WSDL.exe portion of the commands use ACME’s WSDL document to create a client proxy: wsdl /out:d:\temp\acmeProxy.cs /n:ACME.Distribution ➥http://localhost/testbed/chapter10/listing10.14.asmx?WSDL csc /t:library /r:system.web.services.dll /r:system.xml.dll ➥/r:system.data.dll /out:d:\inetpub\wwwroot\testbed\bin\acmeProxy.dll ➥d:\temp\acmeProxy.cs

After the proxy was completed, Wahlin’s Widgets created an ASP.NET file that used the proxy to communicate with ACME Distribution’s Web service via SOAP messages. Listing 10.15 shows a portion of the ASP.NET page code. LISTING 10.15

ASP.NET Application Using ACME’s Web Service

10 ASP, NET, XML, SOAP, AND WEBSERVICES

1: 2: 3: 4: public void Page_Load(Object Src, EventArgs E) { 5: string id = Request.QueryString[“id”]; 6: string order = Request.QueryString[“placeOrder”]; 7: if (!IsPostBack && id==null && order==null) { 8: ShowHidePanels(“pnlSplash”); 9: } else { 10: ShowHidePanels(“”);

448

XML Related Technologies

LISTING 10.15 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51:

Continued

} if (id != null) { CheckStock(Convert.ToInt32(id)); } if (order != null) { PlaceOrder(order); } } public void GetOrderStatus_Click(Object Src, EventArgs E) { ShowHidePanels(“pnlOrderStatus”); ACME.Distribution.ACMEProducts custOrders = new ACME.Distribution.ACMEProducts(); DataSet ds = custOrders.GetOrders(customerID.Value); OrdersDataGrid.DataSource=ds.Tables[0].DefaultView; OrdersDataGrid.DataBind(); } public void PlaceOrder(string order) { ShowHidePanels(“pnlPlaceOrder”); lblPlaceOrder.Text = “

Your order has been placed “ + “for product ID: “ + order + “”; } public void CheckStock(int productID) { ShowHidePanels(“pnlStock”); ACME.Distribution.ACMEProducts custOrders = new ACME.Distribution.ACMEProducts(); DataSet ds = custOrders.CheckStock(productID); StockDataGrid.DataSource=ds.Tables[0].DefaultView; StockDataGrid.DataBind(); } public void ProductSubmit_Click(Object Src, EventArgs E) { ShowHidePanels(“pnlProducts”); ACME.Distribution.ACMEProducts custOrders = new ACME.Distribution.ACMEProducts(); DataSet ds = custOrders.GetProductByName(txtProductName.Text); ProductsDataGrid.DataSource=ds.Tables[0].DefaultView; ProductsDataGrid.DataBind(); } public void CheckOrderStatusLink_Click(Object Src, EventArgs E) { ShowHidePanels(“pnlCheckOrder”);

Working with ASP. NET, XML, SOAP, and Web Services CHAPTER 10

LISTING 10.15

449

Continued

52: } 53: public void BrowseProductsLink_Click(Object Src, EventArgs E) { 54: ShowHidePanels(“pnlBrowseProducts”); 55: ACME.Distribution.ACMEProducts prods = 56: new ACME.Distribution.ACMEProducts(); 57: DataSet ds = prods.GetProducts(); 58: DataView dv = ds.Tables[0].DefaultView; 59: lstProducts.DataSource = dv; 60: lstProducts.DataBind(); 61: } 62: public void lstProducts_Select(Object Src, EventArgs E) { 63: ShowHidePanels(“pnlProducts”); 64: ACME.Distribution.ACMEProducts custOrders = 65: new ACME.Distribution.ACMEProducts(); 66: DataSet ds = custOrders.GetProductByID( 67: Convert.ToInt32(lstProducts.SelectedItem.Value)); 68: ProductsDataGrid.DataSource=ds.Tables[0].DefaultView; 69: ProductsDataGrid.DataBind(); 70: } 71: public void ShowHidePanels(string panel) { 72: Control ctl = null; 73: Control frm = Page.FindControl(“frmWidgets”); 74: int ctlsCount = frm.Controls.Count; 75: for (int i=0;i (greater than) character, 36, 96 0 value, 386 1 value, 386 2 value, 386 8 value, 386

A abbreviations, XPath, 66, 68-69 abort( ) method, 213 AcceptChanges( ) method, 334 accessing application state, Web services, 429-430 MSXML3 through Interop, 179, 181 nodes, XPointer , 76 return values, Extensible Stylesheet Language Transformations (XSLT) templates, 266-267 session state, Web services, 430 stored procedures, Command class, 300-301, 303, 305 ActiveX Data Objects (ADOs) vs. ADO.NET, 294-295 actor attribute, 409 actuate attribute, 81-82 Add( ) method, 161 AddExtensionObject(namespace,URI,object) method, 277 adding comments, eXtensible Markup Language (XML), 35 database records, 389-394 descriptions, Web service classes and methods, 427 eXtensible Markup Language (XML) data into tables, OPENXML rowset provider, 387 external objects to XsltArgumentList class, 283-284 nodes, XmlDocument class, 196-200

reusable classes, Extensible Stylesheet Language Transformations (XSLT), 287-290 simple links, XLink documents, 82 AddNode( ) method, 230-231 AddParam( ) method, 277-278 address element, 261 ADO. See ActiveX Data Objects ADO.NET classes, Extensible Stylesheet Language Transformations (XSLT), 272-273, 275-277, 279-282, 284-285, 287 DataSet class, 295, 306-308, 310-314, 316-317, 319-324, 326, 328-332, 334, 336-344, 346-348 managed providers, 296-301, 303, 305-307 using with SQL Server 2000, 394-396, 398 vs. classic ActiveX Data Objects (ADOs), 294-295 XmlDataDocument class, 324, 326, 328-332, 334, 336-344, 346-348 after tag, 390 aliases, providing to overloaded methods, 428 all element, 122 Allow URL Queries check box, 364 ampersand (&) character, 38, 40 ancestor axis, 56 ancestor-or-self axis, 56 annotations, XDR schema, 369-370, 372-374 AppendChild( ) method, 185, 191 appending information to documents with standard ASP.NET classes, 46-48

attributes

application state, accessing in Web services, 429-430 applications building, ASP.NET objects, 44-45, 47-50 converting from ASP to ASP.NET, 180-181 converting to true eXtensible Markup Language (XML) applications, 225-227, 229-231 creating, Extensible Stylesheet Language Transformations (XSLT), 278-281 hierarchical eXtensible Markup Language (XML) menu, creating, 219, 222-223, 225 sharing data between, 7 applying default namespaces to elements, 29-30 arc element, 84-86 arc keyword, 79 architecture, Web services, 423-424 arcrole attribute, 80 arguments, AddNode( ) method, 231 ArrayList class, 221 arrays, 417-419 arrayType attribute, 417 ASP, converting applications to ASP.NET from, 180-181 asp:Xml Web control, 289290 ASP.NET calling Web services from, 442-443 capturing data, 226-227, 229 consuming Web services, 438-442, 444 converting applications from ASP to, 180-181 eXtensible Markup Language (XML) templates, 367-368

sending data to eXtensible Markup Language (XML) templates, 388-389 updating, inserting, and deleting database records, 389-394 XsltTransform class, 289 ASP.NET objects, generating eXtensible Markup Language, 44-45, 47-50 ASP.NET pages calling SAXParser class from, 158-159 calling Validator class from, 165 assemblies compiling proxy code into, 442 referencing, XmlText Reader class, 152 System.Xml, Document Object Model (DOM) classes, 182-183 asterisk (*), 58, 96 at (@) symbol, 66 at-identity attribute, 390-391 attaching event handlers, XmlValidatingReader class, 161-162 attribute axis, 56 attribute element, 116 attribute tag, 111 Attribute value, 339 AttributeCount property, 139 attributeFormDefault attribute, 129 attributes actor, 409 actuate, 81-82 arcrole, 80 arrayType, 417 at-identity, 390-391 attribute tag, 111 attributeFormDefault, 129 AttributeType tag, 110-111 CDATA, 97 color, 25

content, 106 CustID, 380 dataFld, 217 dataSrc, 217 default, 110-111 described, 25, 27 disable-output-escaping, 253 Document Type Definition (DTD), 97-99 dt:type, 107, 111, 113 dt:values, 111 element tag, 108-109 elementFormDefault, 129 ElementType tag, 106-107 Enumeration, 98 Envelope element, 407-408 eXtensible Markup Language (XML), mapping fields to, 339-341 foreign-relation, 373 form, 129 from, 81, 85 Header element, 409-410 href, 80, 82, 417 ID, 98, 229-230, 390, 417 IDREF/IDREFS, 98 indent, 250 itemNumber, 25 key, 373 key-relation, 373 label, 81, 85 mapping-schema, 376 match, 251 maxOccurs, 109 minOccurs, 108 mode, 252 model, 106 mustUnderstand, 409-410 name, 106, 110, 252, 257, 263, 266, 276 naming, 25 NMTOKEN/NMTOKENS, 99 noNamespaceSchemaL ocation, 130 NOTATION, 99 omit-xml-declaration, 260 order, 107

453

454

attributes

OrdID, 379-380 passing automatically, 145 priority, 252 quoted, 10 quoting, 20 recordsets with, 26 ref, 116 required, 110-111 returnid, 390-391 role, 81 schemaLocation, 130 select, 252-253, 255-256, 263-266, 276 setting to preserve and default, 42 show, 81 src, 7 style, 256 targetNamespace, 128-130 test, 252, 256 title, 81 to, 81, 85 type, 81-82, 85, 108, 111 value, 120 version, 242-243 vspace, 7 Web services, 424-432, 434-438 WebMethod, 426-429 WebService, 426-427 when required for elements, XLink, 87-88 XLink, 80-81, 87-88 XML Data – Reduced (XMLDR) schema, 106-111 XML schema, 116 xml:space, 42 xsl:template element, 251-252 Attributes class, 154 Attributes property, 184, 189 AttributeType element, 116, 121 AttributeType tag, 110-111 authentication credentials, passing, 166 AUTO keyword, 354-355

Auto member, ValidationType enumerations, 160-161 axes, 56, 59, 66 axis types, XPath, 55-57

B bare names, identifying fragments with, 75 BaseURI property, 139, 184, 190 before tag, 390 bin.base64 data type, 112 bin.hex data type, 112 BINARY BASE64 keyword, 363 binding DataSets to DataGrids, 318-320 binding element, 437-438 bit shifting, 23 blocks, catch and finally, 158 Body element, 410-414 boolean data type, 112 boolean functions, 65-66 boolean(value) function, 65 brackets, curly ({}), 263 browsers entity, 36 creating eXtensible Markup Language (XML) document structures, 205, 207-209 Internet Explorer validating eXtensible Markup Language (XML) documents, 92 xml:space attribute, 42 BufferResponse property, 425 building applications, Extensible Stylesheet Language Transformations (XSLT), 278-281 client proxies, 439-442

comments, eXtensible Markup Language (XML), 35 DataSet mappings, eXtensible Markup Language (XML), 343-345 Document Object Model (DOM) structures, 183 Document Type Definition (DTD) syntax, ease of, 90 eXtensible Markup Language (XML) applications, ASP.NET objects, 44-45, 47-50 eXtensible Markup Language (XML) documents, XmlTextWriter class, 166, 168-169, 172-173 generic validation classes, 162-165 hierarchical eXtensible Markup Language (XML) menu applications, 219, 222-223, 225 hierarchical relationships, DataSets, 345-348 Hypertext Markup Language (HTML) pages to view user entries, 211, 214-219 nodes, XmlDocument class, 196-200 reusable classes, Extensible Stylesheet Language Transformations (XSLT), 287-290 SAX-style push models, XmlTextReader class, 145, 147, 149-154, 156-159 structures, eXtensible Markup Language (XML) documents, 205, 207-209 unique fields, keys, and relationships with XML schema, 124-125, 127-128 Web services, 445-447 XML fragments, XmlTextWriter class, 198-199

classes

C CacheDuration property, 425 Call element, 410-411 calling external objects within XSLT stylesheets, 284-286 SAXParser class from ASP.NET pages, 158-159 stored procedures, eXtensible Markup Language (XML) templates, 366 Validator class from ASP.NET pages, 165 Web services from ASP.NET pages, 442-443 CanResolveEntry property, 139 capturing data, eXtensible Markup Language (XML) and ASP.NET, 226-227, 229 case sensitivity eXtensible Markup Language (XML), 20 parameters, eXtensible Markup Language (XML) templates, 366 tags, 10 case statement, 154, 156 catch block, 158 catching errors, XmlTextReader class, 157-158 CDATA attribute, 97 cdata directive, EXPLICIT mode queries, 382 CDATA (character data) sections, 40-41 ceiling(number) function, 65 changing color attribute to element, 25 database records, 389-394 links, Hypertext Markup Language (HTML) documents, 86

char data type, 112 character data (CDATA) sections, 40-41 Character Entities, 37-38 character points, 71 characters, Document Type Definition (DTD) elements, 96 checking element nodes, XmlTextReader class, 154, 156 eXtensible Markup Language (XML) documents, 20-21 validity, eXtensible Markup Language (XML) documents, 92 child axis, 56, 59 child elements, 53. See also nodes child sequence numbers, 76 child sequences, identifying fragments with, 76 ChildNodes property, 184, 188, 190 Chinese language, 23 choice element, 121-122 choosing nodes SelectSingleNode( ) method, 218-219 XPath, 204-205 classes ADO.NET, Extensible Stylesheet Language Transformations (XSLT), 272-273, 275-277, 279-282, 284-285, 287 ArrayList, 221 Attributes, 154 Command, 298-303, 305-306 ContentHandler, 159 CredentialCache, 166 DataAdapter, 306 DataReader, 300, 303, 306 DataRelation, 361

DataSet, 295, 306-308, 310-314, 316-317, 319-324, 326, 328-332, 334, 336-344, 346-348, 358-362 Date/Time extension, 282 Document Object Model (DOM), System.Xml namespace and assembly, 182-183 EdiToXml, 173 generic validation, creating, 162-165 HashTable, 278 NetworkCredential, 166 OleDbCommand, 299-300, 304-305 OleDbConnection, 297-298 OleDbDataAdapter, 306-307 OleDbDataReader, 300 Relation, 347 reusable, creating, 287-290 SAXParser, 152, 158-159 SqlCommand, 298-299, 301-302 SqlConnect, 310-311, 313-314, 317 SqlConnection, 296-297 SqlDataAdapter, 306-307 SqlDataReader, 300 standard ASP.NET, appending information to documents, 46-48 StreamReader, 173, 318 StreamWriter, 221 Validator, 162-165, 205, 207209 Web services, adding descriptions to, 427 WebMethodAttribute, 425 WebServiceAttribute, 426 XmlAttribute, 182, 188 XmlAttributeCollection, 201, 204 XmlCDataSection, 188 XmlComment, 188

455

456

classes

XmlDataDocument, 273, 324, 326, 328-332, 334, 336-344, 346-348 XmlDocument, 182, 189-195, 197-200, 205, 207-209, 272 XmlDocumentFragment, 188 XmlDocumentType, 188 XmlElement, 182, 189 XmlEntity, 189 XmlEntityReference, 189 XmlMenu, 221 XmlNamedNodeMap, 182, 201-202, 204-205, 207-209 XmlNameTable, 145 XmlNode, 182-189, 205, 207-209 XmlNodeList, 182, 200-201 XmlNodeReader, 183, 209-210 XmlNotation, 189 XmlParserContent, 396, 398 XmlProcessingInstruction, 189 XmlSchemaCollection, 161 XmlText, 189 XmlTextReader building SAX-style push models, 145, 147, 149-154, 156-159 creating eXtensible Markup Language (XML) document structure, 205, 207-209 in-memory vs. forwardonly parsing, 135-137 parsing eXtensible Markup Language (XML), 138145 passing authentication credentials, 166 push vs. pull models, 137-138 System.Xml assembly, 134135

validating eXtensible Markup Language (XML) documents, 159-162 vs. Document Object Model (DOM), 179 XmlTextWriter creating eXtensible Markup Language (XML) documents, 166, 168-169, 172-173 creating XML fragments, 198-199 in-memory vs. forwardonly parsing, 135-137 push vs. pull models, 137-138 System.Xml assembly, 134-135 XmlValidatingReader, validating eXtensible Markup Language (XML) documents, 159-162 XPathDocument, 273, 275, 358 XsltArgument List, 273 XsltArgumentList, 276-278, 283-284 XslTransform, 240-241, 273, 275-276 XsltTransform, ASP.NET, 289 clauses, WHERE, 58, 365-366 clearing namespaces, 33 Client code, 414 client proxies, creating, 439-442 Clone( ) method, 185, 191 CloneNode(( ) method, 185, 191 Close( ) method, 141 closed model, 107 closing tags, 9-10, 18-19 COBRA (Common Object Request Broker Architecture), 401

code listings asp:Xml Web control, 289-290 classes DataSet, 329-334 Date/Time extension, 282 generic validation, 163164 OleDbCommand, 299-300, 304-305 SAXParser, in ASP.NET pages, 158, 162-165, 167-168, 170-173 SqlCommand, 301-302, 298-299 Validator, calling from ASP.NET pages, 165 XmlDataDocument, 325334 XmlDocument, 197-199 XmlNamedNodeMap, 202-203 XmlNode, property examples, 187 XmlNodeReader, 209-210 XmlParserContext, 397398 XpathDocument, instantiating, 274-275 XmlTextReader, 142-144, 149-152 XmlTextWriter class, 198-199 XsltArgumentList, adding external objects to, 283284 XslTransform, 240-241, 276 XsltTransform, 289 creating Simple API for XML (SAX), 147-149 creating Simple API for XML (SAX) parsers,149-152 DataSets binding to DataGrids, 318-320

code listings

creating hierarchical relationships, 346-347 filling with data, 309-310 filling with multiple tables, 311-313 mapping XSD schema to, 341-343 viewing as eXtensible Markup Language (XML), 315-317 Deletegrams, 392 directives in EXPLICIT mode queries, 382-383 Document Type Definition (DTD) documents, 104-105 EXPLICIT mode query, 378 extending complex types, 123 eXtensible Markup Language (XML) capturing data, 226-227, 229 converting Electronic Data Interface (EDI) to, 172-173 creating fragments, XmlTextWriter class, 198-199 data generated by WriteXml( ) method, 321-322 data generated by WriteXmlSchema( ) method, 322-324 generating, XmlTextWriter class, 168 inserting data into tables, OPENXML rowset provider, 387 loading data directly from SQL Server, 358-360 loading element data, drop-down boxes, 214217 mapping fields to attributes, 339-341 schema, 114-115, 125-127 transforming, 281, 395

viewing DataSets as, 315-317 eXtensible Markup Language (XML) documents creating structure of, 205208 embedding XPath queries into, 375-376 inferring DataSet schema from, 344-345 parsing, 181 samples of, 93-95, 102, 124, 237-238, 240-241, 246-249, 258-259 schema, 103 shredding, OPENXML rowset provider, 385-386 transforming Extensible Stylesheet Language Transformations (XSLT) into, 259-260 eXtensible Markup Language (XML) templates ASP.NET page for sending data to, 388-389 calling stored procedures, 366 embedding XPath queries into, 375-376 examples of, 364-365 in ASP.NET, 367-368 specifying parameters, 365-366 Extensible Stylesheet Language Transformations (XSLT) calling external objects within stylesheets, 284-286 document examples, 260 reusable classes, 287-288 transforming from eXtensible Markup Language (XML), 259-260

IContentHandler interface, 146-147 methods CreateMenu( ) method, 222-223, 225, 227-229 ExecuteXmlReader( ), 394-395 overloaded, providing aliases to, 428 Page Load event and FillDropDown( ), 280 SelectSingleNode( ), 218-219 WalkTree( ), 224-225 nodes adding, XmlDocument class, 197-199 selecting, SelectSingleNode( ) method, 218-219 operations Insert, 391 Delete, 392 Update, 392 parameters in XPath query templates, 376 Updategrams, 393 properties, XmlNode class, 187 proxy assembly in ASP.NET page, 443 proxy code generated by WSDL.exe , 441-442 purchase order Electronic Data Interface (EDI) documents, 170 schema eXtensible Markup Language (XML) documents, 103 eXtensible Markup Language (XML), 114-115, 125-127 Northwind mapping, 370-372

457

458

code listings

Simple Object Access Protocol (SOAP) messages, 405-407 Simple Object Access Protocol (SOAP) responses with embedded fault information, 412-413 responses, serialized GetOrders( ) method, 411-413 serialization of GetName( ) method into structure of, 404 serialization of GetOrders( ) method into messages from, 411 stored procedures accessing, OleDbCommand class, 304-305 accessing, SqlCommand class, 301-302 calling, eXtensible Markup Language (XML) templates, 366 Updategrams, 389-392 URL-encoding, 356-357 Web Service Description Language (WSDL) document, 433-436 Web services accessing states, 429-430 ASP.NET applications with, 447-449 example of, 445-447 greeting, 426 transaction support, 428-429 codes, Fault element, 414 coding eXtensible Markup Language (XML), 16-20 collapsed ranges, 71 colons (:), root elements, 54 color attribute, 25 ColumnMapping property, 339-341

comma-delimited files, marking up in eXtensible Markup Language (XML), 5-6 Command class, 298-303, 305-306 commands, 422-423 CommandType property, 302 comment( ) node test, 58 comments, 34, 113 Common Object Request Broker Architecture (COBRA), 401 compiling proxy code into assemblies, 442 complexType element, declaring, 120-124 components, sharing data between, 7 compound data types, Simple Object Access Protocol (SOAP), 417, 419 computers, text storage, 23 concat(string1,string2,string 3, ...) function, 62 configuring handlers, XmlTextReader class, 153 SQL Server virtual directories, Internet Information Server (IIS), 351-353 constructing applications, Extensible Stylesheet Language Transformations (XSLT), 278-281 client proxies, 439-442 comments, eXtensible Markup Language (XML), 35 DataSet mappings, eXtensible Markup Language (XML), 343-345 Document Object Model (DOM) structures, 183 Document Type Definition (DTD) syntax, ease of, 90

eXtensible Markup Language (XML) applications, ASP.NET objects, 44-45, 47-50 eXtensible Markup Language (XML) documents, XmlTextWriter class, 166, 168-169, 172-173 generic validation classes, 162-165 hierarchical eXtensible Markup Language (XML) menu applications, 219, 222-223, 225 hierarchical relationships, DataSets, 345-348 Hypertext Markup Language (HTML) pages to view user entries, 211, 214-219 nodes, XmlDocument class, 196-200 reusable classes, Extensible Stylesheet Language Transformations (XSLT), 287-290 SAX-style push models, XmlTextReader class, 145, 147, 149-154, 156-159 structures, eXtensible Markup Language (XML) documents, 205, 207-209 unique fields, keys, and relationships with XML schema, 124-125, 127-128 Web services, 445-447 XML fragments, XmlTextWriter class, 198-199 constructors vReader, 165 XPathDocument class, 274 consuming Web services, 438-442, 447-450 contactName node, 229 contains(string1, string2) function, 62 content attribute, 106

data

content models, 96, 120 ContentHandler class, 159 context node, 55, 57, 66, 253 controls asp:Xml, 289-290 DataGrid WebControl, 318-320, 334 converting applications from ASP to ASP.NET, 180-181 to true eXtensible Markup Language (XML) applications, 225-227, 229-231 Electronic Data Interface (EDI) and legacy data to eXtensible Markup Language (XML), 169, 172-173 Count property, 200, 202 count( ) function, 60, 252 courseDifficulty element, 122 CreateAttribute( ) method, 191 CreateCDataSection( ) method, 191 CreateComment( ) method, 191 CreateDocumentFragment( ) method, 191 CreateDocumentType( ) method, 192 CreateElement( ) method, 192 CreateEntityReference( ) method, 192 CreateMenu( ) method, 221-224 CreateNavigator( ) method, 185, 192, 273 CreateNode( ) method, 192 CreateProcessingInstruction( ) method, 192 CreateSignificantWhiteSpace ( ) method, 192 CreateTextNode( ) method, 192

CreateWhitespace( ) method, 192 CreateXmlDeclaration( ) method, 192 creating applications, Extensible Stylesheet Language Transformations (XSLT), 278-281 client proxies, 439-442 comments, eXtensible Markup Language (XML), 35 DataSet mappings, eXtensible Markup Language (XML), 343-345 Document Object Model (DOM) structures, 183 Document Type Definition (DTD) syntax, ease of, 90 eXtensible Markup Language (XML) applications, ASP.NET objects, 44-45, 47-50 eXtensible Markup Language (XML) documents, XmlTextWriter class, 166, 168-169, 172-173 generic validation classes, 162-165 hierarchical eXtensible Markup Language (XML) menu applications, 219, 222-223, 225 hierarchical relationships, DataSets, 345-348 Hypertext Markup Language (HTML) pages to view user entries, 211, 214-219 nodes, XmlDocument class, 196-200 reusable classes, Extensible Stylesheet Language Transformations (XSLT), 287-290 SAX-style push models, XmlTextReader class, 145, 147, 149-154, 156-159

structures, eXtensible Markup Language (XML) documents, 205, 207-209 unique fields, keys, and relationships with XML schema, 124-125, 127-128 Web services, 445-447 XML fragments, XmlTextWriter class, 198-199 CredentialCache class, 166 credentials, authentication, 166 curly brackets ({}), 263 CustID attribute, 380 customer orders, retrieving, 444-450 CustomerID field, 379-380 CustomerID parameter, 366, 411

D data capturing, eXtensible Markup Language (XML) and ASP.NET, 226-227, 229 Electronic Data Interface (EDI), converting to eXtensible Markup Language (XML), 169, 172-173 element, loading into dropdown boxes, 214-217 eXtensible Markup Language (XML) generated by WriteXml( ) method, 321-322 generated by WriteXmlSchema( ) method, 322-324 inserting into tables, OPENXML rowset provider, 387

459

460

data

loading directly from SQL Server into DataSet class, 358-360 loading directly from SQL Server into XPathDocument class, 358 returned by ExecuteXmlReader( ) method, transforming, 395 filling DataSets with, 309-310 Hypertext Markup Language (HTML), embedding into eXtensible Markup Language (XML) elements, 41 legacy, converting to eXtensible Markup Language (XML), 169, 172173 sending from ASP.NET pages to eXtensible Markup Language (XML) templates, 388-389 sharing between applications and components, 7 data types Simple Object Access Protocol (SOAP), 414, 416417, 419 XML Data – Reduced (XMLDR) schema, 111-113 XML schema, 116-118, 120-124 DataAdapter class, 306 databases Northwind, 124-125, 127-128 updating, inserting, and deleting records, 389-394 dataFld attribute, 217 DataGrid WebControl, 318-320, 334 DataReader class, 300, 303, 306 DataRelation class, 361

DataSet class, 295, 306-308, 310-314, 316-317, 319-324, 326, 328-332, 334, 336-344, 346-348, 358-362 DataSet property, 328 dataSrc attribute, 217 datatype element, 113 date data type, 112 Date/Time extension class, 282 dateTime data type, 112 dateTime.tz data type, 112 DCOM (Distributed Component Object Model), 400-401 declarations DOCTYPE, 94-95 eXtensible Markup Language (XML), 21-23 External Entities, 39 Parameter Entities, 40 declaring complexType element, 120124 entities, Document Type Definitions (DTDs), 38 links, 82 parameters and variables, 264 XmlTextReader class, 153 default attribute, 110-111 default namespaces, 29-31, 33 default values, Document Type Definition (DTD), 99 DefaultCredentials property, 166 defaults, setting attributes to, 42 defining file structures, 7 DeleteDataSet( ) method, 337 deleting database records, 389-394 Depth property, 139 derived data types, 117-118 descendant axis, 56

descendent-or-self axis, 56 description elements, 34, 113 description markup languages, 8-9 Description property, 425 descriptive tags, 7 detail subelement, 413 directives EXPLICIT mode queries, 381-384 Web services, 426-427 directories, virtual, 351-353 disable-output-escaping attribute, 253 DISCO (Discovery of Web Services), 444 Discovery of Web Services (DISCO), 444 displaying DataSets as eXtensible Markup Language (XML), 311-314, 316-317 metadata files, 180 user entries, XMLHTTPRequest objects, 211, 214-219 Distributed Component Object Model (DCOM), 400401 DOCTYPE declaration, 94-95 Document Object Model (DOM) accessing MSXML3 through Interop, 179, 181 classes, System.Xml namespace and assembly, 182183 converting applications to true eXtensible Markup Language (XML) applications, 225-227, 229-231 creating hierarchical eXtensible Markup Language (XML) menu application, 219, 222-223, 225

Element value

creating structures, 183, 205, 207-209 described, 176-178 how it works, 136 in-memory vs. forward-only parsing, 178-179 selecting nodes, XPath, 204205 troubleshooting memory problems, 136 XmlDocument class, 189-195, 197-200 XMLHTTPRequest object, 211-213, 215-219 XmlNamedNodeMap class, 201-202, 204 XmlNode class, 183-184, 186-189 XmlNodeList class, 200-201 XmlNodeReader class, 209-210 Document property, 290 Document Type Definition (DTD), 4, 7 attributes, 97-99 declaring entities, 38 DOCTYPE declaration, 94-95 elements, 95, 97 entities, 38, 99-101 external, 95 internal, 95 notations, 101 reasons to use, 90-91 sample eXtensible Markup Language (XML) documents, 93-95 validating documents with, 21, 90-92 DocumentElement property, 190 documents appending information to, standard ASP.NET classes, 46-48 Document Type Definition (DTD), 104-105

Electronic Data Interface (EDI), 170 Extensible Hypertext Markup Language (XHTML), 43-44 eXtensible Markup Language (XML) closing tags, 18-19 contents of, 14, 16 creating structures in browsers, 205, 207-209 creating, XmlTextWriter class, 166, 168-169, 172-173 encoding types, 22-23 examples of, 93-95, 102, 124, 258-259 inferring DataSet schema from, 344-345 loading, 22, 194-196 nesting tags, 19-20 nodes, 183 parsing, 181 proper coding of, 16-20 referencing XML schema within, 129-130 root elements, 17-18 samples of, 237-238, 240-241, 246-249 saving updates, 195 schema, 103 shredding, OPENXML rowset provider, 385-386 templates, 236-237 transforming Extensible Stylesheet Language Transformations (XSLT) into, 259-260 unique identifiers, 27-28 validating, 20-21, 90-92, 159-162 versions of, 22 Extensible Stylesheet Language Transformations (XSLT), 260 Hypertext Markup Language (HTML), changing links, 86

linking, XLink, 76-77, 79-83, 85-88 source, assigning to asp:Xml Web control, 290 Web Service Description Language (WSDL), 433-436 DocumentType property, 190 dollar sign ($) character, 263 DOM. See Document Object Model DOMDocument30 interface, 181 drop-down boxes, loading element data into, 214-217 dsTables object, 314 dt:type attribute, 107, 111, 113 dt:values attribute, 111 DTD member, ValidationType enumerations, 161 DTD. See Document Type Definition

E EDI (Electronic Data Interface), 169-170, 172-173 editing color attribute to element, 25 database records, 389-394 links, Hypertext Markup Language (HTML) documents, 86 EdiToXml class, 173 Electronic Data Interface (EDI), 169-170, 172-173 element data, loading into drop-down boxes, 214-217 element directive, EXPLICIT mode queries, 382 element element, 116 ELEMENT keyword, 95, 97 element nodes, 154, 156 element tag, 108-109 Element value, 339

461

462

elementFormDefault attribute

elementFormDefault attribute, 129 elements , 251 , 25 , 251 , 24 , 24-25 , 24 , applying default namespaces to, 29-30 address, 261 all, 122 arc, 84-86 attribute, 116 AttributeType, 116, 121 binding, 437-438 Body, 410-414 Call, 410-411 child, 53 choice, 121-122 complexType, declaring, 120-124 courseDifficulty, 122 datatype, 113 described, 24-25 description, 113 Document Type Definition (DTD), 95, 97 element, 116 ElementType, 116, 121 embedding Hypertext Markup Language (HTML) data into, 41 Envelope, 407-408 extend, 84 extendLink, 83 Extensible Stylesheet Language Transformations (XSLT), 242, 244-245, 247-253, 255-256, 258-261, 263-267 Fault, 412-414 favoriteCourses, 121-122 field, 124-125, 127-128 group, 109, 122 Header, 408, 410

hyperLink, 96-97 key, 124-125, 127-128 keyref, 124-125, 127-128 loc, 83 locator, 86 maxInclusive, 118 menuItem, 96-97 message, 436-437 minInclusive, 118 MyCustomer, 379-381 MyCustomerOrders, 380 name, 96, 121-122 nesting, Hypertext Markup Language (HTML), 10 pattern, 120 portType, 437 recordsets with, 25 Response, 411-412 return, 412 returning from HTTP queries, 362-363 root, 17-18, 53-54, 96 row, 261 selector, 124-125, 127-128 sequence, 121-122 service, 438 simple, 84 simpleType, 118, 120 type, 436 unique, 124-125, 127-128 when required for attributes, XLink, 87-88 XML Data – Reduced (XMLDR) schema, 106-111 XML schema, 116 xpath-query, 375 xsd:schema, 128-129 xsl:apply-import, 243 xsl:apply-templates, 243, 253, 255, 257, 265 xsl:attribute, 244, 255-256, 261, 263-264 xsl:attribute-set, 244 xsl:call-template, 244, 257, 265-267 xsl:choose, 244, 255 xsl:comment, 244

xsl:copy, 244, 261 xsl:copy-of, 244, 261 xsl:decimal-format, 244 xsl:element, 244, 261 xsl:fallback, 244 xsl:for-each, 244, 261 xsl:if, 244, 252 xsl:import, 244 xsl:include, 245 xsl:key, 245 xsl:message, 245 xsl:namespace-alias, 245 xsl:number, 245 xsl:otherwise, 245, 255 xsl:output, 245, 250, 260 xsl:param, 245, 257, 261, 263-267 xsl:preserve-space, 245 xsl:processing-instruction, 245 xsl:sort, 245 xsl:strip-space, 245 xsl:stylesheet, 242, 245, 250, 258, 262, 264, 266 xsl:template, 245, 251-252, 264 xsl:text, 245 xsl:transform, 242, 246, 250, 264, 266 xsl:value-of, 246, 252, 256, 261 xsl:variable, 246, 261, 263-267 xsl:when, 246, 255 xsl:with-param, 246, 257, 265 ELEMENTS keyword, 362-363 ElementType element, 116, 121 ElementType tag, 106-107 embedding Hypertext Markup Language (HTML) data into eXtensible Markup Language (XML) elements, 41 XPath queries into eXtensible Markup Language (XML) templates, 375-376

eXtensible Markup Language

EnableSession property, 425 encoding Simple Object Access Protocol (SOAP), 414, 416-417, 419 Encoding property, 139 encoding types, eXtensible Markup Language (XML) documents, 22-23 end element nodes, 156 End tag ‘Name’ does not match the start tag ‘name’ error message, 20 End tag ‘root’ does not match the start tag ‘p’ error message, 18 end-point(location-set) function, 74 endDocument( ) method, 157 endElement( ) method, 155-156 ending parsing, XmlTextReader class, 157-158 ending-resource keyword, 79 entities ©, 36 , 35 ®, 36 Character, 37-38 declaring, Document Type Definitions (DTDs), 38 described, 35-36 Document Type Definition (DTD), 99-101 External, 38-39, 99 handling, XmlTextReader class, 157 Internal, 38-39, 99 Parameter, 38, 40, 100-101 Standard, 36-37 entries, users, 211, 214-219 Enumeration attribute, 98 enumerations CommandType, 302 MappingType, 338 OleDbType, 303

SqlDbType, 302 XmlNodeType, 183 Envelope element, 407-408 EOF property, 139 erasing database records, 389-394 error messages A name was started with an invalid character, 25 End tag ‘Name’ does not match the start tag ‘name’, 20 End tag ‘root’ does not match the start tag ‘p’, 18 Incorrect syntax was used in a comment, 35 Whitespace is not allowed at this location, 36 errors catching, XmlTextReader class, 157-158 Resource, 75 Subresource, 75 Syntax, 75 XPointer, 75 event handlers, 161-162 events onChange, 214-217 Page Load, 280 ValidationCallBack( ), 162 ValidationEventHandler, 161-162 ExecuteXmlReader( ) method, 394-396 EXPLICIT mode queries, 377-384 expressions identifying fragments with, XPointer, 76 leaving axes out of, 66 extend element, 84 extended link keyword, 79 extended links, 83, 85-86 extendLink element, 83 Extensible Hypertext Markup Language (XHTML), 42-44

eXtensible Markup Language (XML) attributes, 25, 27 benefits of, 7-8 capturing data, 226-227, 229 case sensitivity of, 20 character data (CDATA) sections, 40-41 comments, 34 converting applications from ASP to ASP.NET, 180-181 converting applications to, 225-227, 229-231 converting Electronic Data Interface (EDI) and legacy data to, 169, 172-173 creating DataSet mappings, 343-345 creating fragments, XmlTextWriter class, 198-199 creating hierarchical menu applications, 219, 222-223, 225 creating hierarchical relationships, DataSets, 345-348 data generated by WriteXml( ) method, 321-322 data generated by WriteXmlSchema( ) method, 322-324 declarations, 21-23 documents closing tags, 18-19 contents of, 14, 16 encoding types, 22-23 examples of, 93-95, 102, 124 loading, 22 nesting tags, 19-20 proper coding of, 16-20 referencing XML schema within, 129-130 root elements, 17-18 schema, 103 unique identifiers, 27-28

463

464

eXtensible Markup Language

validating, 20-21 validation of, 90-92 versions of, 22 elements, 24-25 entities, 35-40 features of in SQL Server 2000, 350 generating with ASP.NET objects, 44-45, 47-50 generating, XmlTextWriter class, 168 handling whitespaces, 41 how ASP.NET developers can use, 11-12 Hypertext Markup Language (HTML) vs., 8-10 inserting data into tables, OPENXML rowset provider, 387 integrating with ADO.NET, 294 loading DataSets, 318-319 loading element data, dropdown boxes, 214-217 manipulating, OPENXML rowset provider, 385-389 mapping fields to attributes, 339-341 marking up comma-delimited files, 5-6 namespaces, 27, 29-34 origin of, 4-5 parsing, XmlTextReader class, 138-145 processing instructions (PIs), 34 saving DataSets as, 320-324 schema attributes, 116 creating unique fields, keys, and relationships, 124-125, 127-128 data types, 116-118, 120-124 elements, 116

example of, 114 namespace support, 128129 referencing within eXtensible Markup Language (XML) documents, 129-130 transforming data returned by ExecuteXmlReader( ) method, 395 transforming Extensible Stylesheet Language Transformations (XSLT) into, 258 transforming to Hypertext Markup Language (HTML), 281 updating, inserting, and deleting database records, 389394 validating documents, XmlTextReader and XmlValidatingReader classes, 159-162 viewing DataSets as, 311-314, 316-317 why it’s needed, 5-7 eXtensible Markup Language (XML) documents creating structures in browsers, 205, 207-209 examples of, 258-259 inferring DataSet schema from, 344-345 loading, XmlDocument class, 194-196 nodes, 183 parsing, 181 samples of, 237-238, 240-241, 246-249 saving updates, 195 templates, 236-237 transforming Extensible Stylesheet Language Transformations (XSLT) into, 259-260

eXtensible Markup Language (XML) templates directives in EXPLICIT mode queries, 382-383 querying SQL Server 2000 through, 363-365, 367-368 sending data from ASP.NET pages to, 388-389 Extensible Stylesheet Language Transformations (XSLT) ADO.NET classes, 272-273, 275-277, 279-282, 284-285, 287 creating hierarchical relationships, DataSets, 345-348 creating reusable classes, 287-290 described, 234-235 elements, 242, 244-245, 247-253, 255-256, 258-261, 263-267 examples of, 237-238, 240-241 functions, 267-269, 271 templates, 236-237 transforming eXtensible Markup Language (XML) into, 258 transforming Hypertext Markup Language (HTML) into, 237-238, 240-241, 246-253, 255-256, 258 extension objects, Extensible Stylesheet Language Transformations (XSLT), 282, 284-285, 287 extensions, .asmx, 431-432 external Document Type Definition (DTD), 95 External Entities, 38-39, 99 external linksets, XLink, 86-87 external schema, 104

generating

F false( ) function, 66 Fault element, 412-414 faultactor subelement, 413 faultcode message, 408 faultcode subelement, 413 faultstring subelement, 413 favoriteCourses element, 121-122 field element, 124-125, 127-128 fields CustomerID, 379-380 mapping to eXtensible Markup Language (XML) attributes, 339-341 SOAPAction, 420 unique, creating with XML schema, 124-125, 127-128 fileName parameter, 49 files .asmx extension, 431-432 ASP.NET, consuming Web services, 438-442, 444 comma-delimited, marking up in eXtensible Markup Language (XML), 5-6 defining structures of, 7 eXtensible Markup Language (XML), building with ASP.NET objects, 44-45, 4750 Hypertext Markup Language (HTML), screen scraping, 422 linkbases, 86-87 metadata, viewing, 180 schema, 7 Fill( ) method, 307, 311, 314 FillDropDown( ) method, 280 filtering nodes, 58 finally block, 158 finding paths to nodes, 54-60

firewalls, Distributed Component Object Model (DCOM), 401 FirstChild property, 184, 188, 190 fixed.14.4 data type, 112 flag values, OPENXML rowset provider, 386 float data type, 112 floor(number) function, 64 following axis, 56 following-sibling axis, 56 FOR XML AUTO keyword, 363 FOR XML EXPLICIT keyword, 383 FOR XML EXPLICIT keywords, 380 FOR XML keywords, querying SQL Server 2000 through HTTP, 353-358, 360, 362 for..next loop, 201 foreach loop, 201, 314 foreign-relation attribute, 373 form attribute, 129 forward-only parsing vs. in-memory parsing, 135137, 178-179 fragment identifiers, 71 fragments, identifying with XPointer, 75-76 from attribute, 81, 85 functions boolean, 65-66 ceiling(number), 65 concat(string1,string2,string 3, ...), 62 contains(string1, string2), 62 count( ), 252 count(node-set), 60 end-point(location-set), 74 Extensible Stylesheet Language Transformations (XSLT), 267-269, 271

false( ), 66 floor(number), 64 here( ), 74 id( ), 60, 75 lang(string), 66 last( ), 60 local-name( ), 61 name( ), 61 namespace-uri(node), 61 node-set, 60-61 normalize-space(string), 63 not(boolean), 65 number, 64-65 origin( ), 74 position( ), 59, 60, 66 range( ), 72-74 round(number), 65 start-point(location-set), 74 starts-with(string1,string2), 62 string, 61-64 string-length(string), 63 string-range(locationset,string,number,number), 73 substring(string,number,number), 63 substringafter(string1,string2), 63 substringbefore(string1,string2), 62 sum(node-set), 64 translate(string,from,to), 63-64 true( ), 65 XPointer, 72-74

G GenerateXml( ) method, 173 generating eXtensible Markup Language (XML) ASP.NET objects, 44-45, 47-50 XmlTextWriter class, 168 proxies, Web services, 440

465

466

generic validation class, creating

generic validation class, creating, 162-165 GET method, 419 getAllResponseHeaders property, 213 GetAttribute( ) method, 141 GetChanges( ) method, 336 GetDateTime( ) method, 284, 287 GetElementByID( ) method, 192 GetElementFromRow method, 329, 336-337 GetElementsByTagName( ) method, 192, 204 GetEnumerator( ) method, 200, 202 GetExtensionObject( ) method, 277 GetName( ) method, 404, 410 GetNamedItem( ) method, 202 GetNamespaceOfPrefix( ) method, 185, 192 GetOrders( ) method, 411-413 GetParam( ) method, 277 GetPrefixOfNamespace( ) method, 185, 193 GetRemainder( ) method, 141 getRequest(( ) method, 214-217 getResponseHeader( ) property, 213 GetRowFromElement method, 329 getXML value, 218 GetXml( ) method, 317, 336, 338, 343 GetXmlSchema( ) method, 317 greater than ( >) character, 36, 96 group element, 109, 122 groups, XML Data – Reduced (XML-DR) schema, 106-111

H handlers event, attaching with XmlValidatingReader class, 161-162 setting, XmlText Reader class, 153 handling overloaded methods, 427-428 processing instructions, whitespaces, and entities, XmlTextReader class, 157 whitespaces, 41 HasAttributes property, 139 HasChildNodes property, 184, 190 HashTable class, 278 HasValue property, 139 Header element, 408, 410 headers, Hypertext Transfer Protocol (HTTP), 419, 421 here( ) function, 74 Hidden value, 339 hide directive, EXPLICIT mode queries, 381 hierarchical eXtensible Markup Language (XML) menu applications, creating, 219, 222-223, 225 hierarchies, creating DataSet relationships, 345-348 href attribute, 80, 82, 417 HTML. See Hypertext Markup Language HTTP. See Hypertext Transfer Protocol HTTP-GET command, 422-423 HTTP-POST command, 423 hyperLink element, 96-97 Hypertext Markup Language (HTML) changing links in documents, 86

creating pages to view user entries, 211, 214-219 elements, 24 Extensible Hypertext Markup Language (XHTML) vs., 43 eXtensible Markup Language (XML) vs., 8-10 limitations of links in, 77 screen scraping files, 422 transforming eXtensible Markup Language (XML) to , 281 transforming Extensible Stylesheet Language Transformations (XSLT) into, 246-253, 255-256, 258 transforming into Extensible Stylesheet Language Transformations (XSLT), 237-238, 240-241 Hypertext Transfer Protocol (HTTP) headers, Simple Object Access Protocol (SOAP), 419, 421 querying SQL Server 2000 with templates, XPath, and XDR schema, 368-370, 372374, 376 querying SQL Server 2000 with, 351-352, 354-358, 360, 362-365, 367-368

I i1 data type, 112 i2 data type, 112 i4 data type, 112 i8 data type, 112 IContentHandler interface, 146-147 ID attribute, 98, 229-230, 390, 417 ID directive, EXPLICIT mode queries, 381, 383 id variable, 217-218

keywords

id( ) function, 60, 75 identifiers fragment, 71 unique, eXtensible Markup Language (XML) documents, 27-28 Universal Resource (URI), 29 identifying fragments in XPointer, 75-76 IDREF directive, EXPLICIT mode queries, 381, 383 IDREF/IDREFS attribute, 98 IDREFS directive, EXPLICIT mode queries, 381 IIS (Internet Information Server), configuring SQL Server virtual directories, 351-353 IL Disassembler tool, viewing metadata files, 180 Implementation property, 190 ImportNode(node,deep) method, 193 in-memory parsing vs. forward-only parsing, 135-137, 178-179 Incorrect syntax was used in a comment error message, 35 indent attribute, 250 InferXmlSchema( ) method, 345 information retrieval, XPointer, 69-76 inline link keyword, 79 InnerText property, 184, 190 InnerXml property, 184, 190 InsertAfter( ) method, 185, 193 InsertBefore( ) method, 185, 193 InsertDataSet( ) method, 337

inserting database records, 389-394 eXtensible Markup Language (XML) data into tables, OPENXML rowset provider, 387 instantiating XmlNode classes, 186 XmlTextReader class, 138, 153-154 XmlValidatingReader class, 160 XPathDocument classes, 274-275 instructions, processing (PI), 34, 157 int data type, 112 interfaces DOMDocument30, 181 IContentHandler, 146-147 internal Document Type Definition (DTD), 95 Internal Entities, 38-39, 99 Internet Explorer validating eXtensible Markup Language (XML) documents, 92 xml:space attribute, 42 Internet Information Server (IIS), configuring SQL Server virtual directories, 351-353 Interop, accessing MSXML3 through, 179, 181 IsDefault property, 139 IsEmptyElement property, 139 ISO-8859-1 standard, 23 IsReadOnly property, 184, 190 IsStartElement( ) method, 141 Item property, 139, 184, 190 Item( ) method, 200, 202 itemNumber attribute, 25

J Japanese language, 23 Java Remote Method Invocation (RMI), 401

K key attribute, 373 key element, 124-125, 127-128 key-relation attribute, 373 keyref element, 124-125, 127-128 keys, creating with XML schema, 124-125, 127-128 keywords arc, 79 AUTO, 354-355 BINARY BASE64, 363 ELEMENT, 95, 97 ELEMENTS, 362-363 ending-resource, 79 extended link, 79 FOR XML, querying SQL Server 2000 through HTTP, 353-358, 360, 362 FOR XML AUTO, 363 FOR XML EXPLICIT, 380, 383 inline link, 79 linkbase, 79 locator, 79 multidirectional link, 79 out-of-line, 80 RAW, 355 Schema, using with namespaces, 105-106 simple link, 80 standalone, 23 traversal, 80 UNION ALL, 379-381 XLink, 79-80 xml, 22 XMLDATA, 363, 383 xmlns, 29

467

468

label attribute

L label attribute, 81, 85 lang(string) function, 66 last( ) function, 60 LastChild property, 184, 190 launching IL Disassembler tool, 180 legacy data, converting to eXtensible Markup Language (XML), 169, 1 72-173 less than (

XML for ASP.NET Developers (Kaleidoscope)

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Grid computing for developers

Cryptography for Developers

Cryptography for Developers

Mathematics for Game Developers

Physics for game developers

Cryptography for Developers

Mathematics for Game Developers

DevOps for Developers

XML for ASP.NET Developers (Kaleidoscope)

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Kaleidoscope

Grid computing for developers

Cryptography for Developers

Cryptography for Developers

Mathematics for Game Developers

Physics for game developers

Cryptography for Developers

Mathematics for Game Developers

DevOps for Developers

Recommend Documents