CH 08

Color profile: Generic CMYK printer profile
Composite DefaultAll-In-One
screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter 8
XML and C#
Documentation
CHAPTER
8
In this chapter, you will
• Be introduced to Extensible Markup Language (XML)
• Learn to create a well-formed XML document
• Discover how XML is used to create C# documentation
This is another topic that could fill an entire book. Extensible Markup Language (XML)
is an exciting new addition to the list of markup languages, and it redefines the way we
transfer data. We will take a brief look at XML and apply that information to the type
of documentation that you can create in your C# programs by using documentation
comments.
Although the exam may not contain any specific questions on creating C# documen-
tation, it will expect that you understand XML. To that end, this chapter will deal with
the basics of the XML language, including the rules for creating a well-formed XML doc-
ument. This information will be revisited in Chapter 11, where you will find out how
XML fits into the big picture. So let’s move on and discover the newest standard for ex-
changing data—Extensible Markup Language.
Introduction to XML
In the olden days of computers (which, as you know, in most cases means yesterday),
data exchange over the network and between applications happened in two ways. You
either created a binary file that included formatting code for a specific application (such
as a Word document) or you produced a straight text file that could be read by any text
editor (such as Notepad). (Technically, of course, these are both binary files—but a doc-
ument that includes formatting code cannot be read by a straight text editor.) The ad-
vantage of a binary file is that the formatting code is in binary, which makes it faster for a
computer to interpret; thus a Word document opens quickly once it reads the format-
ting information (which we could call metadata, or data about data). However, we are
limited to sending such data only to those applications that understand the metadata.
Enter SGML—Standard Generalized Markup Language. This was the first attempt to
create a format that allows a document to be self-describing. In other words, the text is
P:\010Comp\All-in-1\443-6\ch08.vp
Friday, August 23, 2002 4:58:18 PM
MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

2
“marked up” with metadata that describes the formatting of the text. One of the most
popular extensions of SGML is HTML—Hypertext Markup Language—which is used to
produce formatted documents within a browser program. However, as we’ll see in the next
section, HTML is simply a way to format data. What if we want to create and store data?
Typically, we use a database to store data, and any program requesting information
from the database must understand how to ask the database for the information. In
other words, you need to understand the schema or the way the data is described. XML is
self-describing in that you create the schema along with the actual data. This is a very ex-
citing technique that opens the doors for many possibilities, and we will explore them
in this chapter.
What Is XML?
XML is a standard that was created in order to represent data in an easily readable,
self-defining, and structured approach. It is a markup language that uses tags to define
the structure of the data that is included in the document. There are many advantages to
using XML over the more traditional data storage and retrieval methods:
• It’s a standard—every application that follows the standard is capable of

parsing the XML data.
• It’s extensible—there are no limits, because you define the markup tags.
• It’s an open technology—no one vendor “owns” XML.
• It’s interoperable—let’s face it, this is one of the most desirable qualities of data
in today’s world. If we can read the information from any application, we have
eliminated a very large concern of the past. Consider the different operating
systems (Windows, Unix, Linux, Mac, ...), hardware (PCs, mainframes, hand-held
computers, ...), transfer protocols, and so on. Interoperability is the desired
outcome of any new technology, and XML is interoperable.
• It’s text-based—you don’t need a fancy application to read it. As a matter of
fact, it is readable by the human eye, which is another goal of XML.
• It’s easily transferred over a network—this is a big advantage. We want
our information to be produced visually for us, quickly and efficiently. XML
accomplishes this and more. The load on servers is now greatly reduced because
a client-side application (browser) or script can do a lot of the parsing of the data
and the formatting of it. Servers are now freed up to do the more intensive work
of storing and retrieving the data, rather than formatting it for data transfer.
There are some disadvantages to using XML, but they are being more easily overcome
as the industry swings towards its use. For example, one drawback that may have come
to mind already is that while we might describe an employee record using XML in one
fashion; you may choose to define it in another fashion. In that case, many different
documents could wind up defining the same thing. In order to overcome this potential
confusion, the industry has started to produce vocabularies, or industry-standard ways to
describe recurring data. This allows you to produce software that is more compatible
Chapter 8: XML and C# Documentation

3
with other software. Because the industry has not settled on all of the standards, XML
still exhibits some nonstandard behavior, but you can expect this to disappear as time
moves on.
HTML vs. XML

Although both XML and HTML are markup languages, their use is quite different. If you
can keep their purposes separated, you will have conquered the difference between XML
PART II
and HTML:
• The purpose of HTML is to display data.

