Export (0) Print
Expand All
0 out of 5 rated this helpful - Rate this topic

Lab 2: XML Comments

Visual Studio .NET 2003
 

Visual Studio Team
Microsoft Corporation

August 2001

Summary: In this hands-on lab you will use the C# compiler to generate an Extensible Markup Language (XML) file from XML comments that have been inserted into a C# source file. You can use XML-related comment marks within the C# code to specify which comments should be output to the XML file. The XML file can then be used as documentation for your code.

Download the Experience Visual Studio .NET Lab files from the introduction topic.

Contents

Introduction
Creating a New Project in the IDE
Creating the XMLComment.cs Source File
Opening the Project and the Source File Within the IDE
Compiling the Sample
Applying the XSL Template to the XML File
Opening the Final Version of Doc.xml
Closing Out of Lab 2

Introduction

In this hands-on lab you will use the C# compiler to generate an Extensible Markup Language (XML) file from XML comments that have been inserted into a C# source file. You can use XML-related comment marks within the C# code to specify which comments should be output to the XML file.

The XML file can be used as documentation for your code. You can then add new comments or edit existing ones, thus keeping documentation together with the code it refers to. To create an updated record of documentation, you regenerate the XML file.

In this lab, you will:

  • Use the Microsoft Visual Studio .NET Integrated Development Environment (IDE) to create and edit project files
  • Create an XML file (doc.xml)
  • Open the project and source file within the IDE
  • Compile the sample using the MS-DOS command prompt
  • Apply an Extensible Stylesheet Language (XSL) template to the XML file
  • Open the final version of doc.xml

Creating a New Project in the IDE

  1. Click Start, click Programs, click Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET. The IDE Start page appears as in Figure 1.

    Figure 1. Start page in the Visual Studio .NET IDE

    Note   The Start page opens by default when you start the IDE this way. It provides links to the last four projects that you've worked on within the environment, and also provides additional resource links.
    You can change all of the default settings by clicking Tools, clicking Options and then selecting your preferences.
  2. Click File, click New, and then click Project. The New Project window appears as in Figure 2.
  3. In the Project Types pane, click Visual C# Projects, and in the Templates pane, click Empty Project.
  4. In the Name field, type XML Comments, and then choose a location for your project (the default location is used in this lab).
    Note   There is a space between "XML" and "Comments" for the name of this project.
  5. Click OK.

    Figure 2. New Project window

Creating the XMLComment.cs Source File

The XMLComment.cs file is the source file that is used to create the XML document. XML tags and related text are commented upon within the C# code, and an XML document is created from these tags and text when the source file is compiled.

Note   The XML comment mark is new to the C# language. Starting a line with three slashes (///) in front of text tells the compiler that any text following the slashes is an XML comment. Each line that you want to be an XML comment must begin with three slashes. The comments must be formatted with XML tags so that an XML document can be made from them.
  1. Click File and then click Add New Item. The Add New Item window appears as in Figure 3.
  2. In the Categories pane, click Local Project Items, and in the Templates pane, click Code File.
  3. Type XMLComments.cs in the name field.
    Note   There is no space between "XMLComments" for the name of this new item.

    Figure 3. Add New Item window

  4. Click Open.
  5. Type the following code into the page:
    using System;
    
    class XmlElement
    {
       /// <summary>
       ///    Returns the attribute with the given name and
       ///    namespace</summary>
       /// <param name="name">
       ///    The name of the attribute</param>
       /// <param name="ns">
       ///    The namespace of the attribute, or null if
       ///    the attribute has no namespace</param>
       /// <return>
       ///    The attribute value, or null if the attribute
       ///    does not exist</return>
       /// <seealso cref="GetAttr(string,string)"/>
       public string GetAttr(string name, string ns) {
          return "test";
       }
    }
    
  6. Click File and then click Save XMLComments.cs (or click the Save icon). The file is saved to your project folder.
  7. Click File and then click Exit. If the Microsoft Development window appears, click Yes to save changes to your project.

Opening the Project and the Source File Within the IDE

  1. Click Start, click Programs, click Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. Click File, click Open, and then click Project.
  3. Expand C:\Documents and Settings\Administrator\My Documents\Visual Studio Projects\XMLComments.
  4. Click XMLComments.csproj or XMLComments.sln, and then click Open.
    Note   Clicking either file opens the project.

    If the source file does not open in the main window, in the Solution Explorer window, double-click the XMLComments.cs icon as in Figure 4. The source file opens in the main window. Leave the IDE open to complete the following steps.

    Figure 4. IDE view of XMLComments.cs document

    Note   The System namespace is declared at the top of the file. All classes within this namespace are available to the XmlElement class. The XML elements named "param" have attributes named name and ns. These attribute values are passed to the GetAttr() method in the C# code below the comments.

Compiling the Sample

You will use two existing files, make.bat and doc.xsl, in this section. These files must be placed in the XMLComments project folder so that the sample will compile correctly.