• The purpose of XML is to exchange data.
HTML
HTML is used to format data and render it in a web browser or other application that
translates HTML. There is a fixed set of tags within HTML that have been defined so that
there is a standard way of presenting the data.
Let’s look at an HTML file and then see how it is rendered in a web browser.
<html>
<body>
<h1 align="center"><i><b>My HTML Page</b></i></h1>
<div align="center">
<center>
<table border="1" width="55%">
<tr>
<td width="16%" align="center"><i><b>Student ID</b></i></td>
<td width="17%" align="center"><i><b>First Name</b></i></td>
<td width="15%" align="center"><i><b>Last Name</b></i></td>
<td width="39%" align="center"><i><b>Program of Study</b></i></td>
</tr>
<tr>
<td width="16%">123456</td>
<td width="17%">Matthew</td>
<td width="15%">Rempel</td>
<td width="39%">Software Engineering</td>
</tr>
<tr>
<td width="16%">234567</td>
<td width="17%">Geoff</td>
<td width="15%">Hamilton</td>
<td width="39%">Mining Engineering</td>
</tr>
<tr>
<td width="16%">345678</td>
<td width="17%">Koby</td>
<td width="15%">Waldron</td>
<td width="39%">Business Administration</td>
</tr>
<tr>
<td width="16%">456789</td>
<td width="17%">Lauren </td>
<td width="15%">Waldron</td>

4
<td width="39%">Bachelor of Education</td>
</tr>
</table>
</center>
</div>
</body>
</html>
Notice that the file is divided into tag sections—<html> is the top-level tag, followed by
<body> and the rest. Each section is completed when you end it with a backslash
tag—such as </html>. Since a browser understands these predefined tags, you can
open the HTML file in any browser (see Figure 8-1). Notice that this web page contains
data elements—Student ID, First Name, Last Name, and Program of Study. However,
the data is simply contained in tags that describe how it is presented visually. There is
nothing that actually describes the data itself.
XML
Now let’s look at the same data formatted using XML tags. XML has no predefined set of
tags to describe the student data we have presented in the HTML example. We describe
this data ourselves in XML. Notice in the following code example that there is nothing to
specify how the data is presented to the “viewer.”
<?xml version="1.0" ?>

<students>
<student>
<id>123456</id>
<firstname>Matthew</firstname>
<lastname>Rempel</lastname>
<program>Software Engineering</program>
</student>
<student>
<id>234567</id>
<firstname>Geoff</firstname>
<lastname>Hamilton</lastname>
<program>Mining Engineering</program>
</student>
<student>
<id>345678</id>
<firstname>Koby</firstname>
<lastname>Waldron</lastname>
<program>Business Administration</program>
</student>
<student>
<id>456789</id>
<firstname>Lauren</firstname>
<program>Bachelor of Education</program>
</student>
</students>
Notice that this entire file is dedicated to simply describing the data. We will discuss
the various tags and how you create a well-formed document later in this chapter. For
now, just observe the code and the output as rendered in an XML-parser program, which
in this case is Internet Explorer 6 (see Figure 8-2).

5
Figure 8-1
An HTML file
opened in
Internet Explorer
PART II
Figure 8-2
An XML file
opened in
Internet Explorer

6
If we want to display this XML file, we can use tools that render the XML into a pre-
sentation format, such as the following:
• Microsoft Internet Explorer 6

• XSLT—Extensible Stylesheet Language Transformations
• CSS—cascading style sheets
At this point, however, we are not too interested in displaying the data—if you are inter-
ested in either XSLT or CSS, grab a book on XML rendering. Rather, we need to under-
stand how the data is described and what constitutes a well-formed XML document. We
will discuss the rules of a well-formed XML document later in this chapter.
Why Use XML?

As you can see, HTML and XML are very different. As a matter of fact, they actually com-
plement each other. While XML is focused primarily on the data itself, HTML can be
used to present the information.
Let’s think of some of the applications that can make use of XML. In order to exchange
information between programs and operating systems, you need an interoperable
method of transferring the data. XML provides this functionality. Documents can be writ-
ten in XML and then transformed using presentation software. Companies can send data
to each other using a standard, readable format. One company can transmit an invoice to
another using XML definitions, and the receiving company can easily parse the document
and render it. Say goodbye to fax machines, photocopiers, and even the post office!
Creating an XML Document

An XML document is made up of the following parts:
• XML declaration and processing instructions A document starts with a

declaration of the version of XML along with some encoding information.
Following that declaration, you can include any number of processing
instructions. You may want to tell the XML-parser application to use a
particular style sheet for presenting the data.
• Comments You can insert any number of comments into an XML document.
• Elements An element is a piece of data—we will explore elements in greater
detail later in this chapter.
• Attributes An attribute is an additional piece of information associated with
an element.
In the next few sections, we will briefly look at each of these and then examine the rules
for creating a well-formed XML document.

7
XML Declaration and Processing Instructions
Although it is not necessary to include an XML declaration in your document, it is a good
idea to do so. It helps identify to the reader of your document the type of XML used, the
character set, and whether there are other files necessary to enhance the document.
The XML declaration looks like this:
<?xml version="1.0" encoding="UTR-16" standalone="yes"?>
PART II
The declaration starts with <? and ends with ?>. If you include a declaration, it must be at
the beginning of the file, and you must code the version. Everything else is optional. No-
tice that the values are enclosed in double quotation marks. You can use either double or
single quotes, but they must match. The encoding entry specifies the character set that is
used. This could be ASCII (American Standard Code for Information Interchange), which
allows for 256 characters, Unicode 8 or 16 (UTF-8, UTF-16), which allows for a far greater
number of characters and provides international characters, or it could simply be Win-
dows if you built the file in Notepad. The standalone entry specifies whether there are
other files required to render the document.
In order to embed application-specific instructions into the XML, you must provide
processing instructions. An example of this would be to include an instruction that tells
the document to apply a particular style sheet to the data:
<?xml-stylesheet type="text/xsl" href="mystylesheet.xsl"?>
This line tells the XML-parser program that when it reads the data, it can format it for
output according to the specifications of the style sheet.
Comments
Any number of comments can be included in an XML document. Comments, of course,
provide detailed information to the reader of the file, but no information to the actual
document itself. As a matter of fact, comments may not even be passed on to the appli-
cation parsing the document.
A comment starts with , like this:

Elements
We are now at the crux of the matter. Elements are the most common type of markup that
you will see in an XML document. Elements are used to describe the data and formulate
the hierarchy of the data itself.
You use a tag to define data elements. In between the start tag, <element_name>,
and the end tag, </element_name>, is the actual text or data that belongs to the ele-
ment. In our student example, we define a student’s first name as follows:
<firstname>Matthew</firstname>

8
Because data can be hierarchical in nature, we can create nested elements. A student
has a student ID, a first name, a last name, and a program:
<student>
<id>345678</id>
<firstname>Koby</firstname>
</student>
In this example, there are four sub-elements nested within the top-level element, stu-
dent. We can further nest by defining a collection of students:
<students>
<student>

</student>
<student>

</student>
</students>
Eventually, your design will include a single top-level element. This is called the root
element. As you will see in the rules of a well-formed document, you can only have a sin-
gle root element. All other elements are children of the root element.
When designing the structure of elements, you should follow these simple rules:
• Every start tag must have a corresponding end tag.

• There can only be one root element.
• XML is case sensitive; therefore, Student is a different element from student.
• You cannot overlap tags. In other words, using the preceding example, the
<student> tag must be closed off before the <students> tag is closed.
Attributes
Elements can make use of attributes, which are names matched with values that belong
to an element. We could redefine our student as follows:
<student id="123456" >

<firstname>Lauren</firstname>
</student>
In this case, <id> is an attribute that further describes the element <student>. The
value of the attribute must be enclosed in quotation marks (either double quotes or
single quotes).
A Well-Formed XML Document

Yes, Virginia, there are rules. If a document is said to be a “well-formed XML document,”
this means that it adheres to the syntax rules for XML. These are the rules:

9
• There must be matching opening and closing tags.
• XML is case-sensitive, so naming must be consistent.
• There can only be one root element.
• All other elements are children of the root element.
• You cannot have repeating attributes for a single element.
• All attribute values must be enclosed in quotations. It doesn’t matter if they are
PART II
double or single quotations; they just have to match.
Well-formed means that the document complies with the XML specifications. A docu-
ment can also be considered a valid document. In that case, it must conform to either
a DTD (document type definition) or an XML schema.
NOTE DTDs are XML documents that exist within the XML file or outside
of it. A DTD defines the rules for how the document is structured, what
elements are included, the kinds of data, and any default values.
There are several things to consider when deciding whether to use an XML schema or
a DTD. A DTD is not extensible, and there can only be one for each document. The syn-
tax of DTD is not XML, and the data typing is very weak. An XML schema is XML, which
means that all of the advantages of using XML are also inherited by the XML schema.
NOTE An XML schema is made up of data types and structures and defines
the structure of the XML document.
Having said all of that, a valid XML document adheres to the rules laid down in either
the DTD or the schema. Your XML document will fit into one of these categories:
• An invalid document One that doesn’t follow the tag rules