Note   The doc.xsl file provides the style sheet template for displaying the doc.xml file in a Web browser, and the make.bat file contains C# compiler options.
  1. Click Start, click Programs, click Accessories, and then click Windows Explorer.
  2. Expand C:\FieldContent\Experience VS.NET\Lab2.
  3. Highlight the doc.xsl and make.bat files, click Edit, and then click Copy.
  4. Expand C:\Documents and Settings\Administrator\My Documents\Visual Studio Projects\XMLComments.
  5. Click Edit, and then click Paste to paste the files info the XMLComments folder.

    You will use the MS-DOS Command Prompt to compile the sample.

  6. In Windows Explorer, expand C:\FieldContent\Experience VS.NET\Lab2.
  7. Double-click Command Prompt.
  8. Type type make.bat and then press ENTER. This displays the contents of the make.bat file on the screen.
    Note   The make.bat file contains the following parameters:
    The csc command invokes the C# compiler.
    The /target option specifies the format of the output file, in this case a library file, or dll (XMLComment.dll).
    The /doc option tells the compiler to create an XML file (doc.xml) from the documentation comments within the source file.
    XMLComment.cs is the source file used by the compiler.
  9. Type make and then press ENTER. The Command Prompt window now looks like the one in Figure 5.
    Note   The doc.xml and XMLComment.dll files are created after using the make command. They are automatically created and saved to the XMLComments project folder. This is the default for C#. You need not specify a new path unless you want to change it.

    Figure 5. The Command Prompt box after making doc.xml

  10. Close the Command Prompt box.

Applying the XSL Template to the XML File

You will now apply the XSL template to the XML file (doc.xml) that you created. You will open the XML and XSL files in the IDE, and then apply the XSL template so that the XML doc can be displayed correctly in a Web browser.

  1. In the IDE, click File and then click Add Existing Item.
  2. Expand C:\Documents and Settings\Administrator\My Documents\Visual Studio Projects\XMLComments.
  3. Click doc.xml and then click Open. The doc.xml file opens in the IDE as in Figure 6.

    Figure 6. Doc.xml in the IDE

    You will now open the raw doc.xml file in the Web browser

  4. Click View, and then click Open With.
  5. Click Iexplore.exe, and then click Open. The raw doc.xml file opens in Microsoft Internet Explorer as in Figure 7.
    Note   Internet Explorer displays unformatted XML files as a series of tags with collapsible "-" signs.

    Figure 7. Doc.xml in Internet Explorer before adding style sheet

  6. To close Internet Explorer, click File and then click Close.
  7. To open the doc.xsl template, in the IDE, click File, and then click Add Existing Item.
  8. Expand C:\Documents and Settings\Administrator\My Documents\Visual Studio Projects\XMLComments.
  9. From the Files of type field, select All Files. This allows access to the doc.xsl file.
  10. Click doc.xsl, and then click Open. The doc.xsl template opens in the IDE as in Figure 8.

    Figure 8. Doc.xsl in the IDE

    Note   The doc.xsl file has a commented processing instruction on the second line, <?xml:stylesheet href="doc.xsl" type="text/xsl"?>. This is the line that will be added to the XML file in the next step.
  11. To apply the doc.xsl template to the doc.xml file, highlight the XML processing instruction from the second line of the doc.xsl template, as shown in Figure 9, click Edit, and then click Copy.

    Figure 9. Style sheet processing instruction in doc.xsl

  12. Click the doc.xml tab.
  13. Insert a blank line between the <?xml version="1.0"?> declaration and the <doc> tag.
  14. Place your cursor on the blank line, click Edit, and then click Paste. The screen appears as shown in Figure 10.

    Figure 10. Doc.xml with style sheet processing instruction

  15. Click File, and then click Save doc.xml.
  16. After you save the document, notice that the colon in the <?xml:stylesheet…?> processing instruction is removed. Place a dash (-) between the terms "xml" and "stylesheet" (without parentheses, as in the second line of Figure 11) so that this processing instruction will work correctly. After you insert the dash, click File, and then click Save doc.xml again.

    Figure 11. Doc.xml with correct style sheet formatting

Opening the Final Version of Doc.xml

You can now view doc.xml in a browser with the style sheet applied. Be sure the doc.xml tab is selected in the IDE.

  1. Click View, and then click Open With.
  2. Click Iexplore.exe, and then click Open. The doc.xml file opens in the browser with the doc.xsl formatting applied as in Figure 12.

    Figure 12. Doc.xml in Internet Explorer with style sheet applied

Closing Out of Lab 2

  1. Click File and then click Close to close Internet Explorer.
  2. Click File and then click Exit to close the IDE.

Other articles and labs in the Experience Visual Studio .NET set include:

Introducing the Visual Studio .NET Lab Series

Lab 1: Hello World

Lab 3: ASP vs. ASP.NET

Lab 4: Server Controls Walkthrough

Lab 5: Using the Visual Basic Upgrade Wizard

Lab 6: Building a Browser-Based Application

Lab 7: Inheritance and Override

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.