• A well-formed document One that follows the tag rules but has no DTD or
schema
• A valid document One that follows the tag rules and the rules defined in the
DTD or schema
We have now looked at the very large topic of creating and using XML documents.
The next thing to do is discuss XML documentation using special comments within your
C# program code.
XML Documentation in C#
A Java program can generate HTML documentation from special documentation com-
ments inside the program itself. Microsoft Visual C# .NET has followed this example

10
and embellished it by creating XML documentation from the comments instead of
straight HTML. As we have already seen in this chapter, you can take such XML data and
use it in any way, shape, or form you want. That’s the beauty of XML.
XML Documentation Tags

All comments in C# that are to be treated as documentation comments begin with three
forward slashes (///). These comments must preface a user-defined type—a class defi-
nition, structure, enum, method, and so on. Unlike Java, the C# compiler will generate
the XML file if you include the /doc switch. There is no separate utility to generate the
documentation.
Figure 8-3 illustrates a simple program with documentation comments inserted.
When we compile the source code, we use the compiler and the /doc switch:
csc MyXMLExample.cs /doc:MyXMLExample.xml
Figure 8-4 shows the XML file that is created.

Table 8-1 lists the common tags you can include in your documentation code to add
more descriptive items to the final XML file. If your XML comments don’t produce a well-
formed XML document, the C# compiler will return an error.
XML Comments and Visual Studio .NET

Although you really don’t need to know too much about Visual Studio .NET for the ex-
ams, it warrants discussing here how valuable the IDE is for creating and managing XML
Figure 8-3 A C# class file with documentation comments

11
PART II
Figure 8-4 XML documentation file generated from documentation comments
Documentation Tag Description

<c> Includes code in the text; for example,
<c>string s = "hello";</c>
<code> Includes multiple lines of code in the text
<example> Documents a code example
<exception> Causes compiler to check that this matches an exception that can
be thrown
<include> Includes documentation from another file
<list> Inserts a list into the documentation file
<param> Describes the parameters of a method; the compiler will check that
it matches the parameters of the method
<paramref> Marks a parameter
<permission> Identifies access permissions
<remarks> Includes a description
<returns> Marks the return value of a member
<see> Gives a cross reference to a related item
<seealso> Gives a “see also” section
<summary> Provides an executive summary of the member
<value> Describes a property; this is also used by IntelliSense in order to
display additional information about a member
Table 8-1 C# Documentation Tags

12
comments. The first thing to notice is how friendly the interface is when you want to enter
a documentation comment. As soon as you type the three slashes (///), the program will
return an extensive number of lines, which will assist with your documentation (see Fig-
ure 8-5). Notice how handy this is. Visual Studio has inserted the summary lines as well as
the param and returns tags. We just have to fill in the blanks.
Another excellent feature of Visual Studio .NET is the option to have the XML docu-
mentation rendered in an HTML file. By selecting Tools | Build Comment Web Pages
from the menu, you will be presented with the Build Comment Web Pages dialog box,
as shown in Figure 8-6.
Fill in the location for the HTML file, and Visual Studio will create the HTML for you.
In your project directory, you will find a new directory that will contain all the files
needed to render a documentation page (see Figure 8-7). You can move through the
links and see that the comments that were added to our C# source file have now been
transformed into XML. Then, by using the Visual Studio .NET Comment tool they have
been rendered into HTML and can be opened and viewed in any browser or from within
the IDE itself.
Isn’t this just unbelievably exciting? The days of programmers sweating over docu-
mentation are over. You only have to add these comments as you go, and you have a
brilliant piece of documentation when you are done. You don’t have to use the Visual
Studio .NET tools to render the HTML—you can use an XSL (Extensible Stylesheet Lan-
guage) file to accomplish the same thing. Here are the steps:
1. Create your C# source file with the documentation comments.

2. Compile it with the C# compiler and the /doc switch.
3. Take the generated XML file, and together with an XSL file, run them through
an XSLT processor.
4. You will now have the final HTML documentation in the style you prefer.
Figure 8-5
Visual Studio
.NET IntelliSense

13
Figure 8-6
The Build
Comment Web
Pages dialog box
PART II
Figure 8-7 The HTML documentation page

14
Summary
This chapter has introduced you to a lot of new topics surrounding XML. As we have sug-
gested before, if you are completely new to XML, you would be wise to catch up on this
technology by reading through documentation focused on XML. It’s a data-exchange
format that you don’t want to miss. Although the exam will probably not test you di-
rectly on your knowledge of XML, you will need to understand its uses in your applica-
tions. Be sure to check in with Part III of this book on ASP.NET to explore more of the
uses of XML. You may also find that the Microsoft exams ask you one or two questions
on the documentation comments.
Test Questions
1. Which command will cause an XML file to be generated from documentation
comments?
A. csc MyClass.cs /doc:MyClass.cs
B. cscd MyClass.cs /doc:MyClass.xml
C. cscd MyClass.cs /doc:MyClass.cs
D. csc MyClass.cs /doc:MyClass.xml
2. Which line causes the following XML to be not well-formed?
<VideoList>
<tape>
<name>XML is cool!</name>
</VideoList>
</tape>
A. <tape>
B. </VideoList>
C. </tape>
D. <name>XML is cool!</name>
3. Which XML rule does the following break?
<employees>
<Employee>
<name>Kenneth S. Lind</name>
</Employee>
<employee>
<name>Marj Rempel
</employee>
</employees>
A. There must be a single root element.
B. There must be matching opening and closing tags.
C. XML is case-sensitive.
D. All attributes must be in quotes.

15
4. Which XML rule does the following break?
<employees>
<employee>
<name id=123>Kenneth S. Lind</name>
</employee>
<employee>
<name id=456>Marj Rempel</name>
</employee>
</employees>
PART II
A. There must be a single root element.
B. There must be matching opening and closing tags.
C. XML is case-sensitive.
D. All attributes must be in quotes.
5. Visual Studio .NET provides a tool to generate HTML from the XML
documentation file. It is found where?
A. Tools | Generate XML
B. Tools | Generate HTML
C. Tools | Build Comment Pages
D. Tools | Build Comment Web Pages
6. Which XML line(s) generates an employee attribute?
A. <employee name="Ken">
B. <employee attribute name="Ken">
C. <employee Name='Ken'>
D. <employee attribute Name='Ken'>
7. Which of the following lines is an XML declaration?
A. <xml version="1.0">
B. ?xml version="1.0"?
C. <?xml version=1.0?>
D. <?xml version="1.0"?>
8. Why will the following XML code not be rendered by a browser?
<name>
<lastname>Dowdy</lastname>
<firstname>Howdy</firstname>
</lastname>
A. The browser is not specified.
B. The root element is missing.
C. The root element is not closed properly.
D. The firstname element is incorrect.

16
9. Assess the following XML. Which answer correctly describes the code?
<addresses>
<listing>
<name>
<lastname>Dowdy</lastname>
<firstname>Howdy</firstname>
</name>
<address>
<street>123 Anywhere St</street>
<city>MyCity</city>
</address>
</listing>
</addresses>
A. The name element is described incorrectly.
B. The address element is described incorrectly.
C. The addresses root element is described incorrectly.
D. Nothing—this is well-formed XML.
10. Which of the following documentation comments is correct?
A. /// summary This is a summary comment summary
B. /// <summary> This is a summary comment </summary>
C. /// <summary> This is a summary comment
D. /// summary This is a summary comment
Test Answers
1. D.
2. B. This line needs to be at the end.
3. B. There must be matching opening and closing tags: <name>Marj Rempel
4. D.
5. D.
6. A and C. You can use double or single quotes.
7. D.
8. C.
9. D.
10. B.

CH 08

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CH 08

Uploaded by

Copyright:

Available Formats

Color profile: Generic CMYK printer profile

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

• It’s a standard—every application that follows the standard is capable of

Chapter 8: XML and C# Documentation

HTML vs. XML

• The purpose of HTML is to display data.

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

<?xml version="1.0" ?>

Chapter 8: XML and C# Documentation

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

• Microsoft Internet Explorer 6

Why Use XML?

Creating an XML Document

• XML declaration and processing instructions A document starts with a

Chapter 8: XML and C# Documentation

<?xml version="1.0" encoding="UTR-16" standalone="yes"?>

<?xml-stylesheet type="text/xsl" href="mystylesheet.xsl"?>

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

• Every start tag must have a corresponding end tag.

<student id="123456" >

A Well-Formed XML Document

Chapter 8: XML and C# Documentation

• An invalid document One that doesn’t follow the tag rules

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

XML Documentation Tags

Figure 8-4 shows the XML file that is created.

XML Comments and Visual Studio .NET

Figure 8-3 A C# class file with documentation comments

Chapter 8: XML and C# Documentation

Documentation Tag Description

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

1. Create your C# source file with the documentation comments.

Chapter 8: XML and C# Documentation

Figure 8-7 The HTML documentation page

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

Chapter 8: XML and C# Documentation

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

You might also like